PlayOnLinux - User contributions [en]

Components and Functions

2016-02-05T17:56:37Z

Petch: Add missing POL_Call's

Details, use cases, related errors, and more on each component coming soon...

== AdobeAir ==

'''What is it?'''

"The Adobe AIR runtime enables developers to package the same code into native applications and games for Windows and Mac OS desktops as well as iOS and Android devices, reaching over a billion desktop systems and mobile app stores for over 500 million devices."

-from http://get.adobe.com/air/

'''What does it do?'''

Installs the Adobe Air package.

'''When would I need it?'''

Certain Adobe products require this to be installed as a dependency.

'''Script/Shell command:'''

<pre class="playonlinux code">
POL_Call POL_Install_AdobeAir
</pre>

'''Links:'''

<pre class="playonlinux code">
http://get.adobe.com/air/

== amstream ==

POL_Call POL_Install_amstream

== ATI_Black-Screen_Fix ==

POL_Call POL_Install_ATI_Black-Screen_Fix

== atmlib ==

POL_Call POL_Install_atmlib

== cc580 ==

POL_Call POL_Install_cc580

== CentralizedUserDirs ==

POL_Call POL_Install_CentralizedUserDirs

== corefonts ==

'''What is it?'''

"TrueType is an outline font standard developed by Apple and Microsoft in the late 1980s as a competitor to Adobe's Type 1 fonts used in PostScript. It has become the most common format for fonts on both the Mac OS and Microsoft Windows operating systems."

from http://en.wikipedia.org/wiki/TrueType

'''What does it do?'''

Downloads and registers TrueType fonts (TTF). Here is a list of the fonts that will be installed into the given virtual drive:

* andale mono
* arial black
* arial (bold, italic, bold italic)
* comic sans ms (bold)
* courier new (bold, italic, bold italic)
* georgia (bold, italic, bold italic)
* impact
* times new roman (bold, italic, bold italic)
* trebuchet (bold, italic, bold italic)
* verdana (bold, italic, bold italic)
* webdings

'''When would I need it?'''

Any time you experience missing text in an application, this would be the first place you would want to start. This is usually installed by default, though. If this does not work, try '''tahoma''' or '''tahoma2''' from the [http://wiki.playonlinux.com/index.php/The_Configuration_Window Install Components tab], as those are the usual suspects in such acts of font thievery.

'''Script/Shell command:'''

<pre class="playonlinux code">
POL_Call POL_Install_corefonts
</pre>

'''Links:'''

http://en.wikipedia.org/wiki/TrueType

== crypt32 ==

'''What is it?'''

''crypt32'' does quite a few things relating to decrypting/encrypting data. Basic information in the links below.

'''What does it do?'''

"It supports encryption, decryption, and manipulation of certificates and related data structures."

from http://wiki.winehq.org/Crypt32

'''When would I need it?'''

Most of this is taken care of within Wine via the ''builtin'' dll. You may run into times when the native dll is needed, in which case the POL debug log will spit out an error saying that it tried to do something with it and it failed (like ''unhandled exception'' or ''cannot find crypt32.dll'', etc.). If you do happen to run into an error like this, we highly encourage you to report it to https://appdb.winehq.org so that the community there can possibly implement a fix that is native to Wine, eliminating the need for the actual Windows dll.

'''Script/Shell command:'''

<pre class="playonlinux code">
POL_Call POL_Install_crypt32
</pre>

'''Links:'''

http://wiki.winehq.org/Crypt32

== dcom98 ==

POL_Call POL_Install_dcom98

== DirectX ==

=== d3dcompiler_43 ===

POL_Call POL_Install_d3dcompiler_43

=== d3dx10 ===

POL_Call POL_Install_d3dx10

=== d3dx11 ===

POL_Call POL_Install_d3dx11

=== d3dx9 ===

POL_Call POL_Install_d3dx9

=== d3dx9_29 ===

POL_Call POL_Install_d3dx9_29

=== d3dx9_35 ===

POL_Call POL_Install_d3dx9_35

=== d3dx9_36 ===

POL_Call POL_Install_d3dx9_36

=== d3dx9_40 ===

POL_Call POL_Install_d3dx9_40

=== d3dx9_42 ===

POL_Call POL_Install_d3dx9_42

=== d3dx9_43 ===

POL_Call POL_Install_d3dx9_43

=== dinput8 ===

POL_Call POL_Install_dinput8

=== directmusic ===

POL_Call POL_Install_directmusic

=== directplay ===

POL_Call POL_Install_directplay

=== directx9 ===

POL_Call POL_Install_directx9

=== dinput ===

POL_Call POL_Install_dinput

=== dsound ===

POL_Call POL_Install_dsound

=== dxdiag ===

POL_Call POL_Install_dxdiag

=== dxfullsetup ===

POL_Call POL_Install_dxfullsetup

== Desura ==

POL_Call POL_Install_desura

== devenum ==

POL_Call POL_Install_devenum

== DisableCrashDialog ==

POL_Call POL_Install_DisableCrashDialog

== DosboxDrive ==

POL_Call POL_Install_DosboxDrive

== .NET ==

=== POL_Install_dotnet11 ===

=== POL_Install_dotnet11sp1 ===

=== POL_Install_dotnet20 ===

=== POL_Install_dotnet20sp1 ===

=== POL_Install_dotnet20sp2 ===

=== POL_Install_dotnet30 ===

=== POL_Install_dotnet30sp1 ===

=== POL_Install_dotnet35 ===

=== POL_Install_dotnet35sp1 ===

=== POL_Install_dotnet40 ===

== fakeie6 ==

POL_Call POL_Install_fakeie6

== ffdshow ==

POL_Call POL_Install_ffdshow

== flashplayer ==

POL_Call POL_Install_flashplayer

== Flashplayer_ActiveX ==

POL_Call POL_Install_Flashplayer_ActiveX

== FontsSmoothBGR ==

POL_Call POL_Install_FontsSmoothBGR

== FontsSmoothGrayScale ==

POL_Call POL_Install_FontsSmoothGrayScale

== FontsSmoothRGB ==

POL_Call POL_Install_FontsSmoothRGB

== gdiplus ==

POL_Call POL_Install_gdiplus

== gecko ==

POL_Call POL_Install_gecko

== gfwl ==

POL_Call POL_Install_gfwl

== gfwl86 ==

POL_Call POL_Install_gfwl86

== HackSteam ==

POL_Call POL_Install_HackSteam

== ie6 ==

POL_Call POL_Install_ie6

== ie8 ==

POL_Call POL_Install_ie8

== iv50 ==

POL_Call POL_Install_iv50

== linuxtrack-wine ==

POL_Call POL_Install_linuxtrack-wine

== LunaTheme ==

POL_Call POL_Install_LunaTheme

== mdac28 ==

POL_Call POL_Install_mdac28

== mfc ==

=== POL_Install_mfc40 ===

=== POL_Install_mfc42 ===

== Mono ==

=== POL_Install_mono210 ===

=== POL_Install_mono26 ===

=== POL_Install_mono28 ===

== msasn1 ==

POL_Call POL_Install_msasn1

== msls31 ==

POL_Call POL_Install_msls31

== msvc ==

=== POL_Install_msvc100 ===

=== POL_Install_msvc80 ===

=== POL_Install_msvc90 ===

== msxml ==

=== POL_Install_msxml3 ===

=== POL_Install_msxml4 ===

=== POL_Install_msxml6 ===

== nop ==

POL_Call POL_Install_nop

== physx ==

POL_Call POL_Install_physx

== pngfilt ==

POL_Call POL_Install_pngfilt

== PrivateUserDirs ==

POL_Call POL_Install_PrivateUserDirs

== quartz ==

POL_Call POL_Install_quartz

== RegisterFonts ==

POL_Call POL_Install_RegisterFonts

== riched20 ==

=== POL_Install_riched20 ===

=== POL_Install_riched30 ===

== rsc ==

POL_Call POL_Install_rsc

== steam ==

'''What is it?'''

An installer for the game publishing platform Steam.

'''What does it do?'''

Downloads and Installs Steam client.

'''When would I need it?'''

Any time a game requires Steam to run.

'''Script/Shell command:'''

<pre class="playonlinux code">
POL_Call POL_Install_steam
</pre>

'''Links:'''

http://store.steampowered.com/

== steam_flags ==

'''What is it?'''

A helper script for Steam.

'''What does it do?'''

Set registry third-party flags to avoid steam installing them at the game's first launch.

'''When would I need it?'''

To avoid Steam reinstalling POL-installed dependencies (Wine sometimes requires some ''wizardry'' to get things working that the stock installers do not do, and can cause the application not to run if the workaround is overwritten or broken by the default installation being triggered by the Steam client.).

'''Script/Shell command:'''

<pre class="playonlinux code">
POL_Call POL_Install_steam_flags
</pre>

'''Links:'''

https://www.playonlinux.com/en/app-927-POL_Install_steam_flags.html

== tahoma ==

'''What is it?'''

An installer for the Microsoft font ''Tahoma''.

'''What does it do?'''

Downloads and registers ''Tahoma''.

'''When would I need it?'''

Any time the ''Tahoma'' font is needed.

'''Script/Shell command:'''

<pre class="playonlinux code">
POL_Call POL_Install_tahoma
</pre>

'''Links:'''

http://www.microsoft.com/typography/fonts/family.aspx?FID=19

== tahoma2 ==

'''What is it?'''

An alternative installer for the Microsoft font ''Tahoma''.

'''What does it do?'''

Downloads and registers Tahoma, but from a different package.

'''When would I need it?'''

Any time the ''Tahoma'' font is needed, where the regular ''Tahoma'' installer does not work (like Photoshop CS6).

'''Script/Shell command:'''

<pre class="playonlinux code">
POL_Call POL_Install_tahoma2
</pre>

'''Links:'''

http://www.microsoft.com/typography/fonts/family.aspx?FID=19

== ubigamelauncher ==

POL_Call POL_Install_ubigamelauncher

== vbrun6 ==

POL_Call POL_Install_vbrun6

== vcrun ==

=== POL_Install_vcrun2005 ===

=== POL_Install_vcrun2008 ===

=== POL_Install_vcrun2010 ===

=== POL_Install_vcrun2012 ===

=== POL_Install_vcrun2013 ===

=== POL_Install_vcrun6 ===

== VideoDriver ==

POL_Call POL_Install_VideoDriver

== wine64b ==

POL_Call POL_Install_wine64b

== wineasio ==

'''What is it?'''

WineASIO provides an ASIO driver interface from Wine to jack for low-latency audio and advanced audio/MIDI routing.

'''What does it do?'''

Checks for the following:

* Checks that the virtual drive is 32-bit

* Makes sure that the user is part of the ''audio'' group

* Confirms the presence of ''jack'' and ''qjackctl''

Then, if all checks pass, WineASIO is downloaded and registered into that virtual drive.

'''When would I need it?'''

Certain Adobe products require this to be installed as a dependency.

'''Script/Shell command:'''

<pre class="playonlinux code">
POL_Call POL_Install_wineasio
</pre>

'''Links:'''

http://sourceforge.net/projects/wineasio/

== winhttp ==

POL_Call POL_Install_winhttp

== wininet ==

POL_Call POL_Install_wininet

== wintrust ==

POL_Call POL_Install_wintrust

== wmp10 ==

POL_Call POL_Install_wmp10

== wmp9 ==

POL_Call POL_Install_wmp9

== wmpcodecs ==

POL_Call POL_Install_wmpcodecs

== wsh56 ==

POL_Call POL_Install_wsh56

== wsh57 ==

POL_Call POL_Install_wsh57

== xact ==

POL_Call POL_Install_xact

== xinput ==

POL_Call POL_Install_xinput

== xmllite ==

POL_Call POL_Install_xmllite

== xna31 ==

POL_Call POL_Install_xna31

== xna40 ==

POL_Call POL_Install_xna40

== xvid ==

POL_Call POL_Install_xvid

== Other Functions ==

=== POL_Configurator_runparts ===

POL_Call POL_Configurator_runparts

=== POL_Download_retry ===

POL_Call POL_Download_retry

=== POL_Function_FontsSmoothBGR ===

POL_Call POL_Function_FontsSmoothBGR

=== POL_Function_FontsSmoothGrayScale ===

POL_Call POL_Function_FontsSmoothGrayScale

=== POL_Function_FontsSmoothRGB ===

POL_Call POL_Function_FontsSmoothRGB

=== POL_Function_NoCDWarning ===

POL_Call POL_Function_NoCDWarning

=== POL_Function_override_app_dlls ===

POL_Call POL_Function_override_app_dlls

=== POL_Function_OverrideDLL ===

POL_Call POL_Function_OverrideDLL

=== POL_Function_RootCommand ===

POL_Call POL_Function_RootCommand

=== POL_Function_sandbox ===

POL_Call POL_Function_sandbox

=== POL_Function_SetNativeExtension ===

POL_Call POL_Function_SetNativeExtension

=== POL_Function_simplecdscript ===

POL_Call POL_Function_simplecdscript

=== POL_Function_simplescript ===

POL_Call POL_Function_simplescript

=== POL_Function_Sleep ===

POL_Call POL_Function_Sleep

=== POL_Gamefront_Download ===

POL_Call POL_Gamefront_Download

=== POL_GetTool_samba3 ===

POL_Call POL_GetTool_samba3

=== POL_GoG_download ===

POL_Call POL_GoG_download

=== POL_GoG_Extract ===

POL_Call POL_GoG_Extract

=== POL_GoG_install ===

POL_Call POL_GoG_install

=== POL_GoG_setup ===

POL_Call POL_GoG_setup

Troubleshooting Common Problems

2016-01-06T13:44:42Z

Petch: /* Create a symlink */

Here is a list of common errors and possible solutions. Not everything will be here, but this list will get a lot bigger as time goes on, and hopefully, with the help of the community, we can make this list very, very robust.

When trying a possible solution for an issue, please only try '''ONE''' solution at a time, and test to see if it worked.

== p11-kit: couldn't load module: ... ==

=== Error ===

{{Console|p11-kit: couldn't load module: /usr/lib/i386-linux-gnu/pkcs11/p11-kit-trust.so: /usr/lib/i386-linux-gnu/pkcs11/p11-kit-trust.so: cannot open shared object file: No such file or directory}}

=== Who might encounter this error? ===

Mostly users of Debian, Ubuntu, Kubuntu, etc., Mint (and derivatives), 64-bit systems.

=== What causes this error? ===

The 32-bit version of ''p11-kit-trust.so'' is either not installed, or is not located in an area that Wine expected it to be.

=== Common solutions ===

==== Install 32-bit version of p11-kit-trust.so ====

<pre class='code bash'>
sudo apt-get install p11-kit-modules:i386
</pre>

==== Create a symlink ====

(for systems before multiarch feature?)

''found at http://askubuntu.com/a/384018''

<pre class='code bash'>
sudo /usr/local/bin/getlibs -p p11-kit:i386
sudo ln -s /usr/lib32/i386-linux-gnu/pkcs11/p11-kit-trust.so /usr/lib/i386-linux-gnu/pkcs11/p11-kit-trust.so
</pre>

== Error in FS_Check ==

=== Error ===

{{Console|The following file is located on a fuse filesystem. It might prevent wine from working}}

=== Who might encounter this error? ===

Anyone trying to run an executable file in Wine/POL that is located on an NTFS filesystem.

=== What causes this error? ===

Wine can get grumpy with how NTFS, Linux, and Wine interact with each other. This warning is simply there to alert you to this fact. Most of the time, this error can be ignored.

=== Common solutions ===

==== Move executable to a native Linux filesystem ====

Simply move the executable file in question to your native Linux filesystem, and this error will go away. It will only appear when trying to execute a file that is located on a FUSE filesystem.

== Failed to use ICMP ==

=== Error ===

{{Console|err:winediag:IcmpCreateFile Failed to use ICMP (network ping), this requires special permissions.
}}

=== Who might encounter this error? ===

Anyone trying to run an application that wants to ping out. On POSIX-compliant systems, ''ping'' needs admin rights. ''NOTE:'' '''NEVER''' run Wine or POL as root.

=== What causes this error? ===

When a program tries to send an ICMP packet running through POL/Wine, it will fail, as it needs administrative rights, and we never run POL or Wine as ''root'', do we? ;)

=== Common solutions ===

==== Switch to WineBuild ''1.7.45-staging'' or higher ====

There is a fix for this in the Wine-Staging builds found in '''Manage Wine Versions''', so that should be tried first.

==== Give rights to POL's WineBuild ====

In most instances, you will see a command to remedy this. Most of the time, it is missing the final argument, which is the particular instance of Wine that you are running. These solutions work fine for Vanilla Wine, but not POL. For POL, you have to point the particular command to POL's WineBuild for that particular virtual drive.

For instance, '''AION'''.

All of POL's WineBuilds are stored in ~/.PlayOnLinux/wine/

Within this folder, you have different sub-folders for architecture, and then Wine version. In the case of '''AION''':

{{Console|/home/username/.PlayOnLinux/wine/linux-x86/1.7.36}}

Find out which Wine version your application needs:

# Open the Configuration Window
# In the General tab, when your virtual drive is selected, look at the name of the version of Wine in use.

Now, the command you would want to run is:

'''NOTE''': ''Do NOT copy and paste these commands. They need to be modified for your particular situation.''

{{Console|sudo setcap cap_net_raw+epi /home/username/.PlayOnLinux/wine/linux-x86/1.7.36/bin/wine}}

or

{{Console|sudo setcap cap_net_raw+epi /home/username/.PlayOnLinux/wine/linux-x86/1.7.36/bin/wine-preloader}}

'''NOTE:''' ''I have seen both bin/wine and bin/wine-preloader shown in examples, so for posterity, I am including both.''

Essentially, the syntax for this is as follows:

{{Console|sudo setcap cap_net_raw+epi /home/'''username'''/.PlayOnLinux/wine/'''WineArchitecture'''/'''WineVersion'''/bin/wine}}

Replace:

* '''username''' with your current username

* '''Wine Architecture''' with either '''linux-x86''' (32-bit virtual drive) or '''linux-amd64''' (64-bit virtual drive)

* '''Wine Version''' with the '''EXACT''' name listed in the '''Wine dropdown menu''' in the '''General tab''' of the ''' Configuration Window'''

== Error! Files mismatch ==

=== Error ===

{{Console|''someurl''

Error! Files mismatch

Local: ''md5resultexpected''

Server: ''md5resultdownloaded''

Do you want to retry?
}}

=== Who might encounter this error? ===

This can happen to any user on any system. It is also architecture agnostic.

=== What causes this error? ===

When POL scripts use certain API calls, there is a positional argument for the MD5 hash, to make sure that the downloaded file is intact and is not different than what has been tested. If the server hosting a certain file updates or changes the file in question, or if the download fails, the MD5 will be different, and will throw an error.

=== Common solutions ===

==== File bug report with POL ====

If this happens, it is something that the POL team should be made aware of. Please let us know so that we can take measures to correct this issue. As long as we can get the new file successfully, we can grab the MD5 hash and change the script so that this error will not pop up again (of course, if the file changes, this will happen again, and should be reported.).

== The application you are trying to install needs administrator rights... ==

=== Error ===

{{Console|The application you are trying to install needs administrator rights to function correctly.}}

=== Who might encounter this error? ===

Anyone on any distro may see this error

=== What causes this error? ===

Wine does not implement privileges as some Windows applications may expect, so if a program relies on certain aspects of Windows' user rights that Wine does not or cannot implement, it will fail.

=== Common solutions ===

==== File bug report with WineHQ ====

Anything like this should be reported directly to WineHQ's team, as they would need to troubleshoot and possibly develop a workaround to the permissions issue. You can find their bug system here:

* [https://bugs.winehq.org/ WineHQ's Bugzilla]

== League of Legends Stuck on Logo (after Champ Select) ==

=== Error ===

League of Legends simply stalls at the logo after the champion select dialogue.

=== Who might encounter this error? ===

Anyone on any distro may see this error

=== What causes this error? ===

Multiple d3d libraries that come with Wine apparently, according to threads like [https://www.playonlinux.com/en/topic-11344-HOWTO_Fix_League_Of_Legends_stuck_on_Logo_after_champ_select.html this], do not offer the performance that the native d3d libraries do.

=== Common solutions ===

==== Install needed components ====

Instructions adapted from this thread:

[https://www.playonlinux.com/en/topic-11344-HOWTO_Fix_League_Of_Legends_stuck_on_Logo_after_champ_select.html https://www.playonlinux.com/en/topic-11344-HOWTO_Fix_League_Of_Legends_stuck_on_Logo_after_champ_select.html]

# Install in POL: d3dx10, d3dx11, d3dx9 (only d3dx9, not the other d3dx9_etc) and directx9
# It will break your Adobe Air (already installed in the virtual drive). I really don't know why but it does it, so we have to fix, go to Configure Wine, then select the tab Libraries and add the lib "dnsapi" and set it to "builtin, native"

== PlayOnMac: SECUR32_initNTLMSP ntlm_auth was not found or is outdated ==

=== Error ===

{{Console|err:winediag:SECUR32_initNTLMSP ntlm_auth was not found or is outdated. Make sure that ntlm_auth 3.0.25 is in your path. Usually, you can find it in the winbind package of your distribution.}}

=== Who might encounter this error? ===

PlayOnMac users, even if Samba and winbind are installed.

=== What causes this error? ===

PlayOnMac is not reading the correct path for some reason.

=== Common solutions ===

==== Edit PlayOnMac Bash script to properly set path ====

Instructions adapted from this thread:

[https://www.playonlinux.com/en/topic-13072-Dreaded_ntlm_auth.html https://www.playonlinux.com/en/topic-13072-Dreaded_ntlm_auth.html]

# Edit ''/Applications/PlayOnMac.app/Contents/MacOS/playonmac''
# Change ''#!/bin/bash'' to ''#!/bin/bash --login'', save, and try to start PlayOnMac

== No sound (err:module:load_builtin_dll... libasound.so.2...) ==

=== Error ===

{{Console|err:module:load_builtin_dll failed to load .so lib for builtin L"winealsa.drv": libasound.so.2: cannot open shared object file: No such file or directory.}}

=== Who might encounter this error? ===

Any user on any system may experience this.

=== What causes this error? ===

Missing 32-bit library; in this case, ''libasound2''.

=== Common solutions ===

==== Install the 32-bit version of libasound2 ====

Refer to your distro's docs for the package name for that system. 64-bit systems, because of how Wine/POL works, will almost always need the 32-bit version of libraries used for Wine/POL. Multiarch system's with support for package management with mixed-architectures should check manually if this error is coming up (some distros put things in odd places or don't handle multiarch support very well.).

Talk:Troubleshooting Common Problems

2015-12-12T15:29:31Z

Petch: Created page with " This page lists recognizable patterns that can be read off the debug logs, but lacks some introduction explaining how to get debug logs in the first place"

This page lists recognizable patterns that can be read off the debug logs, but lacks some introduction explaining how to get debug logs in the first place

Talk:Graphics Card Drivers

2015-11-01T11:15:26Z

Petch: Created page with " Installing Mesa 32bit is not how you add 32bit support to nVidia proprietary drivers; That requires adding packages like libgl1-mesa-glx:i386 on current Debian Sid for exampl..."

Installing Mesa 32bit is not how you add 32bit support to nVidia proprietary drivers; That requires adding packages like libgl1-mesa-glx:i386 on current Debian Sid for example.
The problem is finding the right package name for each distro and release, since nVidia driver packaging changed a lot :(

Scripting - Chapter 11: List of Functions

2015-10-12T21:18:27Z

Petch: /* POL_SetupWindow_free_presentation (4.0+) */ Same purpose explanation as POL_SetupWindow_presentation

== 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:'''

# Optional --force option to override any cached images
# URL of top image.
# URL of left image.
# 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:'''
<pre class="playonlinux code">
POL_GetSetupImages "http://files.playonlinux.com/resources/setups/AC2/top.jpg" "http://files.playonlinux.com/resources/setups/AC2/left.jpg" "$TITLE"
</pre>

=== 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:'''
<pre class="playonlinux code">
POL_SetupWindow_Init
</pre>

=== 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:'''
<pre class="playonlinux code">
POL_SetupWindow_Close
</pre>

== PlayOnLinux graphical interface ==

{{Warning|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:'''

# Software name (often $TITLE).
# Software publisher.
# Site of the publisher.
# Script author.
# 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:'''
<pre class="playonlinux code">
POL_SetupWindow_presentation "$TITLE" "Mozilla" "http://www.mozilla.com" "SuperPlumus and NSLW" "$PREFIX"
</pre>

=== POL_SetupWindow_free_presentation (4.0+) ===

'''Purpuse:'''

Display a free format introductory screen.

'''Arguments:'''

# Software name (often $TITLE).
# 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:'''
<pre class="playonlinux code">
POL_SetupWindow_free_presentation "$TITLE" "Welcome to Mozilla Firefox installation wizard."
</pre>

=== POL_SetupWindow_message (4.0+) ===

'''Arguments:'''

# Message.
# Title (often $TITLE).

'''Description:'''

Display a message.

'''Example:'''
<pre class="playonlinux code">
POL_SetupWindow_message "Hello world!" "$TITLE"
</pre>

=== check_one - POL_SetupWindow_missing (4.0-4.1.1) ===

'''Arguments for check_one:'''

# Program that must be present.
# 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:'''
<pre class="playonlinux code">
check_one "p7zip" "p7zip"
POL_SetupWindow_missing
</pre>

=== POL_SetupWindow_file (4.0+) ===

'''Arguments:'''

# Message.
# Title (often $TITLE).
# File to display.

'''Description:'''

Display the content of a file.

'''Example:'''
<pre class="playonlinux code">
POL_SetupWindow_file "Changelog" "$TITLE" "$POL_System_TmpDir/changelog.txt"
</pre>

=== POL_SetupWindow_licence (4.0+) ===

'''Arguments:'''

# Message.
# Title (often $TITLE).
# File to display.

'''Description:'''

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

Useful for displaying licenses.

'''Example:'''
<pre class="playonlinux code">
POL_SetupWindow_licence "Licence:" "$TITLE" "$POL_System_TmpDir/licence.txt"
</pre>

=== POL_SetupWindow_pulsebar - POL_SetupWindow_pulse - POL_SetupWindow_set_text (4.0+) ===

'''Arguments for POL_SetupWindow_pulsebar:'''

# Message.
# Title (often $TITLE).

'''Arguments for POL_SetupWindow_pulse:'''

# Percentage.

'''Arguments for POL_SetupWindow_set_text:'''

# 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:'''
<pre class="playonlinux code">
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"
</pre>

=== POL_SetupWindow_wait (4.0+) ===

'''Arguments:'''

# Message.
# Title (often $TITLE).

'''Description:'''

Display an indeterminate progress bar.

'''Example:'''
<pre class="playonlinux code">
POL_SetupWindow_wait "Please wait" "$TITLE"
</pre>

=== POL_SetupWindow_textbox (4.0+) ===

'''Arguments:'''

# Message.
# Title (often $TITLE).
# 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:'''
<pre class="playonlinux code">
POL_SetupWindow_textbox "Votre pseudo :" "$TITLE"
</pre>

=== POL_SetupWindow_textbox_multiline (4.0+) ===

'''Arguments:'''

# Message.
# Title (often $TITLE).
# 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:'''
<pre class="playonlinux code">
POL_SetupWindow_textbox_multiline "Enter a description for the program" "$TITLE"
</pre>

=== POL_SetupWindow_browse (4.0+) ===

'''Arguments:'''

# Message.
# Title (often $TITLE).
# 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:'''
<pre class="playonlinux code">
POL_SetupWindow_browse "Please select the program." "$TITLE"
</pre>

=== POL_SetupWindow_question (4.0+) ===

'''Arguments:'''

# Message.
# 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:'''
<pre class="playonlinux code">
POL_SetupWindow_question "Message" "Title"
</pre>

=== POL_SetupWindow_menu (4.0+) ===

'''Arguments:'''

# Message.
# Title (often $TITLE).
# Available choices.
# 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:'''
<pre class="playonlinux code">
POL_SetupWindow_menu "What's your favorite color?" "$TITLE" "Red~Green~Blue" "~"
</pre>

=== POL_SetupWindow_menu_num (4.0+) ===

'''Arguments:'''

# Message.
# Title (often $TITLE).
# Available choices.
# 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:'''
<pre class="playonlinux code">
POL_SetupWindow_menu_num "What's your favorite color?" "$TITLE" "Red~Green~Blue" "~"
</pre>

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

=== POL_SetupWindow_menu_list (4.0+) ===

'''Arguments:'''

# Message.
# Title (often $TITLE).
# Available choices.
# Separator character (often ~ or -).
# 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:'''
<pre class="playonlinux code">
POL_SetupWindow_menu_list "What's your favorite color?" "$TITLE" "Red~Green~Blue" "~"
</pre>

=== POL_SetupWindow_checkbox_list (4.0+) ===

'''Arguments:'''

# Message.
# Title (often $TITLE).
# Available choices.
# 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:'''
<pre class="playonlinux code">
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
</pre>

=== 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:'''
<pre class="playonlinux code">
POL_SetupWindow_cdrom
</pre>

=== POL_SetupWindow_check_cdrom (4.0+) ===

'''Arguments:'''

# 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:'''
<pre class="playonlinux code">
POL_SetupWindow_check_cdrom "Data/32_icon.ico"
</pre>

=== POL_SetupWindow_InstallMethod (4.0+) ===

'''Arguments:'''

# 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:'''
<pre class="playonlinux code">
POL_SetupWindow_InstallMethod "LOCAL,CD,STEAM"
</pre>

== POL_RequiredVersion (4.0.15+) ==

'''Arguments:'''

# 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, it itself only appeared in PlayOnLinux 4.0.15, and PlayOnLinux 4.0.14 is still the default in some distributions; 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_AdvisedVersion (4.0.15+) ==

'''Arguments:'''

# 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:'''

# Executable filename.
# Launcher name (often $TITLE).
# Optional name of the icon to download from PlayOnLinux website.
# Optional executable arguments.
# 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 [http://linux.die.net/man/7/glob 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 [http://standards.freedesktop.org/menu-spec/latest/apa.html main] and [http://standards.freedesktop.org/menu-spec/latest/apas02.html 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:'''
<pre class="playonlinux code">
POL_Shortcut "firefox.exe" "$TITLE"
</pre>

== POL_Shortcut_InsertBeforeWine (4.0+) ==

'''Arguments:'''

# Launcher name (often $TITLE).
# Command to add.

'''Description:'''

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

'''Example:'''
<pre class="playonlinux code">
POL_Shortcut_InsertBeforeWine "Jedi Knight II" "export __GL_ExtensionStringVersion=17700"
</pre>

== POL_Shortcut_QuietDebug (4.0.17+) ==
'''Arguments:'''

# 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:'''
# Launcher name (often $TITLE).
# 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:'''

# URL to open.

'''Description:'''

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

'''Example:'''
<pre class="playonlinux code">
POL_Browser "http://www.playonlinux.com"
</pre>

== POL_Download (4.0+) ==

'''Arguments:'''

# URL to download.
# (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:'''

# URL to download.
# Expected MD5 digest of the downloaded file
# (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:'''

# 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:'''
<pre class="playonlinux code">
POL_System_TmpCreate "$PREFIX"
</pre>

== POL_System_TmpDelete (4.0+) ==

'''Description:'''

Removes the script's temporary directory.

'''Example:'''
<pre class="playonlinux code">
POL_System_TmpDelete
</pre>

== POL_System_SetArch (4.0+) ==

'''Arguments:'''

# 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:'''
<pre class="playonlinux code">
POL_System_SetArch "auto"
</pre>

== POL_Call (4.0+) ==

'''Arguments:'''

# Function name.
# 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|Components and Functions]]).

'''Prerequisite:'''

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

'''Example:'''
<pre class="playonlinux code">
POL_Call POL_Install_vcrun6
</pre>

== Wine-related functions ==

=== POL_Wine_SelectPrefix (4.0+) ===

'''Arguments:'''

# 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:'''
<pre class="playonlinux code">
POL_Wine_SelectPrefix "$PREFIX"
</pre>

=== POL_Wine_PrefixExists (4.0+) ===

'''Arguments:'''

# 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:'''
<pre class="playonlinux code">
if [ "$(POL_Wine_PrefixExists "$PREFIX")" = "False" ]
then
# The préfixe doesn't exist
fi
</pre>

=== POL_Wine_PrefixCreate (4.0+) ===

'''Arguments:'''

# 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:'''
<pre class="playonlinux code">
POL_Wine_PrefixCreate "1.3.4"
</pre>

=== 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:'''

# 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:'''
<pre class="playonlinux code">
POL_SetupWindow_VMS "128"
</pre>

=== Set_OS (4.0+) ===

'''Arguments:'''

# Windows version to emulate.
# 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:'''
<pre class="playonlinux code">
Set_OS "win2k"
</pre>

=== Set_Managed (4.0+) ===

'''Arguments:'''

# 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:'''
<pre class="playonlinux code">
Set_Managed "Off"
</pre>

=== Set_SoundDriver (4.0+) ===

'''Arguments:'''

# alsa/oss/esd.

'''Description:'''

Set the audio driver Wine will use.

{{Info|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:'''
<pre class="playonlinux code">
Set_SoundDriver "alsa"
</pre>

=== POL_Wine_Direct3D (4.0+) ===

'''Arguments:'''

# Setting to create/modify.
# New setting value.

'''Description:'''

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

'''Allowed values:'''

See [http://wiki.winehq.org/UsefulRegistryKeys WineHQ's Wiki].

'''Prerequisite:'''

The commands POL_Wine_SelectPrefix and POL_Wine_PrefixCreate must have been used beforehand.

'''Example:'''
<pre class="playonlinux code">
POL_Wine_Direct3D "UseGLSL" "disabled"
</pre>

=== POL_Wine_X11Drv (4.0.14+) ===

'''Arguments:'''

# Setting to create/modify.
# New setting value.

'''Description:'''

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

'''Allowed values:'''

See [http://wiki.winehq.org/UsefulRegistryKeys WineHQ's Wiki].

'''Prerequisite:'''

The commands POL_Wine_SelectPrefix and POL_Wine_PrefixCreate must have been used beforehand.

'''Example:'''
<pre class="playonlinux code">
POL_Wine_X11Drv "DXGrab" "Y"
</pre>

=== POL_Wine_DirectSound (4.0+) ===

'''Arguments:'''

# Setting to create/modify.
# New setting value.

'''Description:'''

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

'''Allowed values:'''

See [http://wiki.winehq.org/UsefulRegistryKeys WineHQ's Wiki].

'''Prerequisite:'''

The commands POL_Wine_SelectPrefix and POL_Wine_PrefixCreate must have been used beforehand.

'''Example:'''
<pre class="playonlinux code">
POL_Wine_DirectSound "HardwareAcceleration" "Emulation"
</pre>

=== POL_Wine_DirectInput (4.0+) ===

'''Arguments:'''

# Setting to create/modify.
# New setting value.

'''Description:'''

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

'''Allowed values:'''

See [http://wiki.winehq.org/UsefulRegistryKeys WineHQ's Wiki].

'''Prerequisite:'''

The commands POL_Wine_SelectPrefix and POL_Wine_PrefixCreate must have been used beforehand.

'''Example:'''
<pre class="playonlinux code">
POL_Wine_DirectInput "MouseWarpOverride" "force"
</pre>

=== POL_Wine_GetRegValue (4.0+) ===

'''Arguments:'''

# 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:'''
<pre class="playonlinux code">
VALUE="$(POL_Wine_GetRegValue "MouseWarpOverride")"
</pre>

=== Set_Desktop (4.0+) ===

'''Arguments:'''

# On/Off.
# Virtual desktop width (if it is enabled).
# 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:'''
<pre class="playonlinux code">
Set_Desktop "On" "1024" "768"
</pre>

=== Set_WineWindowTitle (4.0+) ===

'''Arguments:'''

# 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:'''
<pre class="playonlinux code">
Set_WineWindowTitle "$TITLE"
</pre>

=== 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:'''
<pre class="playonlinux code">
POL_Wine_InstallFonts
</pre>

=== 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:'''
<pre class="playonlinux code">
POL_Wine_SetVideoDriver
</pre>

=== POL_Wine_OverrideDLL (4.0+) ===

'''Arguments:'''

# Mode of override.
# 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:'''
<pre class="playonlinux code">
POL_Wine_OverrideDLL "native" "msvcrt"
POL_Wine_OverrideDLL "" "msvcrt" # To disable the DLL
</pre>

=== POL_Wine_OverrideDLL_App (4.0+) ===

'''Arguments:'''

# Executable name.
# Mode of override.
# 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:'''
<pre class="playonlinux code">
POL_Wine_OverrideDLL_App "firefox.exe" "native" "msvcrt"
POL_Wine_OverrideDLL_App "firefox.exe" "" "msvcrt" # To disable the DLL
</pre>

=== POL_Wine_WaitBefore (4.0.15+) ===

'''Arguments:'''

# 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:'''

# 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:'''
<pre class="playonlinux code">
POL_Wine_WaitExit "$TITLE"
</pre>

=== 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:'''
<pre class="playonlinux code">
POL_Wine_reboot
</pre>

== Debugging commands ==

=== POL_Debug_Init (4.0+) ===

'''Description:'''

Start debugging system.

'''Example:'''
<pre class="playonlinux code">
POL_Debug_Init
</pre>

=== POL_Debug_Message (4.0+) ===

'''Arguments:'''

# 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:'''
<pre class="playonlinux code">
POL_Debug_Message "Modifying config.cfg file."
</pre>

=== POL_Debug_Warning (4.0+) ===

'''Arguments:'''

# 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:'''
<pre class="playonlinux code">
POL_Debug_Warning "File config.cfg did not exist, creating one."
</pre>

=== POL_Debug_Error (4.0+) ===

'''Arguments:'''

# 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:'''
<pre class="playonlinux code">
POL_Debug_Error "Error while modifying config.cfg file"
</pre>

=== POL_Debug_Fatal (4.0+) ===

'''Arguments:'''

# Message.

'''Description:'''

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

'''Prerequisite:'''

The command POL_Debug_Init must have been used beforehand.

'''Example:'''
<pre class="playonlinux code">
POL_Debug_Fatal "Error while modifying config.cfg file"
</pre>

'''Previous:''' [[Scripting - Chapter 10: Script Translation|Chapter 10: Script Translation]]

[[Category:Scripting]]

Scripting - Chapter 11: List of Functions

2015-10-12T21:17:31Z

Petch: /* POL_SetupWindow_free_presentation (4.0+) */ Give more details about the usefulness of the statement

== 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:'''

# Optional --force option to override any cached images
# URL of top image.
# URL of left image.
# 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:'''
<pre class="playonlinux code">
POL_GetSetupImages "http://files.playonlinux.com/resources/setups/AC2/top.jpg" "http://files.playonlinux.com/resources/setups/AC2/left.jpg" "$TITLE"
</pre>

=== 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:'''
<pre class="playonlinux code">
POL_SetupWindow_Init
</pre>

=== 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:'''
<pre class="playonlinux code">
POL_SetupWindow_Close
</pre>

== PlayOnLinux graphical interface ==

{{Warning|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:'''

# Software name (often $TITLE).
# Software publisher.
# Site of the publisher.
# Script author.
# 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:'''
<pre class="playonlinux code">
POL_SetupWindow_presentation "$TITLE" "Mozilla" "http://www.mozilla.com" "SuperPlumus and NSLW" "$PREFIX"
</pre>

=== POL_SetupWindow_free_presentation (4.0+) ===

'''Purpuse:'''

Display a free format introductory screen.

'''Arguments:'''

# Software name (often $TITLE).
# 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.

'''Example:'''
<pre class="playonlinux code">
POL_SetupWindow_free_presentation "$TITLE" "Welcome to Mozilla Firefox installation wizard."
</pre>

=== POL_SetupWindow_message (4.0+) ===

'''Arguments:'''

# Message.
# Title (often $TITLE).

'''Description:'''

Display a message.

'''Example:'''
<pre class="playonlinux code">
POL_SetupWindow_message "Hello world!" "$TITLE"
</pre>

=== check_one - POL_SetupWindow_missing (4.0-4.1.1) ===

'''Arguments for check_one:'''

# Program that must be present.
# 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:'''
<pre class="playonlinux code">
check_one "p7zip" "p7zip"
POL_SetupWindow_missing
</pre>

=== POL_SetupWindow_file (4.0+) ===

'''Arguments:'''

# Message.
# Title (often $TITLE).
# File to display.

'''Description:'''

Display the content of a file.

'''Example:'''
<pre class="playonlinux code">
POL_SetupWindow_file "Changelog" "$TITLE" "$POL_System_TmpDir/changelog.txt"
</pre>

=== POL_SetupWindow_licence (4.0+) ===

'''Arguments:'''

# Message.
# Title (often $TITLE).
# File to display.

'''Description:'''

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

Useful for displaying licenses.

'''Example:'''
<pre class="playonlinux code">
POL_SetupWindow_licence "Licence:" "$TITLE" "$POL_System_TmpDir/licence.txt"
</pre>

=== POL_SetupWindow_pulsebar - POL_SetupWindow_pulse - POL_SetupWindow_set_text (4.0+) ===

'''Arguments for POL_SetupWindow_pulsebar:'''

# Message.
# Title (often $TITLE).

'''Arguments for POL_SetupWindow_pulse:'''

# Percentage.

'''Arguments for POL_SetupWindow_set_text:'''

# 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:'''
<pre class="playonlinux code">
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"
</pre>

=== POL_SetupWindow_wait (4.0+) ===

'''Arguments:'''

# Message.
# Title (often $TITLE).

'''Description:'''

Display an indeterminate progress bar.

'''Example:'''
<pre class="playonlinux code">
POL_SetupWindow_wait "Please wait" "$TITLE"
</pre>

=== POL_SetupWindow_textbox (4.0+) ===

'''Arguments:'''

# Message.
# Title (often $TITLE).
# 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:'''
<pre class="playonlinux code">
POL_SetupWindow_textbox "Votre pseudo :" "$TITLE"
</pre>

=== POL_SetupWindow_textbox_multiline (4.0+) ===

'''Arguments:'''

# Message.
# Title (often $TITLE).
# 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:'''
<pre class="playonlinux code">
POL_SetupWindow_textbox_multiline "Enter a description for the program" "$TITLE"
</pre>

=== POL_SetupWindow_browse (4.0+) ===

'''Arguments:'''

# Message.
# Title (often $TITLE).
# 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:'''
<pre class="playonlinux code">
POL_SetupWindow_browse "Please select the program." "$TITLE"
</pre>

=== POL_SetupWindow_question (4.0+) ===

'''Arguments:'''

# Message.
# 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:'''
<pre class="playonlinux code">
POL_SetupWindow_question "Message" "Title"
</pre>

=== POL_SetupWindow_menu (4.0+) ===

'''Arguments:'''

# Message.
# Title (often $TITLE).
# Available choices.
# 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:'''
<pre class="playonlinux code">
POL_SetupWindow_menu "What's your favorite color?" "$TITLE" "Red~Green~Blue" "~"
</pre>

=== POL_SetupWindow_menu_num (4.0+) ===

'''Arguments:'''

# Message.
# Title (often $TITLE).
# Available choices.
# 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:'''
<pre class="playonlinux code">
POL_SetupWindow_menu_num "What's your favorite color?" "$TITLE" "Red~Green~Blue" "~"
</pre>

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

=== POL_SetupWindow_menu_list (4.0+) ===

'''Arguments:'''

# Message.
# Title (often $TITLE).
# Available choices.
# Separator character (often ~ or -).
# 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:'''
<pre class="playonlinux code">
POL_SetupWindow_menu_list "What's your favorite color?" "$TITLE" "Red~Green~Blue" "~"
</pre>

=== POL_SetupWindow_checkbox_list (4.0+) ===

'''Arguments:'''

# Message.
# Title (often $TITLE).
# Available choices.
# 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:'''
<pre class="playonlinux code">
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
</pre>

=== 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:'''
<pre class="playonlinux code">
POL_SetupWindow_cdrom
</pre>

=== POL_SetupWindow_check_cdrom (4.0+) ===

'''Arguments:'''

# 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:'''
<pre class="playonlinux code">
POL_SetupWindow_check_cdrom "Data/32_icon.ico"
</pre>

=== POL_SetupWindow_InstallMethod (4.0+) ===

'''Arguments:'''

# 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:'''
<pre class="playonlinux code">
POL_SetupWindow_InstallMethod "LOCAL,CD,STEAM"
</pre>

== POL_RequiredVersion (4.0.15+) ==

'''Arguments:'''

# 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, it itself only appeared in PlayOnLinux 4.0.15, and PlayOnLinux 4.0.14 is still the default in some distributions; 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_AdvisedVersion (4.0.15+) ==

'''Arguments:'''

# 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:'''

# Executable filename.
# Launcher name (often $TITLE).
# Optional name of the icon to download from PlayOnLinux website.
# Optional executable arguments.
# 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 [http://linux.die.net/man/7/glob 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 [http://standards.freedesktop.org/menu-spec/latest/apa.html main] and [http://standards.freedesktop.org/menu-spec/latest/apas02.html 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:'''
<pre class="playonlinux code">
POL_Shortcut "firefox.exe" "$TITLE"
</pre>

== POL_Shortcut_InsertBeforeWine (4.0+) ==

'''Arguments:'''

# Launcher name (often $TITLE).
# Command to add.

'''Description:'''

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

'''Example:'''
<pre class="playonlinux code">
POL_Shortcut_InsertBeforeWine "Jedi Knight II" "export __GL_ExtensionStringVersion=17700"
</pre>

== POL_Shortcut_QuietDebug (4.0.17+) ==
'''Arguments:'''

# 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:'''
# Launcher name (often $TITLE).
# 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:'''

# URL to open.

'''Description:'''

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

'''Example:'''
<pre class="playonlinux code">
POL_Browser "http://www.playonlinux.com"
</pre>

== POL_Download (4.0+) ==

'''Arguments:'''

# URL to download.
# (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:'''

# URL to download.
# Expected MD5 digest of the downloaded file
# (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:'''

# 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:'''
<pre class="playonlinux code">
POL_System_TmpCreate "$PREFIX"
</pre>

== POL_System_TmpDelete (4.0+) ==

'''Description:'''

Removes the script's temporary directory.

'''Example:'''
<pre class="playonlinux code">
POL_System_TmpDelete
</pre>

== POL_System_SetArch (4.0+) ==

'''Arguments:'''

# 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:'''
<pre class="playonlinux code">
POL_System_SetArch "auto"
</pre>

== POL_Call (4.0+) ==

'''Arguments:'''

# Function name.
# 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|Components and Functions]]).

'''Prerequisite:'''

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

'''Example:'''
<pre class="playonlinux code">
POL_Call POL_Install_vcrun6
</pre>

== Wine-related functions ==

=== POL_Wine_SelectPrefix (4.0+) ===

'''Arguments:'''

# 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:'''
<pre class="playonlinux code">
POL_Wine_SelectPrefix "$PREFIX"
</pre>

=== POL_Wine_PrefixExists (4.0+) ===

'''Arguments:'''

# 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:'''
<pre class="playonlinux code">
if [ "$(POL_Wine_PrefixExists "$PREFIX")" = "False" ]
then
# The préfixe doesn't exist
fi
</pre>

=== POL_Wine_PrefixCreate (4.0+) ===

'''Arguments:'''

# 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:'''
<pre class="playonlinux code">
POL_Wine_PrefixCreate "1.3.4"
</pre>

=== 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:'''

# 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:'''
<pre class="playonlinux code">
POL_SetupWindow_VMS "128"
</pre>

=== Set_OS (4.0+) ===

'''Arguments:'''

# Windows version to emulate.
# 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:'''
<pre class="playonlinux code">
Set_OS "win2k"
</pre>

=== Set_Managed (4.0+) ===

'''Arguments:'''

# 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:'''
<pre class="playonlinux code">
Set_Managed "Off"
</pre>

=== Set_SoundDriver (4.0+) ===

'''Arguments:'''

# alsa/oss/esd.

'''Description:'''

Set the audio driver Wine will use.

{{Info|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:'''
<pre class="playonlinux code">
Set_SoundDriver "alsa"
</pre>

=== POL_Wine_Direct3D (4.0+) ===

'''Arguments:'''

# Setting to create/modify.
# New setting value.

'''Description:'''

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

'''Allowed values:'''

See [http://wiki.winehq.org/UsefulRegistryKeys WineHQ's Wiki].

'''Prerequisite:'''

The commands POL_Wine_SelectPrefix and POL_Wine_PrefixCreate must have been used beforehand.

'''Example:'''
<pre class="playonlinux code">
POL_Wine_Direct3D "UseGLSL" "disabled"
</pre>

=== POL_Wine_X11Drv (4.0.14+) ===

'''Arguments:'''

# Setting to create/modify.
# New setting value.

'''Description:'''

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

'''Allowed values:'''

See [http://wiki.winehq.org/UsefulRegistryKeys WineHQ's Wiki].

'''Prerequisite:'''

The commands POL_Wine_SelectPrefix and POL_Wine_PrefixCreate must have been used beforehand.

'''Example:'''
<pre class="playonlinux code">
POL_Wine_X11Drv "DXGrab" "Y"
</pre>

=== POL_Wine_DirectSound (4.0+) ===

'''Arguments:'''

# Setting to create/modify.
# New setting value.

'''Description:'''

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

'''Allowed values:'''

See [http://wiki.winehq.org/UsefulRegistryKeys WineHQ's Wiki].

'''Prerequisite:'''

The commands POL_Wine_SelectPrefix and POL_Wine_PrefixCreate must have been used beforehand.

'''Example:'''
<pre class="playonlinux code">
POL_Wine_DirectSound "HardwareAcceleration" "Emulation"
</pre>

=== POL_Wine_DirectInput (4.0+) ===

'''Arguments:'''

# Setting to create/modify.
# New setting value.

'''Description:'''

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

'''Allowed values:'''

See [http://wiki.winehq.org/UsefulRegistryKeys WineHQ's Wiki].

'''Prerequisite:'''

The commands POL_Wine_SelectPrefix and POL_Wine_PrefixCreate must have been used beforehand.

'''Example:'''
<pre class="playonlinux code">
POL_Wine_DirectInput "MouseWarpOverride" "force"
</pre>

=== POL_Wine_GetRegValue (4.0+) ===

'''Arguments:'''

# 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:'''
<pre class="playonlinux code">
VALUE="$(POL_Wine_GetRegValue "MouseWarpOverride")"
</pre>

=== Set_Desktop (4.0+) ===

'''Arguments:'''

# On/Off.
# Virtual desktop width (if it is enabled).
# 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:'''
<pre class="playonlinux code">
Set_Desktop "On" "1024" "768"
</pre>

=== Set_WineWindowTitle (4.0+) ===

'''Arguments:'''

# 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:'''
<pre class="playonlinux code">
Set_WineWindowTitle "$TITLE"
</pre>

=== 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:'''
<pre class="playonlinux code">
POL_Wine_InstallFonts
</pre>

=== 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:'''
<pre class="playonlinux code">
POL_Wine_SetVideoDriver
</pre>

=== POL_Wine_OverrideDLL (4.0+) ===

'''Arguments:'''

# Mode of override.
# 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:'''
<pre class="playonlinux code">
POL_Wine_OverrideDLL "native" "msvcrt"
POL_Wine_OverrideDLL "" "msvcrt" # To disable the DLL
</pre>

=== POL_Wine_OverrideDLL_App (4.0+) ===

'''Arguments:'''

# Executable name.
# Mode of override.
# 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:'''
<pre class="playonlinux code">
POL_Wine_OverrideDLL_App "firefox.exe" "native" "msvcrt"
POL_Wine_OverrideDLL_App "firefox.exe" "" "msvcrt" # To disable the DLL
</pre>

=== POL_Wine_WaitBefore (4.0.15+) ===

'''Arguments:'''

# 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:'''

# 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:'''
<pre class="playonlinux code">
POL_Wine_WaitExit "$TITLE"
</pre>

=== 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:'''
<pre class="playonlinux code">
POL_Wine_reboot
</pre>

== Debugging commands ==

=== POL_Debug_Init (4.0+) ===

'''Description:'''

Start debugging system.

'''Example:'''
<pre class="playonlinux code">
POL_Debug_Init
</pre>

=== POL_Debug_Message (4.0+) ===

'''Arguments:'''

# 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:'''
<pre class="playonlinux code">
POL_Debug_Message "Modifying config.cfg file."
</pre>

=== POL_Debug_Warning (4.0+) ===

'''Arguments:'''

# 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:'''
<pre class="playonlinux code">
POL_Debug_Warning "File config.cfg did not exist, creating one."
</pre>

=== POL_Debug_Error (4.0+) ===

'''Arguments:'''

# 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:'''
<pre class="playonlinux code">
POL_Debug_Error "Error while modifying config.cfg file"
</pre>

=== POL_Debug_Fatal (4.0+) ===

'''Arguments:'''

# Message.

'''Description:'''

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

'''Prerequisite:'''

The command POL_Debug_Init must have been used beforehand.

'''Example:'''
<pre class="playonlinux code">
POL_Debug_Fatal "Error while modifying config.cfg file"
</pre>

'''Previous:''' [[Scripting - Chapter 10: Script Translation|Chapter 10: Script Translation]]

[[Category:Scripting]]

Scripting - Chapter 11: List of Functions

2015-10-12T21:12:20Z

Petch: /* POL_SetupWindow_presentation (4.0+) */ Give a longer description of what the statement is used for

== 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:'''

# Optional --force option to override any cached images
# URL of top image.
# URL of left image.
# 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:'''
<pre class="playonlinux code">
POL_GetSetupImages "http://files.playonlinux.com/resources/setups/AC2/top.jpg" "http://files.playonlinux.com/resources/setups/AC2/left.jpg" "$TITLE"
</pre>

=== 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:'''
<pre class="playonlinux code">
POL_SetupWindow_Init
</pre>

=== 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:'''
<pre class="playonlinux code">
POL_SetupWindow_Close
</pre>

== PlayOnLinux graphical interface ==

{{Warning|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:'''

# Software name (often $TITLE).
# Software publisher.
# Site of the publisher.
# Script author.
# 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:'''
<pre class="playonlinux code">
POL_SetupWindow_presentation "$TITLE" "Mozilla" "http://www.mozilla.com" "SuperPlumus and NSLW" "$PREFIX"
</pre>

=== POL_SetupWindow_free_presentation (4.0+) ===

'''Arguments:'''

# Software name (often $TITLE).
# Message.

'''Description:'''

Present the software with more freedom than POL_SetupWindow_presentation.

'''Example:'''
<pre class="playonlinux code">
POL_SetupWindow_free_presentation "$TITLE" "Welcome to Mozilla Firefox installation wizard."
</pre>

=== POL_SetupWindow_message (4.0+) ===

'''Arguments:'''

# Message.
# Title (often $TITLE).

'''Description:'''

Display a message.

'''Example:'''
<pre class="playonlinux code">
POL_SetupWindow_message "Hello world!" "$TITLE"
</pre>

=== check_one - POL_SetupWindow_missing (4.0-4.1.1) ===

'''Arguments for check_one:'''

# Program that must be present.
# 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:'''
<pre class="playonlinux code">
check_one "p7zip" "p7zip"
POL_SetupWindow_missing
</pre>

=== POL_SetupWindow_file (4.0+) ===

'''Arguments:'''

# Message.
# Title (often $TITLE).
# File to display.

'''Description:'''

Display the content of a file.

'''Example:'''
<pre class="playonlinux code">
POL_SetupWindow_file "Changelog" "$TITLE" "$POL_System_TmpDir/changelog.txt"
</pre>

=== POL_SetupWindow_licence (4.0+) ===

'''Arguments:'''

# Message.
# Title (often $TITLE).
# File to display.

'''Description:'''

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

Useful for displaying licenses.

'''Example:'''
<pre class="playonlinux code">
POL_SetupWindow_licence "Licence:" "$TITLE" "$POL_System_TmpDir/licence.txt"
</pre>

=== POL_SetupWindow_pulsebar - POL_SetupWindow_pulse - POL_SetupWindow_set_text (4.0+) ===

'''Arguments for POL_SetupWindow_pulsebar:'''

# Message.
# Title (often $TITLE).

'''Arguments for POL_SetupWindow_pulse:'''

# Percentage.

'''Arguments for POL_SetupWindow_set_text:'''

# 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:'''
<pre class="playonlinux code">
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"
</pre>

=== POL_SetupWindow_wait (4.0+) ===

'''Arguments:'''

# Message.
# Title (often $TITLE).

'''Description:'''

Display an indeterminate progress bar.

'''Example:'''
<pre class="playonlinux code">
POL_SetupWindow_wait "Please wait" "$TITLE"
</pre>

=== POL_SetupWindow_textbox (4.0+) ===

'''Arguments:'''

# Message.
# Title (often $TITLE).
# 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:'''
<pre class="playonlinux code">
POL_SetupWindow_textbox "Votre pseudo :" "$TITLE"
</pre>

=== POL_SetupWindow_textbox_multiline (4.0+) ===

'''Arguments:'''

# Message.
# Title (often $TITLE).
# 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:'''
<pre class="playonlinux code">
POL_SetupWindow_textbox_multiline "Enter a description for the program" "$TITLE"
</pre>

=== POL_SetupWindow_browse (4.0+) ===

'''Arguments:'''

# Message.
# Title (often $TITLE).
# 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:'''
<pre class="playonlinux code">
POL_SetupWindow_browse "Please select the program." "$TITLE"
</pre>

=== POL_SetupWindow_question (4.0+) ===

'''Arguments:'''

# Message.
# 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:'''
<pre class="playonlinux code">
POL_SetupWindow_question "Message" "Title"
</pre>

=== POL_SetupWindow_menu (4.0+) ===

'''Arguments:'''

# Message.
# Title (often $TITLE).
# Available choices.
# 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:'''
<pre class="playonlinux code">
POL_SetupWindow_menu "What's your favorite color?" "$TITLE" "Red~Green~Blue" "~"
</pre>

=== POL_SetupWindow_menu_num (4.0+) ===

'''Arguments:'''

# Message.
# Title (often $TITLE).
# Available choices.
# 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:'''
<pre class="playonlinux code">
POL_SetupWindow_menu_num "What's your favorite color?" "$TITLE" "Red~Green~Blue" "~"
</pre>

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

=== POL_SetupWindow_menu_list (4.0+) ===

'''Arguments:'''

# Message.
# Title (often $TITLE).
# Available choices.
# Separator character (often ~ or -).
# 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:'''
<pre class="playonlinux code">
POL_SetupWindow_menu_list "What's your favorite color?" "$TITLE" "Red~Green~Blue" "~"
</pre>

=== POL_SetupWindow_checkbox_list (4.0+) ===

'''Arguments:'''

# Message.
# Title (often $TITLE).
# Available choices.
# 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:'''
<pre class="playonlinux code">
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
</pre>

=== 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:'''
<pre class="playonlinux code">
POL_SetupWindow_cdrom
</pre>

=== POL_SetupWindow_check_cdrom (4.0+) ===

'''Arguments:'''

# 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:'''
<pre class="playonlinux code">
POL_SetupWindow_check_cdrom "Data/32_icon.ico"
</pre>

=== POL_SetupWindow_InstallMethod (4.0+) ===

'''Arguments:'''

# 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:'''
<pre class="playonlinux code">
POL_SetupWindow_InstallMethod "LOCAL,CD,STEAM"
</pre>

== POL_RequiredVersion (4.0.15+) ==

'''Arguments:'''

# 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, it itself only appeared in PlayOnLinux 4.0.15, and PlayOnLinux 4.0.14 is still the default in some distributions; 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_AdvisedVersion (4.0.15+) ==

'''Arguments:'''

# 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:'''

# Executable filename.
# Launcher name (often $TITLE).
# Optional name of the icon to download from PlayOnLinux website.
# Optional executable arguments.
# 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 [http://linux.die.net/man/7/glob 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 [http://standards.freedesktop.org/menu-spec/latest/apa.html main] and [http://standards.freedesktop.org/menu-spec/latest/apas02.html 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:'''
<pre class="playonlinux code">
POL_Shortcut "firefox.exe" "$TITLE"
</pre>

== POL_Shortcut_InsertBeforeWine (4.0+) ==

'''Arguments:'''

# Launcher name (often $TITLE).
# Command to add.

'''Description:'''

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

'''Example:'''
<pre class="playonlinux code">
POL_Shortcut_InsertBeforeWine "Jedi Knight II" "export __GL_ExtensionStringVersion=17700"
</pre>

== POL_Shortcut_QuietDebug (4.0.17+) ==
'''Arguments:'''

# 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:'''
# Launcher name (often $TITLE).
# 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:'''

# URL to open.

'''Description:'''

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

'''Example:'''
<pre class="playonlinux code">
POL_Browser "http://www.playonlinux.com"
</pre>

== POL_Download (4.0+) ==

'''Arguments:'''

# URL to download.
# (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:'''

# URL to download.
# Expected MD5 digest of the downloaded file
# (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:'''

# 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:'''
<pre class="playonlinux code">
POL_System_TmpCreate "$PREFIX"
</pre>

== POL_System_TmpDelete (4.0+) ==

'''Description:'''

Removes the script's temporary directory.

'''Example:'''
<pre class="playonlinux code">
POL_System_TmpDelete
</pre>

== POL_System_SetArch (4.0+) ==

'''Arguments:'''

# 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:'''
<pre class="playonlinux code">
POL_System_SetArch "auto"
</pre>

== POL_Call (4.0+) ==

'''Arguments:'''

# Function name.
# 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|Components and Functions]]).

'''Prerequisite:'''

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

'''Example:'''
<pre class="playonlinux code">
POL_Call POL_Install_vcrun6
</pre>

== Wine-related functions ==

=== POL_Wine_SelectPrefix (4.0+) ===

'''Arguments:'''

# 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:'''
<pre class="playonlinux code">
POL_Wine_SelectPrefix "$PREFIX"
</pre>

=== POL_Wine_PrefixExists (4.0+) ===

'''Arguments:'''

# 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:'''
<pre class="playonlinux code">
if [ "$(POL_Wine_PrefixExists "$PREFIX")" = "False" ]
then
# The préfixe doesn't exist
fi
</pre>

=== POL_Wine_PrefixCreate (4.0+) ===

'''Arguments:'''

# 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:'''
<pre class="playonlinux code">
POL_Wine_PrefixCreate "1.3.4"
</pre>

=== 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:'''

# 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:'''
<pre class="playonlinux code">
POL_SetupWindow_VMS "128"
</pre>

=== Set_OS (4.0+) ===

'''Arguments:'''

# Windows version to emulate.
# 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:'''
<pre class="playonlinux code">
Set_OS "win2k"
</pre>

=== Set_Managed (4.0+) ===

'''Arguments:'''

# 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:'''
<pre class="playonlinux code">
Set_Managed "Off"
</pre>

=== Set_SoundDriver (4.0+) ===

'''Arguments:'''

# alsa/oss/esd.

'''Description:'''

Set the audio driver Wine will use.

{{Info|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:'''
<pre class="playonlinux code">
Set_SoundDriver "alsa"
</pre>

=== POL_Wine_Direct3D (4.0+) ===

'''Arguments:'''

# Setting to create/modify.
# New setting value.

'''Description:'''

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

'''Allowed values:'''

See [http://wiki.winehq.org/UsefulRegistryKeys WineHQ's Wiki].

'''Prerequisite:'''

The commands POL_Wine_SelectPrefix and POL_Wine_PrefixCreate must have been used beforehand.

'''Example:'''
<pre class="playonlinux code">
POL_Wine_Direct3D "UseGLSL" "disabled"
</pre>

=== POL_Wine_X11Drv (4.0.14+) ===

'''Arguments:'''

# Setting to create/modify.
# New setting value.

'''Description:'''

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

'''Allowed values:'''

See [http://wiki.winehq.org/UsefulRegistryKeys WineHQ's Wiki].

'''Prerequisite:'''

The commands POL_Wine_SelectPrefix and POL_Wine_PrefixCreate must have been used beforehand.

'''Example:'''
<pre class="playonlinux code">
POL_Wine_X11Drv "DXGrab" "Y"
</pre>

=== POL_Wine_DirectSound (4.0+) ===

'''Arguments:'''

# Setting to create/modify.
# New setting value.

'''Description:'''

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

'''Allowed values:'''

See [http://wiki.winehq.org/UsefulRegistryKeys WineHQ's Wiki].

'''Prerequisite:'''

The commands POL_Wine_SelectPrefix and POL_Wine_PrefixCreate must have been used beforehand.

'''Example:'''
<pre class="playonlinux code">
POL_Wine_DirectSound "HardwareAcceleration" "Emulation"
</pre>

=== POL_Wine_DirectInput (4.0+) ===

'''Arguments:'''

# Setting to create/modify.
# New setting value.

'''Description:'''

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

'''Allowed values:'''

See [http://wiki.winehq.org/UsefulRegistryKeys WineHQ's Wiki].

'''Prerequisite:'''

The commands POL_Wine_SelectPrefix and POL_Wine_PrefixCreate must have been used beforehand.

'''Example:'''
<pre class="playonlinux code">
POL_Wine_DirectInput "MouseWarpOverride" "force"
</pre>

=== POL_Wine_GetRegValue (4.0+) ===

'''Arguments:'''

# 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:'''
<pre class="playonlinux code">
VALUE="$(POL_Wine_GetRegValue "MouseWarpOverride")"
</pre>

=== Set_Desktop (4.0+) ===

'''Arguments:'''

# On/Off.
# Virtual desktop width (if it is enabled).
# 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:'''
<pre class="playonlinux code">
Set_Desktop "On" "1024" "768"
</pre>

=== Set_WineWindowTitle (4.0+) ===

'''Arguments:'''

# 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:'''
<pre class="playonlinux code">
Set_WineWindowTitle "$TITLE"
</pre>

=== 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:'''
<pre class="playonlinux code">
POL_Wine_InstallFonts
</pre>

=== 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:'''
<pre class="playonlinux code">
POL_Wine_SetVideoDriver
</pre>

=== POL_Wine_OverrideDLL (4.0+) ===

'''Arguments:'''

# Mode of override.
# 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:'''
<pre class="playonlinux code">
POL_Wine_OverrideDLL "native" "msvcrt"
POL_Wine_OverrideDLL "" "msvcrt" # To disable the DLL
</pre>

=== POL_Wine_OverrideDLL_App (4.0+) ===

'''Arguments:'''

# Executable name.
# Mode of override.
# 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:'''
<pre class="playonlinux code">
POL_Wine_OverrideDLL_App "firefox.exe" "native" "msvcrt"
POL_Wine_OverrideDLL_App "firefox.exe" "" "msvcrt" # To disable the DLL
</pre>

=== POL_Wine_WaitBefore (4.0.15+) ===

'''Arguments:'''

# 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:'''

# 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:'''
<pre class="playonlinux code">
POL_Wine_WaitExit "$TITLE"
</pre>

=== 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:'''
<pre class="playonlinux code">
POL_Wine_reboot
</pre>

== Debugging commands ==

=== POL_Debug_Init (4.0+) ===

'''Description:'''

Start debugging system.

'''Example:'''
<pre class="playonlinux code">
POL_Debug_Init
</pre>

=== POL_Debug_Message (4.0+) ===

'''Arguments:'''

# 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:'''
<pre class="playonlinux code">
POL_Debug_Message "Modifying config.cfg file."
</pre>

=== POL_Debug_Warning (4.0+) ===

'''Arguments:'''

# 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:'''
<pre class="playonlinux code">
POL_Debug_Warning "File config.cfg did not exist, creating one."
</pre>

=== POL_Debug_Error (4.0+) ===

'''Arguments:'''

# 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:'''
<pre class="playonlinux code">
POL_Debug_Error "Error while modifying config.cfg file"
</pre>

=== POL_Debug_Fatal (4.0+) ===

'''Arguments:'''

# Message.

'''Description:'''

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

'''Prerequisite:'''

The command POL_Debug_Init must have been used beforehand.

'''Example:'''
<pre class="playonlinux code">
POL_Debug_Fatal "Error while modifying config.cfg file"
</pre>

'''Previous:''' [[Scripting - Chapter 10: Script Translation|Chapter 10: Script Translation]]

[[Category:Scripting]]

Scripting - Chapter 11: List of Functions

2015-10-12T04:40:17Z

Petch: /* POL_GetSetupImages (4.0+) */

== 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:'''

# Optional --force option to override any cached images
# URL of top image.
# URL of left image.
# 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:'''
<pre class="playonlinux code">
POL_GetSetupImages "http://files.playonlinux.com/resources/setups/AC2/top.jpg" "http://files.playonlinux.com/resources/setups/AC2/left.jpg" "$TITLE"
</pre>

=== 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:'''
<pre class="playonlinux code">
POL_SetupWindow_Init
</pre>

=== 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:'''
<pre class="playonlinux code">
POL_SetupWindow_Close
</pre>

== PlayOnLinux graphical interface ==

{{Warning|All the functions below need the command POL_SetupWindow_Init to be executed beforehand.}}

=== POL_SetupWindow_presentation (4.0+) ===

'''Arguments:'''

# Software name (often $TITLE).
# Software publisher.
# Site of the publisher.
# Script author.
# Prefix name (usually $PREFIX).

'''Description:'''

Present the software.

'''Example:'''
<pre class="playonlinux code">
POL_SetupWindow_presentation "$TITLE" "Mozilla" "http://www.mozilla.com" "SuperPlumus and NSLW" "$PREFIX"
</pre>

=== POL_SetupWindow_free_presentation (4.0+) ===

'''Arguments:'''

# Software name (often $TITLE).
# Message.

'''Description:'''

Present the software with more freedom than POL_SetupWindow_presentation.

'''Example:'''
<pre class="playonlinux code">
POL_SetupWindow_free_presentation "$TITLE" "Welcome to Mozilla Firefox installation wizard."
</pre>

=== POL_SetupWindow_message (4.0+) ===

'''Arguments:'''

# Message.
# Title (often $TITLE).

'''Description:'''

Display a message.

'''Example:'''
<pre class="playonlinux code">
POL_SetupWindow_message "Hello world!" "$TITLE"
</pre>

=== check_one - POL_SetupWindow_missing (4.0-4.1.1) ===

'''Arguments for check_one:'''

# Program that must be present.
# 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:'''
<pre class="playonlinux code">
check_one "p7zip" "p7zip"
POL_SetupWindow_missing
</pre>

=== POL_SetupWindow_file (4.0+) ===

'''Arguments:'''

# Message.
# Title (often $TITLE).
# File to display.

'''Description:'''

Display the content of a file.

'''Example:'''
<pre class="playonlinux code">
POL_SetupWindow_file "Changelog" "$TITLE" "$POL_System_TmpDir/changelog.txt"
</pre>

=== POL_SetupWindow_licence (4.0+) ===

'''Arguments:'''

# Message.
# Title (often $TITLE).
# File to display.

'''Description:'''

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

Useful for displaying licenses.

'''Example:'''
<pre class="playonlinux code">
POL_SetupWindow_licence "Licence:" "$TITLE" "$POL_System_TmpDir/licence.txt"
</pre>

=== POL_SetupWindow_pulsebar - POL_SetupWindow_pulse - POL_SetupWindow_set_text (4.0+) ===

'''Arguments for POL_SetupWindow_pulsebar:'''

# Message.
# Title (often $TITLE).

'''Arguments for POL_SetupWindow_pulse:'''

# Percentage.

'''Arguments for POL_SetupWindow_set_text:'''

# 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:'''
<pre class="playonlinux code">
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"
</pre>

=== POL_SetupWindow_wait (4.0+) ===

'''Arguments:'''

# Message.
# Title (often $TITLE).

'''Description:'''

Display an indeterminate progress bar.

'''Example:'''
<pre class="playonlinux code">
POL_SetupWindow_wait "Please wait" "$TITLE"
</pre>

=== POL_SetupWindow_textbox (4.0+) ===

'''Arguments:'''

# Message.
# Title (often $TITLE).
# 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:'''
<pre class="playonlinux code">
POL_SetupWindow_textbox "Votre pseudo :" "$TITLE"
</pre>

=== POL_SetupWindow_textbox_multiline (4.0+) ===

'''Arguments:'''

# Message.
# Title (often $TITLE).
# 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:'''
<pre class="playonlinux code">
POL_SetupWindow_textbox_multiline "Enter a description for the program" "$TITLE"
</pre>

=== POL_SetupWindow_browse (4.0+) ===

'''Arguments:'''

# Message.
# Title (often $TITLE).
# 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:'''
<pre class="playonlinux code">
POL_SetupWindow_browse "Please select the program." "$TITLE"
</pre>

=== POL_SetupWindow_question (4.0+) ===

'''Arguments:'''

# Message.
# 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:'''
<pre class="playonlinux code">
POL_SetupWindow_question "Message" "Title"
</pre>

=== POL_SetupWindow_menu (4.0+) ===

'''Arguments:'''

# Message.
# Title (often $TITLE).
# Available choices.
# 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:'''
<pre class="playonlinux code">
POL_SetupWindow_menu "What's your favorite color?" "$TITLE" "Red~Green~Blue" "~"
</pre>

=== POL_SetupWindow_menu_num (4.0+) ===

'''Arguments:'''

# Message.
# Title (often $TITLE).
# Available choices.
# 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:'''
<pre class="playonlinux code">
POL_SetupWindow_menu_num "What's your favorite color?" "$TITLE" "Red~Green~Blue" "~"
</pre>

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

=== POL_SetupWindow_menu_list (4.0+) ===

'''Arguments:'''

# Message.
# Title (often $TITLE).
# Available choices.
# Separator character (often ~ or -).
# 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:'''
<pre class="playonlinux code">
POL_SetupWindow_menu_list "What's your favorite color?" "$TITLE" "Red~Green~Blue" "~"
</pre>

=== POL_SetupWindow_checkbox_list (4.0+) ===

'''Arguments:'''

# Message.
# Title (often $TITLE).
# Available choices.
# 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:'''
<pre class="playonlinux code">
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
</pre>

=== 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:'''
<pre class="playonlinux code">
POL_SetupWindow_cdrom
</pre>

=== POL_SetupWindow_check_cdrom (4.0+) ===

'''Arguments:'''

# 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:'''
<pre class="playonlinux code">
POL_SetupWindow_check_cdrom "Data/32_icon.ico"
</pre>

=== POL_SetupWindow_InstallMethod (4.0+) ===

'''Arguments:'''

# 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:'''
<pre class="playonlinux code">
POL_SetupWindow_InstallMethod "LOCAL,CD,STEAM"
</pre>

== POL_RequiredVersion (4.0.15+) ==

'''Arguments:'''

# 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, it itself only appeared in PlayOnLinux 4.0.15, and PlayOnLinux 4.0.14 is still the default in some distributions; 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_AdvisedVersion (4.0.15+) ==

'''Arguments:'''

# 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:'''

# Executable filename.
# Launcher name (often $TITLE).
# Optional name of the icon to download from PlayOnLinux website.
# Optional executable arguments.
# 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 [http://linux.die.net/man/7/glob 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 [http://standards.freedesktop.org/menu-spec/latest/apa.html main] and [http://standards.freedesktop.org/menu-spec/latest/apas02.html 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:'''
<pre class="playonlinux code">
POL_Shortcut "firefox.exe" "$TITLE"
</pre>

== POL_Shortcut_InsertBeforeWine (4.0+) ==

'''Arguments:'''

# Launcher name (often $TITLE).
# Command to add.

'''Description:'''

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

'''Example:'''
<pre class="playonlinux code">
POL_Shortcut_InsertBeforeWine "Jedi Knight II" "export __GL_ExtensionStringVersion=17700"
</pre>

== POL_Shortcut_QuietDebug (4.0.17+) ==
'''Arguments:'''

# 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:'''
# Launcher name (often $TITLE).
# 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:'''

# URL to open.

'''Description:'''

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

'''Example:'''
<pre class="playonlinux code">
POL_Browser "http://www.playonlinux.com"
</pre>

== POL_Download (4.0+) ==

'''Arguments:'''

# URL to download.
# (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:'''

# URL to download.
# Expected MD5 digest of the downloaded file
# (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:'''

# 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:'''
<pre class="playonlinux code">
POL_System_TmpCreate "$PREFIX"
</pre>

== POL_System_TmpDelete (4.0+) ==

'''Description:'''

Removes the script's temporary directory.

'''Example:'''
<pre class="playonlinux code">
POL_System_TmpDelete
</pre>

== POL_System_SetArch (4.0+) ==

'''Arguments:'''

# 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:'''
<pre class="playonlinux code">
POL_System_SetArch "auto"
</pre>

== POL_Call (4.0+) ==

'''Arguments:'''

# Function name.
# 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|Components and Functions]]).

'''Prerequisite:'''

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

'''Example:'''
<pre class="playonlinux code">
POL_Call POL_Install_vcrun6
</pre>

== Wine-related functions ==

=== POL_Wine_SelectPrefix (4.0+) ===

'''Arguments:'''

# 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:'''
<pre class="playonlinux code">
POL_Wine_SelectPrefix "$PREFIX"
</pre>

=== POL_Wine_PrefixExists (4.0+) ===

'''Arguments:'''

# 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:'''
<pre class="playonlinux code">
if [ "$(POL_Wine_PrefixExists "$PREFIX")" = "False" ]
then
# The préfixe doesn't exist
fi
</pre>

=== POL_Wine_PrefixCreate (4.0+) ===

'''Arguments:'''

# 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:'''
<pre class="playonlinux code">
POL_Wine_PrefixCreate "1.3.4"
</pre>

=== 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:'''

# 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:'''
<pre class="playonlinux code">
POL_SetupWindow_VMS "128"
</pre>

=== Set_OS (4.0+) ===

'''Arguments:'''

# Windows version to emulate.
# 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:'''
<pre class="playonlinux code">
Set_OS "win2k"
</pre>

=== Set_Managed (4.0+) ===

'''Arguments:'''

# 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:'''
<pre class="playonlinux code">
Set_Managed "Off"
</pre>

=== Set_SoundDriver (4.0+) ===

'''Arguments:'''

# alsa/oss/esd.

'''Description:'''

Set the audio driver Wine will use.

{{Info|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:'''
<pre class="playonlinux code">
Set_SoundDriver "alsa"
</pre>

=== POL_Wine_Direct3D (4.0+) ===

'''Arguments:'''

# Setting to create/modify.
# New setting value.

'''Description:'''

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

'''Allowed values:'''

See [http://wiki.winehq.org/UsefulRegistryKeys WineHQ's Wiki].

'''Prerequisite:'''

The commands POL_Wine_SelectPrefix and POL_Wine_PrefixCreate must have been used beforehand.

'''Example:'''
<pre class="playonlinux code">
POL_Wine_Direct3D "UseGLSL" "disabled"
</pre>

=== POL_Wine_X11Drv (4.0.14+) ===

'''Arguments:'''

# Setting to create/modify.
# New setting value.

'''Description:'''

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

'''Allowed values:'''

See [http://wiki.winehq.org/UsefulRegistryKeys WineHQ's Wiki].

'''Prerequisite:'''

The commands POL_Wine_SelectPrefix and POL_Wine_PrefixCreate must have been used beforehand.

'''Example:'''
<pre class="playonlinux code">
POL_Wine_X11Drv "DXGrab" "Y"
</pre>

=== POL_Wine_DirectSound (4.0+) ===

'''Arguments:'''

# Setting to create/modify.
# New setting value.

'''Description:'''

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

'''Allowed values:'''

See [http://wiki.winehq.org/UsefulRegistryKeys WineHQ's Wiki].

'''Prerequisite:'''

The commands POL_Wine_SelectPrefix and POL_Wine_PrefixCreate must have been used beforehand.

'''Example:'''
<pre class="playonlinux code">
POL_Wine_DirectSound "HardwareAcceleration" "Emulation"
</pre>

=== POL_Wine_DirectInput (4.0+) ===

'''Arguments:'''

# Setting to create/modify.
# New setting value.

'''Description:'''

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

'''Allowed values:'''

See [http://wiki.winehq.org/UsefulRegistryKeys WineHQ's Wiki].

'''Prerequisite:'''

The commands POL_Wine_SelectPrefix and POL_Wine_PrefixCreate must have been used beforehand.

'''Example:'''
<pre class="playonlinux code">
POL_Wine_DirectInput "MouseWarpOverride" "force"
</pre>

=== POL_Wine_GetRegValue (4.0+) ===

'''Arguments:'''

# 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:'''
<pre class="playonlinux code">
VALUE="$(POL_Wine_GetRegValue "MouseWarpOverride")"
</pre>

=== Set_Desktop (4.0+) ===

'''Arguments:'''

# On/Off.
# Virtual desktop width (if it is enabled).
# 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:'''
<pre class="playonlinux code">
Set_Desktop "On" "1024" "768"
</pre>

=== Set_WineWindowTitle (4.0+) ===

'''Arguments:'''

# 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:'''
<pre class="playonlinux code">
Set_WineWindowTitle "$TITLE"
</pre>

=== 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:'''
<pre class="playonlinux code">
POL_Wine_InstallFonts
</pre>

=== 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:'''
<pre class="playonlinux code">
POL_Wine_SetVideoDriver
</pre>

=== POL_Wine_OverrideDLL (4.0+) ===

'''Arguments:'''

# Mode of override.
# 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:'''
<pre class="playonlinux code">
POL_Wine_OverrideDLL "native" "msvcrt"
POL_Wine_OverrideDLL "" "msvcrt" # To disable the DLL
</pre>

=== POL_Wine_OverrideDLL_App (4.0+) ===

'''Arguments:'''

# Executable name.
# Mode of override.
# 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:'''
<pre class="playonlinux code">
POL_Wine_OverrideDLL_App "firefox.exe" "native" "msvcrt"
POL_Wine_OverrideDLL_App "firefox.exe" "" "msvcrt" # To disable the DLL
</pre>

=== POL_Wine_WaitBefore (4.0.15+) ===

'''Arguments:'''

# 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:'''

# 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:'''
<pre class="playonlinux code">
POL_Wine_WaitExit "$TITLE"
</pre>

=== 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:'''
<pre class="playonlinux code">
POL_Wine_reboot
</pre>

== Debugging commands ==

=== POL_Debug_Init (4.0+) ===

'''Description:'''

Start debugging system.

'''Example:'''
<pre class="playonlinux code">
POL_Debug_Init
</pre>

=== POL_Debug_Message (4.0+) ===

'''Arguments:'''

# 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:'''
<pre class="playonlinux code">
POL_Debug_Message "Modifying config.cfg file."
</pre>

=== POL_Debug_Warning (4.0+) ===

'''Arguments:'''

# 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:'''
<pre class="playonlinux code">
POL_Debug_Warning "File config.cfg did not exist, creating one."
</pre>

=== POL_Debug_Error (4.0+) ===

'''Arguments:'''

# 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:'''
<pre class="playonlinux code">
POL_Debug_Error "Error while modifying config.cfg file"
</pre>

=== POL_Debug_Fatal (4.0+) ===

'''Arguments:'''

# Message.

'''Description:'''

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

'''Prerequisite:'''

The command POL_Debug_Init must have been used beforehand.

'''Example:'''
<pre class="playonlinux code">
POL_Debug_Fatal "Error while modifying config.cfg file"
</pre>

'''Previous:''' [[Scripting - Chapter 10: Script Translation|Chapter 10: Script Translation]]

[[Category:Scripting]]

How to Contribute a Script

2015-10-12T04:33:40Z

Petch: /* What to do after you have tested your script */ Typo

== So, you have a script that you want to submit to PlayOnLinux? ==

There are a few things that should be followed, as far as our standards for icons, resources for install scripts, posting here for help or submitting to us for publication, and info that make this process more standardized.

== Static Checks ==
Even before running your script, you can test it for common (or not so common) mistakes using static analysers:

- http://www.shellcheck.net/ detects Bash scripting issues; It's not PlayOnLinux specific, but since PlayOnLinux scripts are a special case of Bash scripts, it can still be very useful;

- git clone the [https://github.com/PlayOnLinux/PlayOnLinux_Tools PlayOnLinux Tools] repository and run the script_checker.sh (from the PlayOnLinux_ScriptChecker subdirectory) on your script; That one will detect several PlayOnLinux mistakes, specially deprecated style issues.

== Testing, testing, testing ==

It is very important that you test your scripts thoroughly '''before''' trying to contribute them to the actual system. Although, please do feel free to post your script in the forum if you need help or want a review of it. Scripts that obviously have not been tested (because of spelling/syntax errors, non-existent Wine versions, etc..) will not be accepted and will be deleted from the contribution section, requesting that the author post in the forums for help correcting the script.

For instance, if your script has a WINEVERSION set to, say "4.2.3", it is apparent that the script was never tested to work correctly, because that Wine version does not exist. Things like this will result in deletion of the Script Contribution entry, and you will be requested to post in the forums to get the script set up correctly.

== Content of your posts in the forum (''Your Creations'' section) ==

Please use the following tips to help make the posts here more standardized:

* Make the title of your post something like:

<pre>
[Script] name of script
</pre>

* Post the following information in your post in this order:

# Description of the program (just a basic rundown of what it does)
# Anything you had to do or install OUTSIDE of Wine or PlayOnLinux to make it work
# Any extra notes about installation, or errors that it throws (if any)
# Contents of script

== Screenshot requirements ==

When submitting a screenshot, post them in your original post, reply to your own post with either the link to your screenshots, or just paste the screenshots into the post (we can download them and upload to our server.).

Also, do not submit screenshots with your background or desktop. Full-screen, program-only screenshots, unless you are posting the screenshots for troubleshooting of a related issue. What this means:

* Make sure that you are only taking a screenshot of the program related to this script.
* Window decorations are OK, as long as the program is the main feature of the picture.
* No lewd, pornographic, or otherwise controversial screenshots of ANYTHING (this will result in negative action without question.).
* Be sure to take screenshots of the game ACTUALLY running; no install shots.
* Though 1 screenshot works, we prefer 2. 3 is what we really like to see.
* Legible, fairly hi-def shots; no fuzzy text, not stretched/smashed, not distorted.

== Icons and install resources ==

So, there are 4 different icons and pictures that are desired for the script. They are listed as follows with their EXACT dimensions and file type requirements:

{{Warning|Do not forget to add the file extension to the name.}}

''' The icon that will be used for the installed program: '''
* Name: ''nameofprogram''-48x48
* File Type: PNG, JPEG
* Size: 48x48
''' The icon that will be used in the PlayOnLinux script list and the site: '''
* Name: ''nameofprogram''-22x22
* File Type: PNG, JPEG
* Size: 22x22
''' Sideways banner that is on the left side of the first window when script is ran: '''
* Name: left.jpg (or left.png)
* File Type: PNG, JPEG
* Size: 150x356 (W x H)
''' Top corner Icon for install script: '''
* Name: top.jpg (or top.png)
* File Type: PNG, JPEG
* Size: 64x64 (W x H)

== What to do after you have tested your script ==

After you have had your script on the forum, and its been verified to work, and the script is effective, clean, and portable, then submit in the following fashion:

# Go to [https://www.playonlinux.com PlayOnLinux] or [https://www.playonmac.com PlayOnMac]
# Click '''Supported Software'''
# Click '''Add a program'''
# Enter the name of the script you want to publish
# Fill out the form as completely as you can
# After your submit that, click '''Click here to see it'''
# When you return to your page, click the '''Contribute''' button
# Enter in a description, and below the description form, click '''I want to submit an improvement'''
# Copy/paste your script in that field, and click '''Send'''

Now your script is awaiting approval. A staff member will look at the script and either:

* It will be approved, and will be then available in the POL/POM Install menu
* It will need improvements, which the staff member will inform you of. Then you just use the '''Contribute''' button to submit a new version of the script
* Your script will be deleted because it is empty, spam, a help request, or something else not related to that section

Scripting - Chapter 11: List of Functions

2015-10-11T19:56:37Z

Petch: /* POL_SetupWindow_Close (4.0+) */ wording fixes

== 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:'''

# Optional --force option to override any cached images
# URL of top image.
# URL of left image.
# 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_v2", etc.

'''Prerequisite:'''

This statement must be used before '''POL_SetupWindow_Init'''.

'''Example:'''
<pre class="playonlinux code">
POL_GetSetupImages "http://files.playonlinux.com/resources/setups/AC2/top.jpg" "http://files.playonlinux.com/resources/setups/AC2/left.jpg" "$TITLE"
</pre>

=== 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:'''
<pre class="playonlinux code">
POL_SetupWindow_Init
</pre>

=== 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:'''
<pre class="playonlinux code">
POL_SetupWindow_Close
</pre>

== PlayOnLinux graphical interface ==

{{Warning|All the functions below need the command POL_SetupWindow_Init to be executed beforehand.}}

=== POL_SetupWindow_presentation (4.0+) ===

'''Arguments:'''

# Software name (often $TITLE).
# Software publisher.
# Site of the publisher.
# Script author.
# Prefix name (usually $PREFIX).

'''Description:'''

Present the software.

'''Example:'''
<pre class="playonlinux code">
POL_SetupWindow_presentation "$TITLE" "Mozilla" "http://www.mozilla.com" "SuperPlumus and NSLW" "$PREFIX"
</pre>

=== POL_SetupWindow_free_presentation (4.0+) ===

'''Arguments:'''

# Software name (often $TITLE).
# Message.

'''Description:'''

Present the software with more freedom than POL_SetupWindow_presentation.

'''Example:'''
<pre class="playonlinux code">
POL_SetupWindow_free_presentation "$TITLE" "Welcome to Mozilla Firefox installation wizard."
</pre>

=== POL_SetupWindow_message (4.0+) ===

'''Arguments:'''

# Message.
# Title (often $TITLE).

'''Description:'''

Display a message.

'''Example:'''
<pre class="playonlinux code">
POL_SetupWindow_message "Hello world!" "$TITLE"
</pre>

=== check_one - POL_SetupWindow_missing (4.0-4.1.1) ===

'''Arguments for check_one:'''

# Program that must be present.
# 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:'''
<pre class="playonlinux code">
check_one "p7zip" "p7zip"
POL_SetupWindow_missing
</pre>

=== POL_SetupWindow_file (4.0+) ===

'''Arguments:'''

# Message.
# Title (often $TITLE).
# File to display.

'''Description:'''

Display the content of a file.

'''Example:'''
<pre class="playonlinux code">
POL_SetupWindow_file "Changelog" "$TITLE" "$POL_System_TmpDir/changelog.txt"
</pre>

=== POL_SetupWindow_licence (4.0+) ===

'''Arguments:'''

# Message.
# Title (often $TITLE).
# File to display.

'''Description:'''

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

Useful for displaying licenses.

'''Example:'''
<pre class="playonlinux code">
POL_SetupWindow_licence "Licence:" "$TITLE" "$POL_System_TmpDir/licence.txt"
</pre>

=== POL_SetupWindow_pulsebar - POL_SetupWindow_pulse - POL_SetupWindow_set_text (4.0+) ===

'''Arguments for POL_SetupWindow_pulsebar:'''

# Message.
# Title (often $TITLE).

'''Arguments for POL_SetupWindow_pulse:'''

# Percentage.

'''Arguments for POL_SetupWindow_set_text:'''

# 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:'''
<pre class="playonlinux code">
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"
</pre>

=== POL_SetupWindow_wait (4.0+) ===

'''Arguments:'''

# Message.
# Title (often $TITLE).

'''Description:'''

Display an indeterminate progress bar.

'''Example:'''
<pre class="playonlinux code">
POL_SetupWindow_wait "Please wait" "$TITLE"
</pre>

=== POL_SetupWindow_textbox (4.0+) ===

'''Arguments:'''

# Message.
# Title (often $TITLE).
# 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:'''
<pre class="playonlinux code">
POL_SetupWindow_textbox "Votre pseudo :" "$TITLE"
</pre>

=== POL_SetupWindow_textbox_multiline (4.0+) ===

'''Arguments:'''

# Message.
# Title (often $TITLE).
# 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:'''
<pre class="playonlinux code">
POL_SetupWindow_textbox_multiline "Enter a description for the program" "$TITLE"
</pre>

=== POL_SetupWindow_browse (4.0+) ===

'''Arguments:'''

# Message.
# Title (often $TITLE).
# 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:'''
<pre class="playonlinux code">
POL_SetupWindow_browse "Please select the program." "$TITLE"
</pre>

=== POL_SetupWindow_question (4.0+) ===

'''Arguments:'''

# Message.
# 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:'''
<pre class="playonlinux code">
POL_SetupWindow_question "Message" "Title"
</pre>

=== POL_SetupWindow_menu (4.0+) ===

'''Arguments:'''

# Message.
# Title (often $TITLE).
# Available choices.
# 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:'''
<pre class="playonlinux code">
POL_SetupWindow_menu "What's your favorite color?" "$TITLE" "Red~Green~Blue" "~"
</pre>

=== POL_SetupWindow_menu_num (4.0+) ===

'''Arguments:'''

# Message.
# Title (often $TITLE).
# Available choices.
# 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:'''
<pre class="playonlinux code">
POL_SetupWindow_menu_num "What's your favorite color?" "$TITLE" "Red~Green~Blue" "~"
</pre>

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

=== POL_SetupWindow_menu_list (4.0+) ===

'''Arguments:'''

# Message.
# Title (often $TITLE).
# Available choices.
# Separator character (often ~ or -).
# 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:'''
<pre class="playonlinux code">
POL_SetupWindow_menu_list "What's your favorite color?" "$TITLE" "Red~Green~Blue" "~"
</pre>

=== POL_SetupWindow_checkbox_list (4.0+) ===

'''Arguments:'''

# Message.
# Title (often $TITLE).
# Available choices.
# 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:'''
<pre class="playonlinux code">
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
</pre>

=== 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:'''
<pre class="playonlinux code">
POL_SetupWindow_cdrom
</pre>

=== POL_SetupWindow_check_cdrom (4.0+) ===

'''Arguments:'''

# 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:'''
<pre class="playonlinux code">
POL_SetupWindow_check_cdrom "Data/32_icon.ico"
</pre>

=== POL_SetupWindow_InstallMethod (4.0+) ===

'''Arguments:'''

# 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:'''
<pre class="playonlinux code">
POL_SetupWindow_InstallMethod "LOCAL,CD,STEAM"
</pre>

== POL_RequiredVersion (4.0.15+) ==

'''Arguments:'''

# 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, it itself only appeared in PlayOnLinux 4.0.15, and PlayOnLinux 4.0.14 is still the default in some distributions; 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_AdvisedVersion (4.0.15+) ==

'''Arguments:'''

# 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:'''

# Executable filename.
# Launcher name (often $TITLE).
# Optional name of the icon to download from PlayOnLinux website.
# Optional executable arguments.
# 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 [http://linux.die.net/man/7/glob 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 [http://standards.freedesktop.org/menu-spec/latest/apa.html main] and [http://standards.freedesktop.org/menu-spec/latest/apas02.html 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:'''
<pre class="playonlinux code">
POL_Shortcut "firefox.exe" "$TITLE"
</pre>

== POL_Shortcut_InsertBeforeWine (4.0+) ==

'''Arguments:'''

# Launcher name (often $TITLE).
# Command to add.

'''Description:'''

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

'''Example:'''
<pre class="playonlinux code">
POL_Shortcut_InsertBeforeWine "Jedi Knight II" "export __GL_ExtensionStringVersion=17700"
</pre>

== POL_Shortcut_QuietDebug (4.0.17+) ==
'''Arguments:'''

# 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:'''
# Launcher name (often $TITLE).
# 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:'''

# URL to open.

'''Description:'''

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

'''Example:'''
<pre class="playonlinux code">
POL_Browser "http://www.playonlinux.com"
</pre>

== POL_Download (4.0+) ==

'''Arguments:'''

# URL to download.
# (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:'''

# URL to download.
# Expected MD5 digest of the downloaded file
# (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:'''

# 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:'''
<pre class="playonlinux code">
POL_System_TmpCreate "$PREFIX"
</pre>

== POL_System_TmpDelete (4.0+) ==

'''Description:'''

Removes the script's temporary directory.

'''Example:'''
<pre class="playonlinux code">
POL_System_TmpDelete
</pre>

== POL_System_SetArch (4.0+) ==

'''Arguments:'''

# 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:'''
<pre class="playonlinux code">
POL_System_SetArch "auto"
</pre>

== POL_Call (4.0+) ==

'''Arguments:'''

# Function name.
# 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|Components and Functions]]).

'''Prerequisite:'''

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

'''Example:'''
<pre class="playonlinux code">
POL_Call POL_Install_vcrun6
</pre>

== Wine-related functions ==

=== POL_Wine_SelectPrefix (4.0+) ===

'''Arguments:'''

# 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:'''
<pre class="playonlinux code">
POL_Wine_SelectPrefix "$PREFIX"
</pre>

=== POL_Wine_PrefixExists (4.0+) ===

'''Arguments:'''

# 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:'''
<pre class="playonlinux code">
if [ "$(POL_Wine_PrefixExists "$PREFIX")" = "False" ]
then
# The préfixe doesn't exist
fi
</pre>

=== POL_Wine_PrefixCreate (4.0+) ===

'''Arguments:'''

# 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:'''
<pre class="playonlinux code">
POL_Wine_PrefixCreate "1.3.4"
</pre>

=== 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:'''

# 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:'''
<pre class="playonlinux code">
POL_SetupWindow_VMS "128"
</pre>

=== Set_OS (4.0+) ===

'''Arguments:'''

# Windows version to emulate.
# 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:'''
<pre class="playonlinux code">
Set_OS "win2k"
</pre>

=== Set_Managed (4.0+) ===

'''Arguments:'''

# 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:'''
<pre class="playonlinux code">
Set_Managed "Off"
</pre>

=== Set_SoundDriver (4.0+) ===

'''Arguments:'''

# alsa/oss/esd.

'''Description:'''

Set the audio driver Wine will use.

{{Info|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:'''
<pre class="playonlinux code">
Set_SoundDriver "alsa"
</pre>

=== POL_Wine_Direct3D (4.0+) ===

'''Arguments:'''

# Setting to create/modify.
# New setting value.

'''Description:'''

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

'''Allowed values:'''

See [http://wiki.winehq.org/UsefulRegistryKeys WineHQ's Wiki].

'''Prerequisite:'''

The commands POL_Wine_SelectPrefix and POL_Wine_PrefixCreate must have been used beforehand.

'''Example:'''
<pre class="playonlinux code">
POL_Wine_Direct3D "UseGLSL" "disabled"
</pre>

=== POL_Wine_X11Drv (4.0.14+) ===

'''Arguments:'''

# Setting to create/modify.
# New setting value.

'''Description:'''

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

'''Allowed values:'''

See [http://wiki.winehq.org/UsefulRegistryKeys WineHQ's Wiki].

'''Prerequisite:'''

The commands POL_Wine_SelectPrefix and POL_Wine_PrefixCreate must have been used beforehand.

'''Example:'''
<pre class="playonlinux code">
POL_Wine_X11Drv "DXGrab" "Y"
</pre>

=== POL_Wine_DirectSound (4.0+) ===

'''Arguments:'''

# Setting to create/modify.
# New setting value.

'''Description:'''

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

'''Allowed values:'''

See [http://wiki.winehq.org/UsefulRegistryKeys WineHQ's Wiki].

'''Prerequisite:'''

The commands POL_Wine_SelectPrefix and POL_Wine_PrefixCreate must have been used beforehand.

'''Example:'''
<pre class="playonlinux code">
POL_Wine_DirectSound "HardwareAcceleration" "Emulation"
</pre>

=== POL_Wine_DirectInput (4.0+) ===

'''Arguments:'''

# Setting to create/modify.
# New setting value.

'''Description:'''

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

'''Allowed values:'''

See [http://wiki.winehq.org/UsefulRegistryKeys WineHQ's Wiki].

'''Prerequisite:'''

The commands POL_Wine_SelectPrefix and POL_Wine_PrefixCreate must have been used beforehand.

'''Example:'''
<pre class="playonlinux code">
POL_Wine_DirectInput "MouseWarpOverride" "force"
</pre>

=== POL_Wine_GetRegValue (4.0+) ===

'''Arguments:'''

# 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:'''
<pre class="playonlinux code">
VALUE="$(POL_Wine_GetRegValue "MouseWarpOverride")"
</pre>

=== Set_Desktop (4.0+) ===

'''Arguments:'''

# On/Off.
# Virtual desktop width (if it is enabled).
# 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:'''
<pre class="playonlinux code">
Set_Desktop "On" "1024" "768"
</pre>

=== Set_WineWindowTitle (4.0+) ===

'''Arguments:'''

# 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:'''
<pre class="playonlinux code">
Set_WineWindowTitle "$TITLE"
</pre>

=== 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:'''
<pre class="playonlinux code">
POL_Wine_InstallFonts
</pre>

=== 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:'''
<pre class="playonlinux code">
POL_Wine_SetVideoDriver
</pre>

=== POL_Wine_OverrideDLL (4.0+) ===

'''Arguments:'''

# Mode of override.
# 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:'''
<pre class="playonlinux code">
POL_Wine_OverrideDLL "native" "msvcrt"
POL_Wine_OverrideDLL "" "msvcrt" # To disable the DLL
</pre>

=== POL_Wine_OverrideDLL_App (4.0+) ===

'''Arguments:'''

# Executable name.
# Mode of override.
# 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:'''
<pre class="playonlinux code">
POL_Wine_OverrideDLL_App "firefox.exe" "native" "msvcrt"
POL_Wine_OverrideDLL_App "firefox.exe" "" "msvcrt" # To disable the DLL
</pre>

=== POL_Wine_WaitBefore (4.0.15+) ===

'''Arguments:'''

# 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:'''

# 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:'''
<pre class="playonlinux code">
POL_Wine_WaitExit "$TITLE"
</pre>

=== 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:'''
<pre class="playonlinux code">
POL_Wine_reboot
</pre>

== Debugging commands ==

=== POL_Debug_Init (4.0+) ===

'''Description:'''

Start debugging system.

'''Example:'''
<pre class="playonlinux code">
POL_Debug_Init
</pre>

=== POL_Debug_Message (4.0+) ===

'''Arguments:'''

# 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:'''
<pre class="playonlinux code">
POL_Debug_Message "Modifying config.cfg file."
</pre>

=== POL_Debug_Warning (4.0+) ===

'''Arguments:'''

# 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:'''
<pre class="playonlinux code">
POL_Debug_Warning "File config.cfg did not exist, creating one."
</pre>

=== POL_Debug_Error (4.0+) ===

'''Arguments:'''

# 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:'''
<pre class="playonlinux code">
POL_Debug_Error "Error while modifying config.cfg file"
</pre>

=== POL_Debug_Fatal (4.0+) ===

'''Arguments:'''

# Message.

'''Description:'''

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

'''Prerequisite:'''

The command POL_Debug_Init must have been used beforehand.

'''Example:'''
<pre class="playonlinux code">
POL_Debug_Fatal "Error while modifying config.cfg file"
</pre>

'''Previous:''' [[Scripting - Chapter 10: Script Translation|Chapter 10: Script Translation]]

[[Category:Scripting]]

Scripting - Chapter 11: List of Functions

2015-10-11T19:55:00Z

Petch: /* POL_SetupWindow_Close (4.0+) */ wording fixes

== 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:'''

# Optional --force option to override any cached images
# URL of top image.
# URL of left image.
# 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_v2", etc.

'''Prerequisite:'''

This statement must be used before '''POL_SetupWindow_Init'''.

'''Example:'''
<pre class="playonlinux code">
POL_GetSetupImages "http://files.playonlinux.com/resources/setups/AC2/top.jpg" "http://files.playonlinux.com/resources/setups/AC2/left.jpg" "$TITLE"
</pre>

=== 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:'''
<pre class="playonlinux code">
POL_SetupWindow_Init
</pre>

=== 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 script.

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:'''
<pre class="playonlinux code">
POL_SetupWindow_Close
</pre>

== PlayOnLinux graphical interface ==

{{Warning|All the functions below need the command POL_SetupWindow_Init to be executed beforehand.}}

=== POL_SetupWindow_presentation (4.0+) ===

'''Arguments:'''

# Software name (often $TITLE).
# Software publisher.
# Site of the publisher.
# Script author.
# Prefix name (usually $PREFIX).

'''Description:'''

Present the software.

'''Example:'''
<pre class="playonlinux code">
POL_SetupWindow_presentation "$TITLE" "Mozilla" "http://www.mozilla.com" "SuperPlumus and NSLW" "$PREFIX"
</pre>

=== POL_SetupWindow_free_presentation (4.0+) ===

'''Arguments:'''

# Software name (often $TITLE).
# Message.

'''Description:'''

Present the software with more freedom than POL_SetupWindow_presentation.

'''Example:'''
<pre class="playonlinux code">
POL_SetupWindow_free_presentation "$TITLE" "Welcome to Mozilla Firefox installation wizard."
</pre>

=== POL_SetupWindow_message (4.0+) ===

'''Arguments:'''

# Message.
# Title (often $TITLE).

'''Description:'''

Display a message.

'''Example:'''
<pre class="playonlinux code">
POL_SetupWindow_message "Hello world!" "$TITLE"
</pre>

=== check_one - POL_SetupWindow_missing (4.0-4.1.1) ===

'''Arguments for check_one:'''

# Program that must be present.
# 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:'''
<pre class="playonlinux code">
check_one "p7zip" "p7zip"
POL_SetupWindow_missing
</pre>

=== POL_SetupWindow_file (4.0+) ===

'''Arguments:'''

# Message.
# Title (often $TITLE).
# File to display.

'''Description:'''

Display the content of a file.

'''Example:'''
<pre class="playonlinux code">
POL_SetupWindow_file "Changelog" "$TITLE" "$POL_System_TmpDir/changelog.txt"
</pre>

=== POL_SetupWindow_licence (4.0+) ===

'''Arguments:'''

# Message.
# Title (often $TITLE).
# File to display.

'''Description:'''

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

Useful for displaying licenses.

'''Example:'''
<pre class="playonlinux code">
POL_SetupWindow_licence "Licence:" "$TITLE" "$POL_System_TmpDir/licence.txt"
</pre>

=== POL_SetupWindow_pulsebar - POL_SetupWindow_pulse - POL_SetupWindow_set_text (4.0+) ===

'''Arguments for POL_SetupWindow_pulsebar:'''

# Message.
# Title (often $TITLE).

'''Arguments for POL_SetupWindow_pulse:'''

# Percentage.

'''Arguments for POL_SetupWindow_set_text:'''

# 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:'''
<pre class="playonlinux code">
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"
</pre>

=== POL_SetupWindow_wait (4.0+) ===

'''Arguments:'''

# Message.
# Title (often $TITLE).

'''Description:'''

Display an indeterminate progress bar.

'''Example:'''
<pre class="playonlinux code">
POL_SetupWindow_wait "Please wait" "$TITLE"
</pre>

=== POL_SetupWindow_textbox (4.0+) ===

'''Arguments:'''

# Message.
# Title (often $TITLE).
# 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:'''
<pre class="playonlinux code">
POL_SetupWindow_textbox "Votre pseudo :" "$TITLE"
</pre>

=== POL_SetupWindow_textbox_multiline (4.0+) ===

'''Arguments:'''

# Message.
# Title (often $TITLE).
# 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:'''
<pre class="playonlinux code">
POL_SetupWindow_textbox_multiline "Enter a description for the program" "$TITLE"
</pre>

=== POL_SetupWindow_browse (4.0+) ===

'''Arguments:'''

# Message.
# Title (often $TITLE).
# 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:'''
<pre class="playonlinux code">
POL_SetupWindow_browse "Please select the program." "$TITLE"
</pre>

=== POL_SetupWindow_question (4.0+) ===

'''Arguments:'''

# Message.
# 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:'''
<pre class="playonlinux code">
POL_SetupWindow_question "Message" "Title"
</pre>

=== POL_SetupWindow_menu (4.0+) ===

'''Arguments:'''

# Message.
# Title (often $TITLE).
# Available choices.
# 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:'''
<pre class="playonlinux code">
POL_SetupWindow_menu "What's your favorite color?" "$TITLE" "Red~Green~Blue" "~"
</pre>

=== POL_SetupWindow_menu_num (4.0+) ===

'''Arguments:'''

# Message.
# Title (often $TITLE).
# Available choices.
# 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:'''
<pre class="playonlinux code">
POL_SetupWindow_menu_num "What's your favorite color?" "$TITLE" "Red~Green~Blue" "~"
</pre>

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

=== POL_SetupWindow_menu_list (4.0+) ===

'''Arguments:'''

# Message.
# Title (often $TITLE).
# Available choices.
# Separator character (often ~ or -).
# 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:'''
<pre class="playonlinux code">
POL_SetupWindow_menu_list "What's your favorite color?" "$TITLE" "Red~Green~Blue" "~"
</pre>

=== POL_SetupWindow_checkbox_list (4.0+) ===

'''Arguments:'''

# Message.
# Title (often $TITLE).
# Available choices.
# 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:'''
<pre class="playonlinux code">
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
</pre>

=== 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:'''
<pre class="playonlinux code">
POL_SetupWindow_cdrom
</pre>

=== POL_SetupWindow_check_cdrom (4.0+) ===

'''Arguments:'''

# 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:'''
<pre class="playonlinux code">
POL_SetupWindow_check_cdrom "Data/32_icon.ico"
</pre>

=== POL_SetupWindow_InstallMethod (4.0+) ===

'''Arguments:'''

# 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:'''
<pre class="playonlinux code">
POL_SetupWindow_InstallMethod "LOCAL,CD,STEAM"
</pre>

== POL_RequiredVersion (4.0.15+) ==

'''Arguments:'''

# 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, it itself only appeared in PlayOnLinux 4.0.15, and PlayOnLinux 4.0.14 is still the default in some distributions; 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_AdvisedVersion (4.0.15+) ==

'''Arguments:'''

# 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:'''

# Executable filename.
# Launcher name (often $TITLE).
# Optional name of the icon to download from PlayOnLinux website.
# Optional executable arguments.
# 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 [http://linux.die.net/man/7/glob 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 [http://standards.freedesktop.org/menu-spec/latest/apa.html main] and [http://standards.freedesktop.org/menu-spec/latest/apas02.html 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:'''
<pre class="playonlinux code">
POL_Shortcut "firefox.exe" "$TITLE"
</pre>

== POL_Shortcut_InsertBeforeWine (4.0+) ==

'''Arguments:'''

# Launcher name (often $TITLE).
# Command to add.

'''Description:'''

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

'''Example:'''
<pre class="playonlinux code">
POL_Shortcut_InsertBeforeWine "Jedi Knight II" "export __GL_ExtensionStringVersion=17700"
</pre>

== POL_Shortcut_QuietDebug (4.0.17+) ==
'''Arguments:'''

# 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:'''
# Launcher name (often $TITLE).
# 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:'''

# URL to open.

'''Description:'''

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

'''Example:'''
<pre class="playonlinux code">
POL_Browser "http://www.playonlinux.com"
</pre>

== POL_Download (4.0+) ==

'''Arguments:'''

# URL to download.
# (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:'''

# URL to download.
# Expected MD5 digest of the downloaded file
# (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:'''

# 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:'''
<pre class="playonlinux code">
POL_System_TmpCreate "$PREFIX"
</pre>

== POL_System_TmpDelete (4.0+) ==

'''Description:'''

Removes the script's temporary directory.

'''Example:'''
<pre class="playonlinux code">
POL_System_TmpDelete
</pre>

== POL_System_SetArch (4.0+) ==

'''Arguments:'''

# 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:'''
<pre class="playonlinux code">
POL_System_SetArch "auto"
</pre>

== POL_Call (4.0+) ==

'''Arguments:'''

# Function name.
# 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|Components and Functions]]).

'''Prerequisite:'''

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

'''Example:'''
<pre class="playonlinux code">
POL_Call POL_Install_vcrun6
</pre>

== Wine-related functions ==

=== POL_Wine_SelectPrefix (4.0+) ===

'''Arguments:'''

# 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:'''
<pre class="playonlinux code">
POL_Wine_SelectPrefix "$PREFIX"
</pre>

=== POL_Wine_PrefixExists (4.0+) ===

'''Arguments:'''

# 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:'''
<pre class="playonlinux code">
if [ "$(POL_Wine_PrefixExists "$PREFIX")" = "False" ]
then
# The préfixe doesn't exist
fi
</pre>

=== POL_Wine_PrefixCreate (4.0+) ===

'''Arguments:'''

# 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:'''
<pre class="playonlinux code">
POL_Wine_PrefixCreate "1.3.4"
</pre>

=== 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:'''

# 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:'''
<pre class="playonlinux code">
POL_SetupWindow_VMS "128"
</pre>

=== Set_OS (4.0+) ===

'''Arguments:'''

# Windows version to emulate.
# 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:'''
<pre class="playonlinux code">
Set_OS "win2k"
</pre>

=== Set_Managed (4.0+) ===

'''Arguments:'''

# 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:'''
<pre class="playonlinux code">
Set_Managed "Off"
</pre>

=== Set_SoundDriver (4.0+) ===

'''Arguments:'''

# alsa/oss/esd.

'''Description:'''

Set the audio driver Wine will use.

{{Info|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:'''
<pre class="playonlinux code">
Set_SoundDriver "alsa"
</pre>

=== POL_Wine_Direct3D (4.0+) ===

'''Arguments:'''

# Setting to create/modify.
# New setting value.

'''Description:'''

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

'''Allowed values:'''

See [http://wiki.winehq.org/UsefulRegistryKeys WineHQ's Wiki].

'''Prerequisite:'''

The commands POL_Wine_SelectPrefix and POL_Wine_PrefixCreate must have been used beforehand.

'''Example:'''
<pre class="playonlinux code">
POL_Wine_Direct3D "UseGLSL" "disabled"
</pre>

=== POL_Wine_X11Drv (4.0.14+) ===

'''Arguments:'''

# Setting to create/modify.
# New setting value.

'''Description:'''

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

'''Allowed values:'''

See [http://wiki.winehq.org/UsefulRegistryKeys WineHQ's Wiki].

'''Prerequisite:'''

The commands POL_Wine_SelectPrefix and POL_Wine_PrefixCreate must have been used beforehand.

'''Example:'''
<pre class="playonlinux code">
POL_Wine_X11Drv "DXGrab" "Y"
</pre>

=== POL_Wine_DirectSound (4.0+) ===

'''Arguments:'''

# Setting to create/modify.
# New setting value.

'''Description:'''

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

'''Allowed values:'''

See [http://wiki.winehq.org/UsefulRegistryKeys WineHQ's Wiki].

'''Prerequisite:'''

The commands POL_Wine_SelectPrefix and POL_Wine_PrefixCreate must have been used beforehand.

'''Example:'''
<pre class="playonlinux code">
POL_Wine_DirectSound "HardwareAcceleration" "Emulation"
</pre>

=== POL_Wine_DirectInput (4.0+) ===

'''Arguments:'''

# Setting to create/modify.
# New setting value.

'''Description:'''

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

'''Allowed values:'''

See [http://wiki.winehq.org/UsefulRegistryKeys WineHQ's Wiki].

'''Prerequisite:'''

The commands POL_Wine_SelectPrefix and POL_Wine_PrefixCreate must have been used beforehand.

'''Example:'''
<pre class="playonlinux code">
POL_Wine_DirectInput "MouseWarpOverride" "force"
</pre>

=== POL_Wine_GetRegValue (4.0+) ===

'''Arguments:'''

# 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:'''
<pre class="playonlinux code">
VALUE="$(POL_Wine_GetRegValue "MouseWarpOverride")"
</pre>

=== Set_Desktop (4.0+) ===

'''Arguments:'''

# On/Off.
# Virtual desktop width (if it is enabled).
# 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:'''
<pre class="playonlinux code">
Set_Desktop "On" "1024" "768"
</pre>

=== Set_WineWindowTitle (4.0+) ===

'''Arguments:'''

# 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:'''
<pre class="playonlinux code">
Set_WineWindowTitle "$TITLE"
</pre>

=== 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:'''
<pre class="playonlinux code">
POL_Wine_InstallFonts
</pre>

=== 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:'''
<pre class="playonlinux code">
POL_Wine_SetVideoDriver
</pre>

=== POL_Wine_OverrideDLL (4.0+) ===

'''Arguments:'''

# Mode of override.
# 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:'''
<pre class="playonlinux code">
POL_Wine_OverrideDLL "native" "msvcrt"
POL_Wine_OverrideDLL "" "msvcrt" # To disable the DLL
</pre>

=== POL_Wine_OverrideDLL_App (4.0+) ===

'''Arguments:'''

# Executable name.
# Mode of override.
# 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:'''
<pre class="playonlinux code">
POL_Wine_OverrideDLL_App "firefox.exe" "native" "msvcrt"
POL_Wine_OverrideDLL_App "firefox.exe" "" "msvcrt" # To disable the DLL
</pre>

=== POL_Wine_WaitBefore (4.0.15+) ===

'''Arguments:'''

# 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:'''

# 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:'''
<pre class="playonlinux code">
POL_Wine_WaitExit "$TITLE"
</pre>

=== 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:'''
<pre class="playonlinux code">
POL_Wine_reboot
</pre>

== Debugging commands ==

=== POL_Debug_Init (4.0+) ===

'''Description:'''

Start debugging system.

'''Example:'''
<pre class="playonlinux code">
POL_Debug_Init
</pre>

=== POL_Debug_Message (4.0+) ===

'''Arguments:'''

# 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:'''
<pre class="playonlinux code">
POL_Debug_Message "Modifying config.cfg file."
</pre>

=== POL_Debug_Warning (4.0+) ===

'''Arguments:'''

# 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:'''
<pre class="playonlinux code">
POL_Debug_Warning "File config.cfg did not exist, creating one."
</pre>

=== POL_Debug_Error (4.0+) ===

'''Arguments:'''

# 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:'''
<pre class="playonlinux code">
POL_Debug_Error "Error while modifying config.cfg file"
</pre>

=== POL_Debug_Fatal (4.0+) ===

'''Arguments:'''

# Message.

'''Description:'''

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

'''Prerequisite:'''

The command POL_Debug_Init must have been used beforehand.

'''Example:'''
<pre class="playonlinux code">
POL_Debug_Fatal "Error while modifying config.cfg file"
</pre>

'''Previous:''' [[Scripting - Chapter 10: Script Translation|Chapter 10: Script Translation]]

[[Category:Scripting]]

Scripting - Chapter 11: List of Functions

2015-10-11T19:54:04Z

Petch: /* POL_SetupWindow_Close (4.0+) */

== 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:'''

# Optional --force option to override any cached images
# URL of top image.
# URL of left image.
# 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_v2", etc.

'''Prerequisite:'''

This statement must be used before '''POL_SetupWindow_Init'''.

'''Example:'''
<pre class="playonlinux code">
POL_GetSetupImages "http://files.playonlinux.com/resources/setups/AC2/top.jpg" "http://files.playonlinux.com/resources/setups/AC2/left.jpg" "$TITLE"
</pre>

=== 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:'''
<pre class="playonlinux code">
POL_SetupWindow_Init
</pre>

=== 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, it is recommended to use '''POL_SetupWindow_Close''' as late as possible in the script.

If some statement error has been detected during the execution of the script by the embedded debugger (see "Debugging Commands" below), 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:'''
<pre class="playonlinux code">
POL_SetupWindow_Close
</pre>

== PlayOnLinux graphical interface ==

{{Warning|All the functions below need the command POL_SetupWindow_Init to be executed beforehand.}}

=== POL_SetupWindow_presentation (4.0+) ===

'''Arguments:'''

# Software name (often $TITLE).
# Software publisher.
# Site of the publisher.
# Script author.
# Prefix name (usually $PREFIX).

'''Description:'''

Present the software.

'''Example:'''
<pre class="playonlinux code">
POL_SetupWindow_presentation "$TITLE" "Mozilla" "http://www.mozilla.com" "SuperPlumus and NSLW" "$PREFIX"
</pre>

=== POL_SetupWindow_free_presentation (4.0+) ===

'''Arguments:'''

# Software name (often $TITLE).
# Message.

'''Description:'''

Present the software with more freedom than POL_SetupWindow_presentation.

'''Example:'''
<pre class="playonlinux code">
POL_SetupWindow_free_presentation "$TITLE" "Welcome to Mozilla Firefox installation wizard."
</pre>

=== POL_SetupWindow_message (4.0+) ===

'''Arguments:'''

# Message.
# Title (often $TITLE).

'''Description:'''

Display a message.

'''Example:'''
<pre class="playonlinux code">
POL_SetupWindow_message "Hello world!" "$TITLE"
</pre>

=== check_one - POL_SetupWindow_missing (4.0-4.1.1) ===

'''Arguments for check_one:'''

# Program that must be present.
# 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:'''
<pre class="playonlinux code">
check_one "p7zip" "p7zip"
POL_SetupWindow_missing
</pre>

=== POL_SetupWindow_file (4.0+) ===

'''Arguments:'''

# Message.
# Title (often $TITLE).
# File to display.

'''Description:'''

Display the content of a file.

'''Example:'''
<pre class="playonlinux code">
POL_SetupWindow_file "Changelog" "$TITLE" "$POL_System_TmpDir/changelog.txt"
</pre>

=== POL_SetupWindow_licence (4.0+) ===

'''Arguments:'''

# Message.
# Title (often $TITLE).
# File to display.

'''Description:'''

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

Useful for displaying licenses.

'''Example:'''
<pre class="playonlinux code">
POL_SetupWindow_licence "Licence:" "$TITLE" "$POL_System_TmpDir/licence.txt"
</pre>

=== POL_SetupWindow_pulsebar - POL_SetupWindow_pulse - POL_SetupWindow_set_text (4.0+) ===

'''Arguments for POL_SetupWindow_pulsebar:'''

# Message.
# Title (often $TITLE).

'''Arguments for POL_SetupWindow_pulse:'''

# Percentage.

'''Arguments for POL_SetupWindow_set_text:'''

# 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:'''
<pre class="playonlinux code">
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"
</pre>

=== POL_SetupWindow_wait (4.0+) ===

'''Arguments:'''

# Message.
# Title (often $TITLE).

'''Description:'''

Display an indeterminate progress bar.

'''Example:'''
<pre class="playonlinux code">
POL_SetupWindow_wait "Please wait" "$TITLE"
</pre>

=== POL_SetupWindow_textbox (4.0+) ===

'''Arguments:'''

# Message.
# Title (often $TITLE).
# 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:'''
<pre class="playonlinux code">
POL_SetupWindow_textbox "Votre pseudo :" "$TITLE"
</pre>

=== POL_SetupWindow_textbox_multiline (4.0+) ===

'''Arguments:'''

# Message.
# Title (often $TITLE).
# 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:'''
<pre class="playonlinux code">
POL_SetupWindow_textbox_multiline "Enter a description for the program" "$TITLE"
</pre>

=== POL_SetupWindow_browse (4.0+) ===

'''Arguments:'''

# Message.
# Title (often $TITLE).
# 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:'''
<pre class="playonlinux code">
POL_SetupWindow_browse "Please select the program." "$TITLE"
</pre>

=== POL_SetupWindow_question (4.0+) ===

'''Arguments:'''

# Message.
# 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:'''
<pre class="playonlinux code">
POL_SetupWindow_question "Message" "Title"
</pre>

=== POL_SetupWindow_menu (4.0+) ===

'''Arguments:'''

# Message.
# Title (often $TITLE).
# Available choices.
# 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:'''
<pre class="playonlinux code">
POL_SetupWindow_menu "What's your favorite color?" "$TITLE" "Red~Green~Blue" "~"
</pre>

=== POL_SetupWindow_menu_num (4.0+) ===

'''Arguments:'''

# Message.
# Title (often $TITLE).
# Available choices.
# 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:'''
<pre class="playonlinux code">
POL_SetupWindow_menu_num "What's your favorite color?" "$TITLE" "Red~Green~Blue" "~"
</pre>

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

=== POL_SetupWindow_menu_list (4.0+) ===

'''Arguments:'''

# Message.
# Title (often $TITLE).
# Available choices.
# Separator character (often ~ or -).
# 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:'''
<pre class="playonlinux code">
POL_SetupWindow_menu_list "What's your favorite color?" "$TITLE" "Red~Green~Blue" "~"
</pre>

=== POL_SetupWindow_checkbox_list (4.0+) ===

'''Arguments:'''

# Message.
# Title (often $TITLE).
# Available choices.
# 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:'''
<pre class="playonlinux code">
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
</pre>

=== 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:'''
<pre class="playonlinux code">
POL_SetupWindow_cdrom
</pre>

=== POL_SetupWindow_check_cdrom (4.0+) ===

'''Arguments:'''

# 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:'''
<pre class="playonlinux code">
POL_SetupWindow_check_cdrom "Data/32_icon.ico"
</pre>

=== POL_SetupWindow_InstallMethod (4.0+) ===

'''Arguments:'''

# 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:'''
<pre class="playonlinux code">
POL_SetupWindow_InstallMethod "LOCAL,CD,STEAM"
</pre>

== POL_RequiredVersion (4.0.15+) ==

'''Arguments:'''

# 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, it itself only appeared in PlayOnLinux 4.0.15, and PlayOnLinux 4.0.14 is still the default in some distributions; 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_AdvisedVersion (4.0.15+) ==

'''Arguments:'''

# 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:'''

# Executable filename.
# Launcher name (often $TITLE).
# Optional name of the icon to download from PlayOnLinux website.
# Optional executable arguments.
# 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 [http://linux.die.net/man/7/glob 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 [http://standards.freedesktop.org/menu-spec/latest/apa.html main] and [http://standards.freedesktop.org/menu-spec/latest/apas02.html 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:'''
<pre class="playonlinux code">
POL_Shortcut "firefox.exe" "$TITLE"
</pre>

== POL_Shortcut_InsertBeforeWine (4.0+) ==

'''Arguments:'''

# Launcher name (often $TITLE).
# Command to add.

'''Description:'''

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

'''Example:'''
<pre class="playonlinux code">
POL_Shortcut_InsertBeforeWine "Jedi Knight II" "export __GL_ExtensionStringVersion=17700"
</pre>

== POL_Shortcut_QuietDebug (4.0.17+) ==
'''Arguments:'''

# 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:'''
# Launcher name (often $TITLE).
# 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:'''

# URL to open.

'''Description:'''

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

'''Example:'''
<pre class="playonlinux code">
POL_Browser "http://www.playonlinux.com"
</pre>

== POL_Download (4.0+) ==

'''Arguments:'''

# URL to download.
# (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:'''

# URL to download.
# Expected MD5 digest of the downloaded file
# (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:'''

# 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:'''
<pre class="playonlinux code">
POL_System_TmpCreate "$PREFIX"
</pre>

== POL_System_TmpDelete (4.0+) ==

'''Description:'''

Removes the script's temporary directory.

'''Example:'''
<pre class="playonlinux code">
POL_System_TmpDelete
</pre>

== POL_System_SetArch (4.0+) ==

'''Arguments:'''

# 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:'''
<pre class="playonlinux code">
POL_System_SetArch "auto"
</pre>

== POL_Call (4.0+) ==

'''Arguments:'''

# Function name.
# 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|Components and Functions]]).

'''Prerequisite:'''

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

'''Example:'''
<pre class="playonlinux code">
POL_Call POL_Install_vcrun6
</pre>

== Wine-related functions ==

=== POL_Wine_SelectPrefix (4.0+) ===

'''Arguments:'''

# 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:'''
<pre class="playonlinux code">
POL_Wine_SelectPrefix "$PREFIX"
</pre>

=== POL_Wine_PrefixExists (4.0+) ===

'''Arguments:'''

# 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:'''
<pre class="playonlinux code">
if [ "$(POL_Wine_PrefixExists "$PREFIX")" = "False" ]
then
# The préfixe doesn't exist
fi
</pre>

=== POL_Wine_PrefixCreate (4.0+) ===

'''Arguments:'''

# 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:'''
<pre class="playonlinux code">
POL_Wine_PrefixCreate "1.3.4"
</pre>

=== 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:'''

# 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:'''
<pre class="playonlinux code">
POL_SetupWindow_VMS "128"
</pre>

=== Set_OS (4.0+) ===

'''Arguments:'''

# Windows version to emulate.
# 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:'''
<pre class="playonlinux code">
Set_OS "win2k"
</pre>

=== Set_Managed (4.0+) ===

'''Arguments:'''

# 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:'''
<pre class="playonlinux code">
Set_Managed "Off"
</pre>

=== Set_SoundDriver (4.0+) ===

'''Arguments:'''

# alsa/oss/esd.

'''Description:'''

Set the audio driver Wine will use.

{{Info|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:'''
<pre class="playonlinux code">
Set_SoundDriver "alsa"
</pre>

=== POL_Wine_Direct3D (4.0+) ===

'''Arguments:'''

# Setting to create/modify.
# New setting value.

'''Description:'''

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

'''Allowed values:'''

See [http://wiki.winehq.org/UsefulRegistryKeys WineHQ's Wiki].

'''Prerequisite:'''

The commands POL_Wine_SelectPrefix and POL_Wine_PrefixCreate must have been used beforehand.

'''Example:'''
<pre class="playonlinux code">
POL_Wine_Direct3D "UseGLSL" "disabled"
</pre>

=== POL_Wine_X11Drv (4.0.14+) ===

'''Arguments:'''

# Setting to create/modify.
# New setting value.

'''Description:'''

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

'''Allowed values:'''

See [http://wiki.winehq.org/UsefulRegistryKeys WineHQ's Wiki].

'''Prerequisite:'''

The commands POL_Wine_SelectPrefix and POL_Wine_PrefixCreate must have been used beforehand.

'''Example:'''
<pre class="playonlinux code">
POL_Wine_X11Drv "DXGrab" "Y"
</pre>

=== POL_Wine_DirectSound (4.0+) ===

'''Arguments:'''

# Setting to create/modify.
# New setting value.

'''Description:'''

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

'''Allowed values:'''

See [http://wiki.winehq.org/UsefulRegistryKeys WineHQ's Wiki].

'''Prerequisite:'''

The commands POL_Wine_SelectPrefix and POL_Wine_PrefixCreate must have been used beforehand.

'''Example:'''
<pre class="playonlinux code">
POL_Wine_DirectSound "HardwareAcceleration" "Emulation"
</pre>

=== POL_Wine_DirectInput (4.0+) ===

'''Arguments:'''

# Setting to create/modify.
# New setting value.

'''Description:'''

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

'''Allowed values:'''

See [http://wiki.winehq.org/UsefulRegistryKeys WineHQ's Wiki].

'''Prerequisite:'''

The commands POL_Wine_SelectPrefix and POL_Wine_PrefixCreate must have been used beforehand.

'''Example:'''
<pre class="playonlinux code">
POL_Wine_DirectInput "MouseWarpOverride" "force"
</pre>

=== POL_Wine_GetRegValue (4.0+) ===

'''Arguments:'''

# 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:'''
<pre class="playonlinux code">
VALUE="$(POL_Wine_GetRegValue "MouseWarpOverride")"
</pre>

=== Set_Desktop (4.0+) ===

'''Arguments:'''

# On/Off.
# Virtual desktop width (if it is enabled).
# 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:'''
<pre class="playonlinux code">
Set_Desktop "On" "1024" "768"
</pre>

=== Set_WineWindowTitle (4.0+) ===

'''Arguments:'''

# 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:'''
<pre class="playonlinux code">
Set_WineWindowTitle "$TITLE"
</pre>

=== 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:'''
<pre class="playonlinux code">
POL_Wine_InstallFonts
</pre>

=== 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:'''
<pre class="playonlinux code">
POL_Wine_SetVideoDriver
</pre>

=== POL_Wine_OverrideDLL (4.0+) ===

'''Arguments:'''

# Mode of override.
# 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:'''
<pre class="playonlinux code">
POL_Wine_OverrideDLL "native" "msvcrt"
POL_Wine_OverrideDLL "" "msvcrt" # To disable the DLL
</pre>

=== POL_Wine_OverrideDLL_App (4.0+) ===

'''Arguments:'''

# Executable name.
# Mode of override.
# 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:'''
<pre class="playonlinux code">
POL_Wine_OverrideDLL_App "firefox.exe" "native" "msvcrt"
POL_Wine_OverrideDLL_App "firefox.exe" "" "msvcrt" # To disable the DLL
</pre>

=== POL_Wine_WaitBefore (4.0.15+) ===

'''Arguments:'''

# 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:'''

# 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:'''
<pre class="playonlinux code">
POL_Wine_WaitExit "$TITLE"
</pre>

=== 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:'''
<pre class="playonlinux code">
POL_Wine_reboot
</pre>

== Debugging commands ==

=== POL_Debug_Init (4.0+) ===

'''Description:'''

Start debugging system.

'''Example:'''
<pre class="playonlinux code">
POL_Debug_Init
</pre>

=== POL_Debug_Message (4.0+) ===

'''Arguments:'''

# 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:'''
<pre class="playonlinux code">
POL_Debug_Message "Modifying config.cfg file."
</pre>

=== POL_Debug_Warning (4.0+) ===

'''Arguments:'''

# 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:'''
<pre class="playonlinux code">
POL_Debug_Warning "File config.cfg did not exist, creating one."
</pre>

=== POL_Debug_Error (4.0+) ===

'''Arguments:'''

# 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:'''
<pre class="playonlinux code">
POL_Debug_Error "Error while modifying config.cfg file"
</pre>

=== POL_Debug_Fatal (4.0+) ===

'''Arguments:'''

# Message.

'''Description:'''

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

'''Prerequisite:'''

The command POL_Debug_Init must have been used beforehand.

'''Example:'''
<pre class="playonlinux code">
POL_Debug_Fatal "Error while modifying config.cfg file"
</pre>

'''Previous:''' [[Scripting - Chapter 10: Script Translation|Chapter 10: Script Translation]]

[[Category:Scripting]]

Scripting - Chapter 11: List of Functions

2015-10-11T19:53:18Z

Petch: /* POL_SetupWindow_Close (4.0+) */ Add comment about automated bug reports

== 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:'''

# Optional --force option to override any cached images
# URL of top image.
# URL of left image.
# 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_v2", etc.

'''Prerequisite:'''

This statement must be used before '''POL_SetupWindow_Init'''.

'''Example:'''
<pre class="playonlinux code">
POL_GetSetupImages "http://files.playonlinux.com/resources/setups/AC2/top.jpg" "http://files.playonlinux.com/resources/setups/AC2/left.jpg" "$TITLE"
</pre>

=== 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:'''
<pre class="playonlinux code">
POL_SetupWindow_Init
</pre>

=== 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, it is recommended to use '''POL_SetupWindow_Close''' as late as possible in the script.

If some statement error has been detected during the execution of the script by the embedded debugger (see Debugger statements below), 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:'''
<pre class="playonlinux code">
POL_SetupWindow_Close
</pre>

== PlayOnLinux graphical interface ==

{{Warning|All the functions below need the command POL_SetupWindow_Init to be executed beforehand.}}

=== POL_SetupWindow_presentation (4.0+) ===

'''Arguments:'''

# Software name (often $TITLE).
# Software publisher.
# Site of the publisher.
# Script author.
# Prefix name (usually $PREFIX).

'''Description:'''

Present the software.

'''Example:'''
<pre class="playonlinux code">
POL_SetupWindow_presentation "$TITLE" "Mozilla" "http://www.mozilla.com" "SuperPlumus and NSLW" "$PREFIX"
</pre>

=== POL_SetupWindow_free_presentation (4.0+) ===

'''Arguments:'''

# Software name (often $TITLE).
# Message.

'''Description:'''

Present the software with more freedom than POL_SetupWindow_presentation.

'''Example:'''
<pre class="playonlinux code">
POL_SetupWindow_free_presentation "$TITLE" "Welcome to Mozilla Firefox installation wizard."
</pre>

=== POL_SetupWindow_message (4.0+) ===

'''Arguments:'''

# Message.
# Title (often $TITLE).

'''Description:'''

Display a message.

'''Example:'''
<pre class="playonlinux code">
POL_SetupWindow_message "Hello world!" "$TITLE"
</pre>

=== check_one - POL_SetupWindow_missing (4.0-4.1.1) ===

'''Arguments for check_one:'''

# Program that must be present.
# 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:'''
<pre class="playonlinux code">
check_one "p7zip" "p7zip"
POL_SetupWindow_missing
</pre>

=== POL_SetupWindow_file (4.0+) ===

'''Arguments:'''

# Message.
# Title (often $TITLE).
# File to display.

'''Description:'''

Display the content of a file.

'''Example:'''
<pre class="playonlinux code">
POL_SetupWindow_file "Changelog" "$TITLE" "$POL_System_TmpDir/changelog.txt"
</pre>

=== POL_SetupWindow_licence (4.0+) ===

'''Arguments:'''

# Message.
# Title (often $TITLE).
# File to display.

'''Description:'''

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

Useful for displaying licenses.

'''Example:'''
<pre class="playonlinux code">
POL_SetupWindow_licence "Licence:" "$TITLE" "$POL_System_TmpDir/licence.txt"
</pre>

=== POL_SetupWindow_pulsebar - POL_SetupWindow_pulse - POL_SetupWindow_set_text (4.0+) ===

'''Arguments for POL_SetupWindow_pulsebar:'''

# Message.
# Title (often $TITLE).

'''Arguments for POL_SetupWindow_pulse:'''

# Percentage.

'''Arguments for POL_SetupWindow_set_text:'''

# 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:'''
<pre class="playonlinux code">
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"
</pre>

=== POL_SetupWindow_wait (4.0+) ===

'''Arguments:'''

# Message.
# Title (often $TITLE).

'''Description:'''

Display an indeterminate progress bar.

'''Example:'''
<pre class="playonlinux code">
POL_SetupWindow_wait "Please wait" "$TITLE"
</pre>

=== POL_SetupWindow_textbox (4.0+) ===

'''Arguments:'''

# Message.
# Title (often $TITLE).
# 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:'''
<pre class="playonlinux code">
POL_SetupWindow_textbox "Votre pseudo :" "$TITLE"
</pre>

=== POL_SetupWindow_textbox_multiline (4.0+) ===

'''Arguments:'''

# Message.
# Title (often $TITLE).
# 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:'''
<pre class="playonlinux code">
POL_SetupWindow_textbox_multiline "Enter a description for the program" "$TITLE"
</pre>

=== POL_SetupWindow_browse (4.0+) ===

'''Arguments:'''

# Message.
# Title (often $TITLE).
# 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:'''
<pre class="playonlinux code">
POL_SetupWindow_browse "Please select the program." "$TITLE"
</pre>

=== POL_SetupWindow_question (4.0+) ===

'''Arguments:'''

# Message.
# 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:'''
<pre class="playonlinux code">
POL_SetupWindow_question "Message" "Title"
</pre>

=== POL_SetupWindow_menu (4.0+) ===

'''Arguments:'''

# Message.
# Title (often $TITLE).
# Available choices.
# 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:'''
<pre class="playonlinux code">
POL_SetupWindow_menu "What's your favorite color?" "$TITLE" "Red~Green~Blue" "~"
</pre>

=== POL_SetupWindow_menu_num (4.0+) ===

'''Arguments:'''

# Message.
# Title (often $TITLE).
# Available choices.
# 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:'''
<pre class="playonlinux code">
POL_SetupWindow_menu_num "What's your favorite color?" "$TITLE" "Red~Green~Blue" "~"
</pre>

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

=== POL_SetupWindow_menu_list (4.0+) ===

'''Arguments:'''

# Message.
# Title (often $TITLE).
# Available choices.
# Separator character (often ~ or -).
# 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:'''
<pre class="playonlinux code">
POL_SetupWindow_menu_list "What's your favorite color?" "$TITLE" "Red~Green~Blue" "~"
</pre>

=== POL_SetupWindow_checkbox_list (4.0+) ===

'''Arguments:'''

# Message.
# Title (often $TITLE).
# Available choices.
# 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:'''
<pre class="playonlinux code">
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
</pre>

=== 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:'''
<pre class="playonlinux code">
POL_SetupWindow_cdrom
</pre>

=== POL_SetupWindow_check_cdrom (4.0+) ===

'''Arguments:'''

# 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:'''
<pre class="playonlinux code">
POL_SetupWindow_check_cdrom "Data/32_icon.ico"
</pre>

=== POL_SetupWindow_InstallMethod (4.0+) ===

'''Arguments:'''

# 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:'''
<pre class="playonlinux code">
POL_SetupWindow_InstallMethod "LOCAL,CD,STEAM"
</pre>

== POL_RequiredVersion (4.0.15+) ==

'''Arguments:'''

# 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, it itself only appeared in PlayOnLinux 4.0.15, and PlayOnLinux 4.0.14 is still the default in some distributions; 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_AdvisedVersion (4.0.15+) ==

'''Arguments:'''

# 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:'''

# Executable filename.
# Launcher name (often $TITLE).
# Optional name of the icon to download from PlayOnLinux website.
# Optional executable arguments.
# 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 [http://linux.die.net/man/7/glob 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 [http://standards.freedesktop.org/menu-spec/latest/apa.html main] and [http://standards.freedesktop.org/menu-spec/latest/apas02.html 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:'''
<pre class="playonlinux code">
POL_Shortcut "firefox.exe" "$TITLE"
</pre>

== POL_Shortcut_InsertBeforeWine (4.0+) ==

'''Arguments:'''

# Launcher name (often $TITLE).
# Command to add.

'''Description:'''

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

'''Example:'''
<pre class="playonlinux code">
POL_Shortcut_InsertBeforeWine "Jedi Knight II" "export __GL_ExtensionStringVersion=17700"
</pre>

== POL_Shortcut_QuietDebug (4.0.17+) ==
'''Arguments:'''

# 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:'''
# Launcher name (often $TITLE).
# 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:'''

# URL to open.

'''Description:'''

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

'''Example:'''
<pre class="playonlinux code">
POL_Browser "http://www.playonlinux.com"
</pre>

== POL_Download (4.0+) ==

'''Arguments:'''

# URL to download.
# (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:'''

# URL to download.
# Expected MD5 digest of the downloaded file
# (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:'''

# 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:'''
<pre class="playonlinux code">
POL_System_TmpCreate "$PREFIX"
</pre>

== POL_System_TmpDelete (4.0+) ==

'''Description:'''

Removes the script's temporary directory.

'''Example:'''
<pre class="playonlinux code">
POL_System_TmpDelete
</pre>

== POL_System_SetArch (4.0+) ==

'''Arguments:'''

# 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:'''
<pre class="playonlinux code">
POL_System_SetArch "auto"
</pre>

== POL_Call (4.0+) ==

'''Arguments:'''

# Function name.
# 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|Components and Functions]]).

'''Prerequisite:'''

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

'''Example:'''
<pre class="playonlinux code">
POL_Call POL_Install_vcrun6
</pre>

== Wine-related functions ==

=== POL_Wine_SelectPrefix (4.0+) ===

'''Arguments:'''

# 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:'''
<pre class="playonlinux code">
POL_Wine_SelectPrefix "$PREFIX"
</pre>

=== POL_Wine_PrefixExists (4.0+) ===

'''Arguments:'''

# 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:'''
<pre class="playonlinux code">
if [ "$(POL_Wine_PrefixExists "$PREFIX")" = "False" ]
then
# The préfixe doesn't exist
fi
</pre>

=== POL_Wine_PrefixCreate (4.0+) ===

'''Arguments:'''

# 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:'''
<pre class="playonlinux code">
POL_Wine_PrefixCreate "1.3.4"
</pre>

=== 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:'''

# 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:'''
<pre class="playonlinux code">
POL_SetupWindow_VMS "128"
</pre>

=== Set_OS (4.0+) ===

'''Arguments:'''

# Windows version to emulate.
# 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:'''
<pre class="playonlinux code">
Set_OS "win2k"
</pre>

=== Set_Managed (4.0+) ===

'''Arguments:'''

# 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:'''
<pre class="playonlinux code">
Set_Managed "Off"
</pre>

=== Set_SoundDriver (4.0+) ===

'''Arguments:'''

# alsa/oss/esd.

'''Description:'''

Set the audio driver Wine will use.

{{Info|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:'''
<pre class="playonlinux code">
Set_SoundDriver "alsa"
</pre>

=== POL_Wine_Direct3D (4.0+) ===

'''Arguments:'''

# Setting to create/modify.
# New setting value.

'''Description:'''

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

'''Allowed values:'''

See [http://wiki.winehq.org/UsefulRegistryKeys WineHQ's Wiki].

'''Prerequisite:'''

The commands POL_Wine_SelectPrefix and POL_Wine_PrefixCreate must have been used beforehand.

'''Example:'''
<pre class="playonlinux code">
POL_Wine_Direct3D "UseGLSL" "disabled"
</pre>

=== POL_Wine_X11Drv (4.0.14+) ===

'''Arguments:'''

# Setting to create/modify.
# New setting value.

'''Description:'''

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

'''Allowed values:'''

See [http://wiki.winehq.org/UsefulRegistryKeys WineHQ's Wiki].

'''Prerequisite:'''

The commands POL_Wine_SelectPrefix and POL_Wine_PrefixCreate must have been used beforehand.

'''Example:'''
<pre class="playonlinux code">
POL_Wine_X11Drv "DXGrab" "Y"
</pre>

=== POL_Wine_DirectSound (4.0+) ===

'''Arguments:'''

# Setting to create/modify.
# New setting value.

'''Description:'''

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

'''Allowed values:'''

See [http://wiki.winehq.org/UsefulRegistryKeys WineHQ's Wiki].

'''Prerequisite:'''

The commands POL_Wine_SelectPrefix and POL_Wine_PrefixCreate must have been used beforehand.

'''Example:'''
<pre class="playonlinux code">
POL_Wine_DirectSound "HardwareAcceleration" "Emulation"
</pre>

=== POL_Wine_DirectInput (4.0+) ===

'''Arguments:'''

# Setting to create/modify.
# New setting value.

'''Description:'''

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

'''Allowed values:'''

See [http://wiki.winehq.org/UsefulRegistryKeys WineHQ's Wiki].

'''Prerequisite:'''

The commands POL_Wine_SelectPrefix and POL_Wine_PrefixCreate must have been used beforehand.

'''Example:'''
<pre class="playonlinux code">
POL_Wine_DirectInput "MouseWarpOverride" "force"
</pre>

=== POL_Wine_GetRegValue (4.0+) ===

'''Arguments:'''

# 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:'''
<pre class="playonlinux code">
VALUE="$(POL_Wine_GetRegValue "MouseWarpOverride")"
</pre>

=== Set_Desktop (4.0+) ===

'''Arguments:'''

# On/Off.
# Virtual desktop width (if it is enabled).
# 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:'''
<pre class="playonlinux code">
Set_Desktop "On" "1024" "768"
</pre>

=== Set_WineWindowTitle (4.0+) ===

'''Arguments:'''

# 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:'''
<pre class="playonlinux code">
Set_WineWindowTitle "$TITLE"
</pre>

=== 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:'''
<pre class="playonlinux code">
POL_Wine_InstallFonts
</pre>

=== 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:'''
<pre class="playonlinux code">
POL_Wine_SetVideoDriver
</pre>

=== POL_Wine_OverrideDLL (4.0+) ===

'''Arguments:'''

# Mode of override.
# 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:'''
<pre class="playonlinux code">
POL_Wine_OverrideDLL "native" "msvcrt"
POL_Wine_OverrideDLL "" "msvcrt" # To disable the DLL
</pre>

=== POL_Wine_OverrideDLL_App (4.0+) ===

'''Arguments:'''

# Executable name.
# Mode of override.
# 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:'''
<pre class="playonlinux code">
POL_Wine_OverrideDLL_App "firefox.exe" "native" "msvcrt"
POL_Wine_OverrideDLL_App "firefox.exe" "" "msvcrt" # To disable the DLL
</pre>

=== POL_Wine_WaitBefore (4.0.15+) ===

'''Arguments:'''

# 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:'''

# 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:'''
<pre class="playonlinux code">
POL_Wine_WaitExit "$TITLE"
</pre>

=== 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:'''
<pre class="playonlinux code">
POL_Wine_reboot
</pre>

== Debugging commands ==

=== POL_Debug_Init (4.0+) ===

'''Description:'''

Start debugging system.

'''Example:'''
<pre class="playonlinux code">
POL_Debug_Init
</pre>

=== POL_Debug_Message (4.0+) ===

'''Arguments:'''

# 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:'''
<pre class="playonlinux code">
POL_Debug_Message "Modifying config.cfg file."
</pre>

=== POL_Debug_Warning (4.0+) ===

'''Arguments:'''

# 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:'''
<pre class="playonlinux code">
POL_Debug_Warning "File config.cfg did not exist, creating one."
</pre>

=== POL_Debug_Error (4.0+) ===

'''Arguments:'''

# 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:'''
<pre class="playonlinux code">
POL_Debug_Error "Error while modifying config.cfg file"
</pre>

=== POL_Debug_Fatal (4.0+) ===

'''Arguments:'''

# Message.

'''Description:'''

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

'''Prerequisite:'''

The command POL_Debug_Init must have been used beforehand.

'''Example:'''
<pre class="playonlinux code">
POL_Debug_Fatal "Error while modifying config.cfg file"
</pre>

'''Previous:''' [[Scripting - Chapter 10: Script Translation|Chapter 10: Script Translation]]

[[Category:Scripting]]

Scripting - Chapter 11: List of Functions

2015-10-11T19:47:32Z

Petch: /* POL_SetupWindow_Init (4.0+) */ drop some double quotes, too many of them already

== 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:'''

# Optional --force option to override any cached images
# URL of top image.
# URL of left image.
# 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_v2", etc.

'''Prerequisite:'''

This statement must be used before '''POL_SetupWindow_Init'''.

'''Example:'''
<pre class="playonlinux code">
POL_GetSetupImages "http://files.playonlinux.com/resources/setups/AC2/top.jpg" "http://files.playonlinux.com/resources/setups/AC2/left.jpg" "$TITLE"
</pre>

=== 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:'''
<pre class="playonlinux code">
POL_SetupWindow_Init
</pre>

=== 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, it is recommended to use '''POL_SetupWindow_Close''' as late as possible in the script.

'''Example:'''
<pre class="playonlinux code">
POL_SetupWindow_Close
</pre>

== PlayOnLinux graphical interface ==

{{Warning|All the functions below need the command POL_SetupWindow_Init to be executed beforehand.}}

=== POL_SetupWindow_presentation (4.0+) ===

'''Arguments:'''

# Software name (often $TITLE).
# Software publisher.
# Site of the publisher.
# Script author.
# Prefix name (usually $PREFIX).

'''Description:'''

Present the software.

'''Example:'''
<pre class="playonlinux code">
POL_SetupWindow_presentation "$TITLE" "Mozilla" "http://www.mozilla.com" "SuperPlumus and NSLW" "$PREFIX"
</pre>

=== POL_SetupWindow_free_presentation (4.0+) ===

'''Arguments:'''

# Software name (often $TITLE).
# Message.

'''Description:'''

Present the software with more freedom than POL_SetupWindow_presentation.

'''Example:'''
<pre class="playonlinux code">
POL_SetupWindow_free_presentation "$TITLE" "Welcome to Mozilla Firefox installation wizard."
</pre>

=== POL_SetupWindow_message (4.0+) ===

'''Arguments:'''

# Message.
# Title (often $TITLE).

'''Description:'''

Display a message.

'''Example:'''
<pre class="playonlinux code">
POL_SetupWindow_message "Hello world!" "$TITLE"
</pre>

=== check_one - POL_SetupWindow_missing (4.0-4.1.1) ===

'''Arguments for check_one:'''

# Program that must be present.
# 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:'''
<pre class="playonlinux code">
check_one "p7zip" "p7zip"
POL_SetupWindow_missing
</pre>

=== POL_SetupWindow_file (4.0+) ===

'''Arguments:'''

# Message.
# Title (often $TITLE).
# File to display.

'''Description:'''

Display the content of a file.

'''Example:'''
<pre class="playonlinux code">
POL_SetupWindow_file "Changelog" "$TITLE" "$POL_System_TmpDir/changelog.txt"
</pre>

=== POL_SetupWindow_licence (4.0+) ===

'''Arguments:'''

# Message.
# Title (often $TITLE).
# File to display.

'''Description:'''

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

Useful for displaying licenses.

'''Example:'''
<pre class="playonlinux code">
POL_SetupWindow_licence "Licence:" "$TITLE" "$POL_System_TmpDir/licence.txt"
</pre>

=== POL_SetupWindow_pulsebar - POL_SetupWindow_pulse - POL_SetupWindow_set_text (4.0+) ===

'''Arguments for POL_SetupWindow_pulsebar:'''

# Message.
# Title (often $TITLE).

'''Arguments for POL_SetupWindow_pulse:'''

# Percentage.

'''Arguments for POL_SetupWindow_set_text:'''

# 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:'''
<pre class="playonlinux code">
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"
</pre>

=== POL_SetupWindow_wait (4.0+) ===

'''Arguments:'''

# Message.
# Title (often $TITLE).

'''Description:'''

Display an indeterminate progress bar.

'''Example:'''
<pre class="playonlinux code">
POL_SetupWindow_wait "Please wait" "$TITLE"
</pre>

=== POL_SetupWindow_textbox (4.0+) ===

'''Arguments:'''

# Message.
# Title (often $TITLE).
# 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:'''
<pre class="playonlinux code">
POL_SetupWindow_textbox "Votre pseudo :" "$TITLE"
</pre>

=== POL_SetupWindow_textbox_multiline (4.0+) ===

'''Arguments:'''

# Message.
# Title (often $TITLE).
# 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:'''
<pre class="playonlinux code">
POL_SetupWindow_textbox_multiline "Enter a description for the program" "$TITLE"
</pre>

=== POL_SetupWindow_browse (4.0+) ===

'''Arguments:'''

# Message.
# Title (often $TITLE).
# 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:'''
<pre class="playonlinux code">
POL_SetupWindow_browse "Please select the program." "$TITLE"
</pre>

=== POL_SetupWindow_question (4.0+) ===

'''Arguments:'''

# Message.
# 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:'''
<pre class="playonlinux code">
POL_SetupWindow_question "Message" "Title"
</pre>

=== POL_SetupWindow_menu (4.0+) ===

'''Arguments:'''

# Message.
# Title (often $TITLE).
# Available choices.
# 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:'''
<pre class="playonlinux code">
POL_SetupWindow_menu "What's your favorite color?" "$TITLE" "Red~Green~Blue" "~"
</pre>

=== POL_SetupWindow_menu_num (4.0+) ===

'''Arguments:'''

# Message.
# Title (often $TITLE).
# Available choices.
# 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:'''
<pre class="playonlinux code">
POL_SetupWindow_menu_num "What's your favorite color?" "$TITLE" "Red~Green~Blue" "~"
</pre>

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

=== POL_SetupWindow_menu_list (4.0+) ===

'''Arguments:'''

# Message.
# Title (often $TITLE).
# Available choices.
# Separator character (often ~ or -).
# 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:'''
<pre class="playonlinux code">
POL_SetupWindow_menu_list "What's your favorite color?" "$TITLE" "Red~Green~Blue" "~"
</pre>

=== POL_SetupWindow_checkbox_list (4.0+) ===

'''Arguments:'''

# Message.
# Title (often $TITLE).
# Available choices.
# 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:'''
<pre class="playonlinux code">
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
</pre>

=== 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:'''
<pre class="playonlinux code">
POL_SetupWindow_cdrom
</pre>

=== POL_SetupWindow_check_cdrom (4.0+) ===

'''Arguments:'''

# 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:'''
<pre class="playonlinux code">
POL_SetupWindow_check_cdrom "Data/32_icon.ico"
</pre>

=== POL_SetupWindow_InstallMethod (4.0+) ===

'''Arguments:'''

# 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:'''
<pre class="playonlinux code">
POL_SetupWindow_InstallMethod "LOCAL,CD,STEAM"
</pre>

== POL_RequiredVersion (4.0.15+) ==

'''Arguments:'''

# 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, it itself only appeared in PlayOnLinux 4.0.15, and PlayOnLinux 4.0.14 is still the default in some distributions; 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_AdvisedVersion (4.0.15+) ==

'''Arguments:'''

# 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:'''

# Executable filename.
# Launcher name (often $TITLE).
# Optional name of the icon to download from PlayOnLinux website.
# Optional executable arguments.
# 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 [http://linux.die.net/man/7/glob 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 [http://standards.freedesktop.org/menu-spec/latest/apa.html main] and [http://standards.freedesktop.org/menu-spec/latest/apas02.html 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:'''
<pre class="playonlinux code">
POL_Shortcut "firefox.exe" "$TITLE"
</pre>

== POL_Shortcut_InsertBeforeWine (4.0+) ==

'''Arguments:'''

# Launcher name (often $TITLE).
# Command to add.

'''Description:'''

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

'''Example:'''
<pre class="playonlinux code">
POL_Shortcut_InsertBeforeWine "Jedi Knight II" "export __GL_ExtensionStringVersion=17700"
</pre>

== POL_Shortcut_QuietDebug (4.0.17+) ==
'''Arguments:'''

# 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:'''
# Launcher name (often $TITLE).
# 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:'''

# URL to open.

'''Description:'''

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

'''Example:'''
<pre class="playonlinux code">
POL_Browser "http://www.playonlinux.com"
</pre>

== POL_Download (4.0+) ==

'''Arguments:'''

# URL to download.
# (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:'''

# URL to download.
# Expected MD5 digest of the downloaded file
# (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:'''

# 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:'''
<pre class="playonlinux code">
POL_System_TmpCreate "$PREFIX"
</pre>

== POL_System_TmpDelete (4.0+) ==

'''Description:'''

Removes the script's temporary directory.

'''Example:'''
<pre class="playonlinux code">
POL_System_TmpDelete
</pre>

== POL_System_SetArch (4.0+) ==

'''Arguments:'''

# 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:'''
<pre class="playonlinux code">
POL_System_SetArch "auto"
</pre>

== POL_Call (4.0+) ==

'''Arguments:'''

# Function name.
# 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|Components and Functions]]).

'''Prerequisite:'''

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

'''Example:'''
<pre class="playonlinux code">
POL_Call POL_Install_vcrun6
</pre>

== Wine-related functions ==

=== POL_Wine_SelectPrefix (4.0+) ===

'''Arguments:'''

# 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:'''
<pre class="playonlinux code">
POL_Wine_SelectPrefix "$PREFIX"
</pre>

=== POL_Wine_PrefixExists (4.0+) ===

'''Arguments:'''

# 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:'''
<pre class="playonlinux code">
if [ "$(POL_Wine_PrefixExists "$PREFIX")" = "False" ]
then
# The préfixe doesn't exist
fi
</pre>

=== POL_Wine_PrefixCreate (4.0+) ===

'''Arguments:'''

# 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:'''
<pre class="playonlinux code">
POL_Wine_PrefixCreate "1.3.4"
</pre>

=== 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:'''

# 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:'''
<pre class="playonlinux code">
POL_SetupWindow_VMS "128"
</pre>

=== Set_OS (4.0+) ===

'''Arguments:'''

# Windows version to emulate.
# 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:'''
<pre class="playonlinux code">
Set_OS "win2k"
</pre>

=== Set_Managed (4.0+) ===

'''Arguments:'''

# 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:'''
<pre class="playonlinux code">
Set_Managed "Off"
</pre>

=== Set_SoundDriver (4.0+) ===

'''Arguments:'''

# alsa/oss/esd.

'''Description:'''

Set the audio driver Wine will use.

{{Info|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:'''
<pre class="playonlinux code">
Set_SoundDriver "alsa"
</pre>

=== POL_Wine_Direct3D (4.0+) ===

'''Arguments:'''

# Setting to create/modify.
# New setting value.

'''Description:'''

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

'''Allowed values:'''

See [http://wiki.winehq.org/UsefulRegistryKeys WineHQ's Wiki].

'''Prerequisite:'''

The commands POL_Wine_SelectPrefix and POL_Wine_PrefixCreate must have been used beforehand.

'''Example:'''
<pre class="playonlinux code">
POL_Wine_Direct3D "UseGLSL" "disabled"
</pre>

=== POL_Wine_X11Drv (4.0.14+) ===

'''Arguments:'''

# Setting to create/modify.
# New setting value.

'''Description:'''

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

'''Allowed values:'''

See [http://wiki.winehq.org/UsefulRegistryKeys WineHQ's Wiki].

'''Prerequisite:'''

The commands POL_Wine_SelectPrefix and POL_Wine_PrefixCreate must have been used beforehand.

'''Example:'''
<pre class="playonlinux code">
POL_Wine_X11Drv "DXGrab" "Y"
</pre>

=== POL_Wine_DirectSound (4.0+) ===

'''Arguments:'''

# Setting to create/modify.
# New setting value.

'''Description:'''

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

'''Allowed values:'''

See [http://wiki.winehq.org/UsefulRegistryKeys WineHQ's Wiki].

'''Prerequisite:'''

The commands POL_Wine_SelectPrefix and POL_Wine_PrefixCreate must have been used beforehand.

'''Example:'''
<pre class="playonlinux code">
POL_Wine_DirectSound "HardwareAcceleration" "Emulation"
</pre>

=== POL_Wine_DirectInput (4.0+) ===

'''Arguments:'''

# Setting to create/modify.
# New setting value.

'''Description:'''

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

'''Allowed values:'''

See [http://wiki.winehq.org/UsefulRegistryKeys WineHQ's Wiki].

'''Prerequisite:'''

The commands POL_Wine_SelectPrefix and POL_Wine_PrefixCreate must have been used beforehand.

'''Example:'''
<pre class="playonlinux code">
POL_Wine_DirectInput "MouseWarpOverride" "force"
</pre>

=== POL_Wine_GetRegValue (4.0+) ===

'''Arguments:'''

# 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:'''
<pre class="playonlinux code">
VALUE="$(POL_Wine_GetRegValue "MouseWarpOverride")"
</pre>

=== Set_Desktop (4.0+) ===

'''Arguments:'''

# On/Off.
# Virtual desktop width (if it is enabled).
# 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:'''
<pre class="playonlinux code">
Set_Desktop "On" "1024" "768"
</pre>

=== Set_WineWindowTitle (4.0+) ===

'''Arguments:'''

# 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:'''
<pre class="playonlinux code">
Set_WineWindowTitle "$TITLE"
</pre>

=== 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:'''
<pre class="playonlinux code">
POL_Wine_InstallFonts
</pre>

=== 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:'''
<pre class="playonlinux code">
POL_Wine_SetVideoDriver
</pre>

=== POL_Wine_OverrideDLL (4.0+) ===

'''Arguments:'''

# Mode of override.
# 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:'''
<pre class="playonlinux code">
POL_Wine_OverrideDLL "native" "msvcrt"
POL_Wine_OverrideDLL "" "msvcrt" # To disable the DLL
</pre>

=== POL_Wine_OverrideDLL_App (4.0+) ===

'''Arguments:'''

# Executable name.
# Mode of override.
# 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:'''
<pre class="playonlinux code">
POL_Wine_OverrideDLL_App "firefox.exe" "native" "msvcrt"
POL_Wine_OverrideDLL_App "firefox.exe" "" "msvcrt" # To disable the DLL
</pre>

=== POL_Wine_WaitBefore (4.0.15+) ===

'''Arguments:'''

# 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:'''

# 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:'''
<pre class="playonlinux code">
POL_Wine_WaitExit "$TITLE"
</pre>

=== 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:'''
<pre class="playonlinux code">
POL_Wine_reboot
</pre>

== Debugging commands ==

=== POL_Debug_Init (4.0+) ===

'''Description:'''

Start debugging system.

'''Example:'''
<pre class="playonlinux code">
POL_Debug_Init
</pre>

=== POL_Debug_Message (4.0+) ===

'''Arguments:'''

# 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:'''
<pre class="playonlinux code">
POL_Debug_Message "Modifying config.cfg file."
</pre>

=== POL_Debug_Warning (4.0+) ===

'''Arguments:'''

# 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:'''
<pre class="playonlinux code">
POL_Debug_Warning "File config.cfg did not exist, creating one."
</pre>

=== POL_Debug_Error (4.0+) ===

'''Arguments:'''

# 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:'''
<pre class="playonlinux code">
POL_Debug_Error "Error while modifying config.cfg file"
</pre>

=== POL_Debug_Fatal (4.0+) ===

'''Arguments:'''

# Message.

'''Description:'''

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

'''Prerequisite:'''

The command POL_Debug_Init must have been used beforehand.

'''Example:'''
<pre class="playonlinux code">
POL_Debug_Fatal "Error while modifying config.cfg file"
</pre>

'''Previous:''' [[Scripting - Chapter 10: Script Translation|Chapter 10: Script Translation]]

[[Category:Scripting]]

Scripting - Chapter 11: List of Functions

2015-10-11T19:46:52Z

Petch: Try to flesh out POL_SetupWindow_Init/POL_SetupWindow_Close descriptions

== 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:'''

# Optional --force option to override any cached images
# URL of top image.
# URL of left image.
# 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_v2", etc.

'''Prerequisite:'''

This statement must be used before '''POL_SetupWindow_Init'''.

'''Example:'''
<pre class="playonlinux code">
POL_GetSetupImages "http://files.playonlinux.com/resources/setups/AC2/top.jpg" "http://files.playonlinux.com/resources/setups/AC2/left.jpg" "$TITLE"
</pre>

=== 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:'''
<pre class="playonlinux code">
POL_SetupWindow_Init
</pre>

=== 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, it is recommended to use '''POL_SetupWindow_Close''' as late as possible in the script.

'''Example:'''
<pre class="playonlinux code">
POL_SetupWindow_Close
</pre>

== PlayOnLinux graphical interface ==

{{Warning|All the functions below need the command POL_SetupWindow_Init to be executed beforehand.}}

=== POL_SetupWindow_presentation (4.0+) ===

'''Arguments:'''

# Software name (often $TITLE).
# Software publisher.
# Site of the publisher.
# Script author.
# Prefix name (usually $PREFIX).

'''Description:'''

Present the software.

'''Example:'''
<pre class="playonlinux code">
POL_SetupWindow_presentation "$TITLE" "Mozilla" "http://www.mozilla.com" "SuperPlumus and NSLW" "$PREFIX"
</pre>

=== POL_SetupWindow_free_presentation (4.0+) ===

'''Arguments:'''

# Software name (often $TITLE).
# Message.

'''Description:'''

Present the software with more freedom than POL_SetupWindow_presentation.

'''Example:'''
<pre class="playonlinux code">
POL_SetupWindow_free_presentation "$TITLE" "Welcome to Mozilla Firefox installation wizard."
</pre>

=== POL_SetupWindow_message (4.0+) ===

'''Arguments:'''

# Message.
# Title (often $TITLE).

'''Description:'''

Display a message.

'''Example:'''
<pre class="playonlinux code">
POL_SetupWindow_message "Hello world!" "$TITLE"
</pre>

=== check_one - POL_SetupWindow_missing (4.0-4.1.1) ===

'''Arguments for check_one:'''

# Program that must be present.
# 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:'''
<pre class="playonlinux code">
check_one "p7zip" "p7zip"
POL_SetupWindow_missing
</pre>

=== POL_SetupWindow_file (4.0+) ===

'''Arguments:'''

# Message.
# Title (often $TITLE).
# File to display.

'''Description:'''

Display the content of a file.

'''Example:'''
<pre class="playonlinux code">
POL_SetupWindow_file "Changelog" "$TITLE" "$POL_System_TmpDir/changelog.txt"
</pre>

=== POL_SetupWindow_licence (4.0+) ===

'''Arguments:'''

# Message.
# Title (often $TITLE).
# File to display.

'''Description:'''

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

Useful for displaying licenses.

'''Example:'''
<pre class="playonlinux code">
POL_SetupWindow_licence "Licence:" "$TITLE" "$POL_System_TmpDir/licence.txt"
</pre>

=== POL_SetupWindow_pulsebar - POL_SetupWindow_pulse - POL_SetupWindow_set_text (4.0+) ===

'''Arguments for POL_SetupWindow_pulsebar:'''

# Message.
# Title (often $TITLE).

'''Arguments for POL_SetupWindow_pulse:'''

# Percentage.

'''Arguments for POL_SetupWindow_set_text:'''

# 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:'''
<pre class="playonlinux code">
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"
</pre>

=== POL_SetupWindow_wait (4.0+) ===

'''Arguments:'''

# Message.
# Title (often $TITLE).

'''Description:'''

Display an indeterminate progress bar.

'''Example:'''
<pre class="playonlinux code">
POL_SetupWindow_wait "Please wait" "$TITLE"
</pre>

=== POL_SetupWindow_textbox (4.0+) ===

'''Arguments:'''

# Message.
# Title (often $TITLE).
# 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:'''
<pre class="playonlinux code">
POL_SetupWindow_textbox "Votre pseudo :" "$TITLE"
</pre>

=== POL_SetupWindow_textbox_multiline (4.0+) ===

'''Arguments:'''

# Message.
# Title (often $TITLE).
# 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:'''
<pre class="playonlinux code">
POL_SetupWindow_textbox_multiline "Enter a description for the program" "$TITLE"
</pre>

=== POL_SetupWindow_browse (4.0+) ===

'''Arguments:'''

# Message.
# Title (often $TITLE).
# 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:'''
<pre class="playonlinux code">
POL_SetupWindow_browse "Please select the program." "$TITLE"
</pre>

=== POL_SetupWindow_question (4.0+) ===

'''Arguments:'''

# Message.
# 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:'''
<pre class="playonlinux code">
POL_SetupWindow_question "Message" "Title"
</pre>

=== POL_SetupWindow_menu (4.0+) ===

'''Arguments:'''

# Message.
# Title (often $TITLE).
# Available choices.
# 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:'''
<pre class="playonlinux code">
POL_SetupWindow_menu "What's your favorite color?" "$TITLE" "Red~Green~Blue" "~"
</pre>

=== POL_SetupWindow_menu_num (4.0+) ===

'''Arguments:'''

# Message.
# Title (often $TITLE).
# Available choices.
# 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:'''
<pre class="playonlinux code">
POL_SetupWindow_menu_num "What's your favorite color?" "$TITLE" "Red~Green~Blue" "~"
</pre>

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

=== POL_SetupWindow_menu_list (4.0+) ===

'''Arguments:'''

# Message.
# Title (often $TITLE).
# Available choices.
# Separator character (often ~ or -).
# 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:'''
<pre class="playonlinux code">
POL_SetupWindow_menu_list "What's your favorite color?" "$TITLE" "Red~Green~Blue" "~"
</pre>

=== POL_SetupWindow_checkbox_list (4.0+) ===

'''Arguments:'''

# Message.
# Title (often $TITLE).
# Available choices.
# 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:'''
<pre class="playonlinux code">
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
</pre>

=== 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:'''
<pre class="playonlinux code">
POL_SetupWindow_cdrom
</pre>

=== POL_SetupWindow_check_cdrom (4.0+) ===

'''Arguments:'''

# 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:'''
<pre class="playonlinux code">
POL_SetupWindow_check_cdrom "Data/32_icon.ico"
</pre>

=== POL_SetupWindow_InstallMethod (4.0+) ===

'''Arguments:'''

# 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:'''
<pre class="playonlinux code">
POL_SetupWindow_InstallMethod "LOCAL,CD,STEAM"
</pre>

== POL_RequiredVersion (4.0.15+) ==

'''Arguments:'''

# 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, it itself only appeared in PlayOnLinux 4.0.15, and PlayOnLinux 4.0.14 is still the default in some distributions; 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_AdvisedVersion (4.0.15+) ==

'''Arguments:'''

# 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:'''

# Executable filename.
# Launcher name (often $TITLE).
# Optional name of the icon to download from PlayOnLinux website.
# Optional executable arguments.
# 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 [http://linux.die.net/man/7/glob 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 [http://standards.freedesktop.org/menu-spec/latest/apa.html main] and [http://standards.freedesktop.org/menu-spec/latest/apas02.html 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:'''
<pre class="playonlinux code">
POL_Shortcut "firefox.exe" "$TITLE"
</pre>

== POL_Shortcut_InsertBeforeWine (4.0+) ==

'''Arguments:'''

# Launcher name (often $TITLE).
# Command to add.

'''Description:'''

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

'''Example:'''
<pre class="playonlinux code">
POL_Shortcut_InsertBeforeWine "Jedi Knight II" "export __GL_ExtensionStringVersion=17700"
</pre>

== POL_Shortcut_QuietDebug (4.0.17+) ==
'''Arguments:'''

# 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:'''
# Launcher name (often $TITLE).
# 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:'''

# URL to open.

'''Description:'''

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

'''Example:'''
<pre class="playonlinux code">
POL_Browser "http://www.playonlinux.com"
</pre>

== POL_Download (4.0+) ==

'''Arguments:'''

# URL to download.
# (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:'''

# URL to download.
# Expected MD5 digest of the downloaded file
# (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:'''

# 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:'''
<pre class="playonlinux code">
POL_System_TmpCreate "$PREFIX"
</pre>

== POL_System_TmpDelete (4.0+) ==

'''Description:'''

Removes the script's temporary directory.

'''Example:'''
<pre class="playonlinux code">
POL_System_TmpDelete
</pre>

== POL_System_SetArch (4.0+) ==

'''Arguments:'''

# 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:'''
<pre class="playonlinux code">
POL_System_SetArch "auto"
</pre>

== POL_Call (4.0+) ==

'''Arguments:'''

# Function name.
# 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|Components and Functions]]).

'''Prerequisite:'''

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

'''Example:'''
<pre class="playonlinux code">
POL_Call POL_Install_vcrun6
</pre>

== Wine-related functions ==

=== POL_Wine_SelectPrefix (4.0+) ===

'''Arguments:'''

# 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:'''
<pre class="playonlinux code">
POL_Wine_SelectPrefix "$PREFIX"
</pre>

=== POL_Wine_PrefixExists (4.0+) ===

'''Arguments:'''

# 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:'''
<pre class="playonlinux code">
if [ "$(POL_Wine_PrefixExists "$PREFIX")" = "False" ]
then
# The préfixe doesn't exist
fi
</pre>

=== POL_Wine_PrefixCreate (4.0+) ===

'''Arguments:'''

# 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:'''
<pre class="playonlinux code">
POL_Wine_PrefixCreate "1.3.4"
</pre>

=== 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:'''

# 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:'''
<pre class="playonlinux code">
POL_SetupWindow_VMS "128"
</pre>

=== Set_OS (4.0+) ===

'''Arguments:'''

# Windows version to emulate.
# 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:'''
<pre class="playonlinux code">
Set_OS "win2k"
</pre>

=== Set_Managed (4.0+) ===

'''Arguments:'''

# 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:'''
<pre class="playonlinux code">
Set_Managed "Off"
</pre>

=== Set_SoundDriver (4.0+) ===

'''Arguments:'''

# alsa/oss/esd.

'''Description:'''

Set the audio driver Wine will use.

{{Info|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:'''
<pre class="playonlinux code">
Set_SoundDriver "alsa"
</pre>

=== POL_Wine_Direct3D (4.0+) ===

'''Arguments:'''

# Setting to create/modify.
# New setting value.

'''Description:'''

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

'''Allowed values:'''

See [http://wiki.winehq.org/UsefulRegistryKeys WineHQ's Wiki].

'''Prerequisite:'''

The commands POL_Wine_SelectPrefix and POL_Wine_PrefixCreate must have been used beforehand.

'''Example:'''
<pre class="playonlinux code">
POL_Wine_Direct3D "UseGLSL" "disabled"
</pre>

=== POL_Wine_X11Drv (4.0.14+) ===

'''Arguments:'''

# Setting to create/modify.
# New setting value.

'''Description:'''

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

'''Allowed values:'''

See [http://wiki.winehq.org/UsefulRegistryKeys WineHQ's Wiki].

'''Prerequisite:'''

The commands POL_Wine_SelectPrefix and POL_Wine_PrefixCreate must have been used beforehand.

'''Example:'''
<pre class="playonlinux code">
POL_Wine_X11Drv "DXGrab" "Y"
</pre>

=== POL_Wine_DirectSound (4.0+) ===

'''Arguments:'''

# Setting to create/modify.
# New setting value.

'''Description:'''

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

'''Allowed values:'''

See [http://wiki.winehq.org/UsefulRegistryKeys WineHQ's Wiki].

'''Prerequisite:'''

The commands POL_Wine_SelectPrefix and POL_Wine_PrefixCreate must have been used beforehand.

'''Example:'''
<pre class="playonlinux code">
POL_Wine_DirectSound "HardwareAcceleration" "Emulation"
</pre>

=== POL_Wine_DirectInput (4.0+) ===

'''Arguments:'''

# Setting to create/modify.
# New setting value.

'''Description:'''

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

'''Allowed values:'''

See [http://wiki.winehq.org/UsefulRegistryKeys WineHQ's Wiki].

'''Prerequisite:'''

The commands POL_Wine_SelectPrefix and POL_Wine_PrefixCreate must have been used beforehand.

'''Example:'''
<pre class="playonlinux code">
POL_Wine_DirectInput "MouseWarpOverride" "force"
</pre>

=== POL_Wine_GetRegValue (4.0+) ===

'''Arguments:'''

# 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:'''
<pre class="playonlinux code">
VALUE="$(POL_Wine_GetRegValue "MouseWarpOverride")"
</pre>

=== Set_Desktop (4.0+) ===

'''Arguments:'''

# On/Off.
# Virtual desktop width (if it is enabled).
# 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:'''
<pre class="playonlinux code">
Set_Desktop "On" "1024" "768"
</pre>

=== Set_WineWindowTitle (4.0+) ===

'''Arguments:'''

# 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:'''
<pre class="playonlinux code">
Set_WineWindowTitle "$TITLE"
</pre>

=== 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:'''
<pre class="playonlinux code">
POL_Wine_InstallFonts
</pre>

=== 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:'''
<pre class="playonlinux code">
POL_Wine_SetVideoDriver
</pre>

=== POL_Wine_OverrideDLL (4.0+) ===

'''Arguments:'''

# Mode of override.
# 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:'''
<pre class="playonlinux code">
POL_Wine_OverrideDLL "native" "msvcrt"
POL_Wine_OverrideDLL "" "msvcrt" # To disable the DLL
</pre>

=== POL_Wine_OverrideDLL_App (4.0+) ===

'''Arguments:'''

# Executable name.
# Mode of override.
# 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:'''
<pre class="playonlinux code">
POL_Wine_OverrideDLL_App "firefox.exe" "native" "msvcrt"
POL_Wine_OverrideDLL_App "firefox.exe" "" "msvcrt" # To disable the DLL
</pre>

=== POL_Wine_WaitBefore (4.0.15+) ===

'''Arguments:'''

# 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:'''

# 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:'''
<pre class="playonlinux code">
POL_Wine_WaitExit "$TITLE"
</pre>

=== 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:'''
<pre class="playonlinux code">
POL_Wine_reboot
</pre>

== Debugging commands ==

=== POL_Debug_Init (4.0+) ===

'''Description:'''

Start debugging system.

'''Example:'''
<pre class="playonlinux code">
POL_Debug_Init
</pre>

=== POL_Debug_Message (4.0+) ===

'''Arguments:'''

# 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:'''
<pre class="playonlinux code">
POL_Debug_Message "Modifying config.cfg file."
</pre>

=== POL_Debug_Warning (4.0+) ===

'''Arguments:'''

# 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:'''
<pre class="playonlinux code">
POL_Debug_Warning "File config.cfg did not exist, creating one."
</pre>

=== POL_Debug_Error (4.0+) ===

'''Arguments:'''

# 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:'''
<pre class="playonlinux code">
POL_Debug_Error "Error while modifying config.cfg file"
</pre>

=== POL_Debug_Fatal (4.0+) ===

'''Arguments:'''

# Message.

'''Description:'''

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

'''Prerequisite:'''

The command POL_Debug_Init must have been used beforehand.

'''Example:'''
<pre class="playonlinux code">
POL_Debug_Fatal "Error while modifying config.cfg file"
</pre>

'''Previous:''' [[Scripting - Chapter 10: Script Translation|Chapter 10: Script Translation]]

[[Category:Scripting]]

Scripting - Chapter 11: List of Functions

2015-10-11T19:33:16Z

Petch: /* POL_GetSetupImages (4.0+) */ Fix formatting

== 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:'''

# Optional --force option to override any cached images
# URL of top image.
# URL of left image.
# 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_v2", etc.

'''Prerequisite:'''

This statement must be used before '''POL_SetupWindow_Init'''.

'''Example:'''
<pre class="playonlinux code">
POL_GetSetupImages "http://files.playonlinux.com/resources/setups/AC2/top.jpg" "http://files.playonlinux.com/resources/setups/AC2/left.jpg" "$TITLE"
</pre>

=== POL_SetupWindow_Init (4.0+) ===

'''Description:'''

Opens the installation wizard window.

'''Example:'''
<pre class="playonlinux code">
POL_SetupWindow_Init
</pre>

=== POL_SetupWindow_Close (4.0+) ===

'''Description:'''

Closes the installation wizard window.

'''Example:'''
<pre class="playonlinux code">
POL_SetupWindow_Close
</pre>

== PlayOnLinux graphical interface ==

{{Warning|All the functions below need the command POL_SetupWindow_Init to be executed beforehand.}}

=== POL_SetupWindow_presentation (4.0+) ===

'''Arguments:'''

# Software name (often $TITLE).
# Software publisher.
# Site of the publisher.
# Script author.
# Prefix name (usually $PREFIX).

'''Description:'''

Present the software.

'''Example:'''
<pre class="playonlinux code">
POL_SetupWindow_presentation "$TITLE" "Mozilla" "http://www.mozilla.com" "SuperPlumus and NSLW" "$PREFIX"
</pre>

=== POL_SetupWindow_free_presentation (4.0+) ===

'''Arguments:'''

# Software name (often $TITLE).
# Message.

'''Description:'''

Present the software with more freedom than POL_SetupWindow_presentation.

'''Example:'''
<pre class="playonlinux code">
POL_SetupWindow_free_presentation "$TITLE" "Welcome to Mozilla Firefox installation wizard."
</pre>

=== POL_SetupWindow_message (4.0+) ===

'''Arguments:'''

# Message.
# Title (often $TITLE).

'''Description:'''

Display a message.

'''Example:'''
<pre class="playonlinux code">
POL_SetupWindow_message "Hello world!" "$TITLE"
</pre>

=== check_one - POL_SetupWindow_missing (4.0-4.1.1) ===

'''Arguments for check_one:'''

# Program that must be present.
# 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:'''
<pre class="playonlinux code">
check_one "p7zip" "p7zip"
POL_SetupWindow_missing
</pre>

=== POL_SetupWindow_file (4.0+) ===

'''Arguments:'''

# Message.
# Title (often $TITLE).
# File to display.

'''Description:'''

Display the content of a file.

'''Example:'''
<pre class="playonlinux code">
POL_SetupWindow_file "Changelog" "$TITLE" "$POL_System_TmpDir/changelog.txt"
</pre>

=== POL_SetupWindow_licence (4.0+) ===

'''Arguments:'''

# Message.
# Title (often $TITLE).
# File to display.

'''Description:'''

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

Useful for displaying licenses.

'''Example:'''
<pre class="playonlinux code">
POL_SetupWindow_licence "Licence:" "$TITLE" "$POL_System_TmpDir/licence.txt"
</pre>

=== POL_SetupWindow_pulsebar - POL_SetupWindow_pulse - POL_SetupWindow_set_text (4.0+) ===

'''Arguments for POL_SetupWindow_pulsebar:'''

# Message.
# Title (often $TITLE).

'''Arguments for POL_SetupWindow_pulse:'''

# Percentage.

'''Arguments for POL_SetupWindow_set_text:'''

# 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:'''
<pre class="playonlinux code">
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"
</pre>

=== POL_SetupWindow_wait (4.0+) ===

'''Arguments:'''

# Message.
# Title (often $TITLE).

'''Description:'''

Display an indeterminate progress bar.

'''Example:'''
<pre class="playonlinux code">
POL_SetupWindow_wait "Please wait" "$TITLE"
</pre>

=== POL_SetupWindow_textbox (4.0+) ===

'''Arguments:'''

# Message.
# Title (often $TITLE).
# 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:'''
<pre class="playonlinux code">
POL_SetupWindow_textbox "Votre pseudo :" "$TITLE"
</pre>

=== POL_SetupWindow_textbox_multiline (4.0+) ===

'''Arguments:'''

# Message.
# Title (often $TITLE).
# 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:'''
<pre class="playonlinux code">
POL_SetupWindow_textbox_multiline "Enter a description for the program" "$TITLE"
</pre>

=== POL_SetupWindow_browse (4.0+) ===

'''Arguments:'''

# Message.
# Title (often $TITLE).
# 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:'''
<pre class="playonlinux code">
POL_SetupWindow_browse "Please select the program." "$TITLE"
</pre>

=== POL_SetupWindow_question (4.0+) ===

'''Arguments:'''

# Message.
# 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:'''
<pre class="playonlinux code">
POL_SetupWindow_question "Message" "Title"
</pre>

=== POL_SetupWindow_menu (4.0+) ===

'''Arguments:'''

# Message.
# Title (often $TITLE).
# Available choices.
# 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:'''
<pre class="playonlinux code">
POL_SetupWindow_menu "What's your favorite color?" "$TITLE" "Red~Green~Blue" "~"
</pre>

=== POL_SetupWindow_menu_num (4.0+) ===

'''Arguments:'''

# Message.
# Title (often $TITLE).
# Available choices.
# 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:'''
<pre class="playonlinux code">
POL_SetupWindow_menu_num "What's your favorite color?" "$TITLE" "Red~Green~Blue" "~"
</pre>

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

=== POL_SetupWindow_menu_list (4.0+) ===

'''Arguments:'''

# Message.
# Title (often $TITLE).
# Available choices.
# Separator character (often ~ or -).
# 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:'''
<pre class="playonlinux code">
POL_SetupWindow_menu_list "What's your favorite color?" "$TITLE" "Red~Green~Blue" "~"
</pre>

=== POL_SetupWindow_checkbox_list (4.0+) ===

'''Arguments:'''

# Message.
# Title (often $TITLE).
# Available choices.
# 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:'''
<pre class="playonlinux code">
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
</pre>

=== 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:'''
<pre class="playonlinux code">
POL_SetupWindow_cdrom
</pre>

=== POL_SetupWindow_check_cdrom (4.0+) ===

'''Arguments:'''

# 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:'''
<pre class="playonlinux code">
POL_SetupWindow_check_cdrom "Data/32_icon.ico"
</pre>

=== POL_SetupWindow_InstallMethod (4.0+) ===

'''Arguments:'''

# 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:'''
<pre class="playonlinux code">
POL_SetupWindow_InstallMethod "LOCAL,CD,STEAM"
</pre>

== POL_RequiredVersion (4.0.15+) ==

'''Arguments:'''

# 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, it itself only appeared in PlayOnLinux 4.0.15, and PlayOnLinux 4.0.14 is still the default in some distributions; 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_AdvisedVersion (4.0.15+) ==

'''Arguments:'''

# 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:'''

# Executable filename.
# Launcher name (often $TITLE).
# Optional name of the icon to download from PlayOnLinux website.
# Optional executable arguments.
# 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 [http://linux.die.net/man/7/glob 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 [http://standards.freedesktop.org/menu-spec/latest/apa.html main] and [http://standards.freedesktop.org/menu-spec/latest/apas02.html 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:'''
<pre class="playonlinux code">
POL_Shortcut "firefox.exe" "$TITLE"
</pre>

== POL_Shortcut_InsertBeforeWine (4.0+) ==

'''Arguments:'''

# Launcher name (often $TITLE).
# Command to add.

'''Description:'''

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

'''Example:'''
<pre class="playonlinux code">
POL_Shortcut_InsertBeforeWine "Jedi Knight II" "export __GL_ExtensionStringVersion=17700"
</pre>

== POL_Shortcut_QuietDebug (4.0.17+) ==
'''Arguments:'''

# 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:'''
# Launcher name (often $TITLE).
# 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:'''

# URL to open.

'''Description:'''

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

'''Example:'''
<pre class="playonlinux code">
POL_Browser "http://www.playonlinux.com"
</pre>

== POL_Download (4.0+) ==

'''Arguments:'''

# URL to download.
# (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:'''

# URL to download.
# Expected MD5 digest of the downloaded file
# (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:'''

# 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:'''
<pre class="playonlinux code">
POL_System_TmpCreate "$PREFIX"
</pre>

== POL_System_TmpDelete (4.0+) ==

'''Description:'''

Removes the script's temporary directory.

'''Example:'''
<pre class="playonlinux code">
POL_System_TmpDelete
</pre>

== POL_System_SetArch (4.0+) ==

'''Arguments:'''

# 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:'''
<pre class="playonlinux code">
POL_System_SetArch "auto"
</pre>

== POL_Call (4.0+) ==

'''Arguments:'''

# Function name.
# 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|Components and Functions]]).

'''Prerequisite:'''

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

'''Example:'''
<pre class="playonlinux code">
POL_Call POL_Install_vcrun6
</pre>

== Wine-related functions ==

=== POL_Wine_SelectPrefix (4.0+) ===

'''Arguments:'''

# 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:'''
<pre class="playonlinux code">
POL_Wine_SelectPrefix "$PREFIX"
</pre>

=== POL_Wine_PrefixExists (4.0+) ===

'''Arguments:'''

# 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:'''
<pre class="playonlinux code">
if [ "$(POL_Wine_PrefixExists "$PREFIX")" = "False" ]
then
# The préfixe doesn't exist
fi
</pre>

=== POL_Wine_PrefixCreate (4.0+) ===

'''Arguments:'''

# 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:'''
<pre class="playonlinux code">
POL_Wine_PrefixCreate "1.3.4"
</pre>

=== 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:'''

# 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:'''
<pre class="playonlinux code">
POL_SetupWindow_VMS "128"
</pre>

=== Set_OS (4.0+) ===

'''Arguments:'''

# Windows version to emulate.
# 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:'''
<pre class="playonlinux code">
Set_OS "win2k"
</pre>

=== Set_Managed (4.0+) ===

'''Arguments:'''

# 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:'''
<pre class="playonlinux code">
Set_Managed "Off"
</pre>

=== Set_SoundDriver (4.0+) ===

'''Arguments:'''

# alsa/oss/esd.

'''Description:'''

Set the audio driver Wine will use.

{{Info|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:'''
<pre class="playonlinux code">
Set_SoundDriver "alsa"
</pre>

=== POL_Wine_Direct3D (4.0+) ===

'''Arguments:'''

# Setting to create/modify.
# New setting value.

'''Description:'''

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

'''Allowed values:'''

See [http://wiki.winehq.org/UsefulRegistryKeys WineHQ's Wiki].

'''Prerequisite:'''

The commands POL_Wine_SelectPrefix and POL_Wine_PrefixCreate must have been used beforehand.

'''Example:'''
<pre class="playonlinux code">
POL_Wine_Direct3D "UseGLSL" "disabled"
</pre>

=== POL_Wine_X11Drv (4.0.14+) ===

'''Arguments:'''

# Setting to create/modify.
# New setting value.

'''Description:'''

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

'''Allowed values:'''

See [http://wiki.winehq.org/UsefulRegistryKeys WineHQ's Wiki].

'''Prerequisite:'''

The commands POL_Wine_SelectPrefix and POL_Wine_PrefixCreate must have been used beforehand.

'''Example:'''
<pre class="playonlinux code">
POL_Wine_X11Drv "DXGrab" "Y"
</pre>

=== POL_Wine_DirectSound (4.0+) ===

'''Arguments:'''

# Setting to create/modify.
# New setting value.

'''Description:'''

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

'''Allowed values:'''

See [http://wiki.winehq.org/UsefulRegistryKeys WineHQ's Wiki].

'''Prerequisite:'''

The commands POL_Wine_SelectPrefix and POL_Wine_PrefixCreate must have been used beforehand.

'''Example:'''
<pre class="playonlinux code">
POL_Wine_DirectSound "HardwareAcceleration" "Emulation"
</pre>

=== POL_Wine_DirectInput (4.0+) ===

'''Arguments:'''

# Setting to create/modify.
# New setting value.

'''Description:'''

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

'''Allowed values:'''

See [http://wiki.winehq.org/UsefulRegistryKeys WineHQ's Wiki].

'''Prerequisite:'''

The commands POL_Wine_SelectPrefix and POL_Wine_PrefixCreate must have been used beforehand.

'''Example:'''
<pre class="playonlinux code">
POL_Wine_DirectInput "MouseWarpOverride" "force"
</pre>

=== POL_Wine_GetRegValue (4.0+) ===

'''Arguments:'''

# 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:'''
<pre class="playonlinux code">
VALUE="$(POL_Wine_GetRegValue "MouseWarpOverride")"
</pre>

=== Set_Desktop (4.0+) ===

'''Arguments:'''

# On/Off.
# Virtual desktop width (if it is enabled).
# 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:'''
<pre class="playonlinux code">
Set_Desktop "On" "1024" "768"
</pre>

=== Set_WineWindowTitle (4.0+) ===

'''Arguments:'''

# 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:'''
<pre class="playonlinux code">
Set_WineWindowTitle "$TITLE"
</pre>

=== 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:'''
<pre class="playonlinux code">
POL_Wine_InstallFonts
</pre>

=== 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:'''
<pre class="playonlinux code">
POL_Wine_SetVideoDriver
</pre>

=== POL_Wine_OverrideDLL (4.0+) ===

'''Arguments:'''

# Mode of override.
# 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:'''
<pre class="playonlinux code">
POL_Wine_OverrideDLL "native" "msvcrt"
POL_Wine_OverrideDLL "" "msvcrt" # To disable the DLL
</pre>

=== POL_Wine_OverrideDLL_App (4.0+) ===

'''Arguments:'''

# Executable name.
# Mode of override.
# 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:'''
<pre class="playonlinux code">
POL_Wine_OverrideDLL_App "firefox.exe" "native" "msvcrt"
POL_Wine_OverrideDLL_App "firefox.exe" "" "msvcrt" # To disable the DLL
</pre>

=== POL_Wine_WaitBefore (4.0.15+) ===

'''Arguments:'''

# 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:'''

# 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:'''
<pre class="playonlinux code">
POL_Wine_WaitExit "$TITLE"
</pre>

=== 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:'''
<pre class="playonlinux code">
POL_Wine_reboot
</pre>

== Debugging commands ==

=== POL_Debug_Init (4.0+) ===

'''Description:'''

Start debugging system.

'''Example:'''
<pre class="playonlinux code">
POL_Debug_Init
</pre>

=== POL_Debug_Message (4.0+) ===

'''Arguments:'''

# 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:'''
<pre class="playonlinux code">
POL_Debug_Message "Modifying config.cfg file."
</pre>

=== POL_Debug_Warning (4.0+) ===

'''Arguments:'''

# 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:'''
<pre class="playonlinux code">
POL_Debug_Warning "File config.cfg did not exist, creating one."
</pre>

=== POL_Debug_Error (4.0+) ===

'''Arguments:'''

# 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:'''
<pre class="playonlinux code">
POL_Debug_Error "Error while modifying config.cfg file"
</pre>

=== POL_Debug_Fatal (4.0+) ===

'''Arguments:'''

# Message.

'''Description:'''

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

'''Prerequisite:'''

The command POL_Debug_Init must have been used beforehand.

'''Example:'''
<pre class="playonlinux code">
POL_Debug_Fatal "Error while modifying config.cfg file"
</pre>

'''Previous:''' [[Scripting - Chapter 10: Script Translation|Chapter 10: Script Translation]]

[[Category:Scripting]]

Scripting - Chapter 11: List of Functions

2015-10-11T19:31:24Z

Petch: Try to flesh out POL_GetSetupImages statement description

== 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:'''

# Optional --force option to override any cached images
# URL of top image.
# URL of left image.
# 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_v2", etc.

'''Prerequisite:'''

This statement must be used before '''POL_SetupWindow_Init'''.

'''Example:'''
<pre class="playonlinux code">
POL_GetSetupImages "http://files.playonlinux.com/resources/setups/AC2/top.jpg" "http://files.playonlinux.com/resources/setups/AC2/left.jpg" "$TITLE"
</pre>

=== POL_SetupWindow_Init (4.0+) ===

'''Description:'''

Opens the installation wizard window.

'''Example:'''
<pre class="playonlinux code">
POL_SetupWindow_Init
</pre>

=== POL_SetupWindow_Close (4.0+) ===

'''Description:'''

Closes the installation wizard window.

'''Example:'''
<pre class="playonlinux code">
POL_SetupWindow_Close
</pre>

== PlayOnLinux graphical interface ==

{{Warning|All the functions below need the command POL_SetupWindow_Init to be executed beforehand.}}

=== POL_SetupWindow_presentation (4.0+) ===

'''Arguments:'''

# Software name (often $TITLE).
# Software publisher.
# Site of the publisher.
# Script author.
# Prefix name (usually $PREFIX).

'''Description:'''

Present the software.

'''Example:'''
<pre class="playonlinux code">
POL_SetupWindow_presentation "$TITLE" "Mozilla" "http://www.mozilla.com" "SuperPlumus and NSLW" "$PREFIX"
</pre>

=== POL_SetupWindow_free_presentation (4.0+) ===

'''Arguments:'''

# Software name (often $TITLE).
# Message.

'''Description:'''

Present the software with more freedom than POL_SetupWindow_presentation.

'''Example:'''
<pre class="playonlinux code">
POL_SetupWindow_free_presentation "$TITLE" "Welcome to Mozilla Firefox installation wizard."
</pre>

=== POL_SetupWindow_message (4.0+) ===

'''Arguments:'''

# Message.
# Title (often $TITLE).

'''Description:'''

Display a message.

'''Example:'''
<pre class="playonlinux code">
POL_SetupWindow_message "Hello world!" "$TITLE"
</pre>

=== check_one - POL_SetupWindow_missing (4.0-4.1.1) ===

'''Arguments for check_one:'''

# Program that must be present.
# 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:'''
<pre class="playonlinux code">
check_one "p7zip" "p7zip"
POL_SetupWindow_missing
</pre>

=== POL_SetupWindow_file (4.0+) ===

'''Arguments:'''

# Message.
# Title (often $TITLE).
# File to display.

'''Description:'''

Display the content of a file.

'''Example:'''
<pre class="playonlinux code">
POL_SetupWindow_file "Changelog" "$TITLE" "$POL_System_TmpDir/changelog.txt"
</pre>

=== POL_SetupWindow_licence (4.0+) ===

'''Arguments:'''

# Message.
# Title (often $TITLE).
# File to display.

'''Description:'''

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

Useful for displaying licenses.

'''Example:'''
<pre class="playonlinux code">
POL_SetupWindow_licence "Licence:" "$TITLE" "$POL_System_TmpDir/licence.txt"
</pre>

=== POL_SetupWindow_pulsebar - POL_SetupWindow_pulse - POL_SetupWindow_set_text (4.0+) ===

'''Arguments for POL_SetupWindow_pulsebar:'''

# Message.
# Title (often $TITLE).

'''Arguments for POL_SetupWindow_pulse:'''

# Percentage.

'''Arguments for POL_SetupWindow_set_text:'''

# 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:'''
<pre class="playonlinux code">
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"
</pre>

=== POL_SetupWindow_wait (4.0+) ===

'''Arguments:'''

# Message.
# Title (often $TITLE).

'''Description:'''

Display an indeterminate progress bar.

'''Example:'''
<pre class="playonlinux code">
POL_SetupWindow_wait "Please wait" "$TITLE"
</pre>

=== POL_SetupWindow_textbox (4.0+) ===

'''Arguments:'''

# Message.
# Title (often $TITLE).
# 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:'''
<pre class="playonlinux code">
POL_SetupWindow_textbox "Votre pseudo :" "$TITLE"
</pre>

=== POL_SetupWindow_textbox_multiline (4.0+) ===

'''Arguments:'''

# Message.
# Title (often $TITLE).
# 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:'''
<pre class="playonlinux code">
POL_SetupWindow_textbox_multiline "Enter a description for the program" "$TITLE"
</pre>

=== POL_SetupWindow_browse (4.0+) ===

'''Arguments:'''

# Message.
# Title (often $TITLE).
# 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:'''
<pre class="playonlinux code">
POL_SetupWindow_browse "Please select the program." "$TITLE"
</pre>

=== POL_SetupWindow_question (4.0+) ===

'''Arguments:'''

# Message.
# 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:'''
<pre class="playonlinux code">
POL_SetupWindow_question "Message" "Title"
</pre>

=== POL_SetupWindow_menu (4.0+) ===

'''Arguments:'''

# Message.
# Title (often $TITLE).
# Available choices.
# 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:'''
<pre class="playonlinux code">
POL_SetupWindow_menu "What's your favorite color?" "$TITLE" "Red~Green~Blue" "~"
</pre>

=== POL_SetupWindow_menu_num (4.0+) ===

'''Arguments:'''

# Message.
# Title (often $TITLE).
# Available choices.
# 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:'''
<pre class="playonlinux code">
POL_SetupWindow_menu_num "What's your favorite color?" "$TITLE" "Red~Green~Blue" "~"
</pre>

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

=== POL_SetupWindow_menu_list (4.0+) ===

'''Arguments:'''

# Message.
# Title (often $TITLE).
# Available choices.
# Separator character (often ~ or -).
# 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:'''
<pre class="playonlinux code">
POL_SetupWindow_menu_list "What's your favorite color?" "$TITLE" "Red~Green~Blue" "~"
</pre>

=== POL_SetupWindow_checkbox_list (4.0+) ===

'''Arguments:'''

# Message.
# Title (often $TITLE).
# Available choices.
# 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:'''
<pre class="playonlinux code">
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
</pre>

=== 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:'''
<pre class="playonlinux code">
POL_SetupWindow_cdrom
</pre>

=== POL_SetupWindow_check_cdrom (4.0+) ===

'''Arguments:'''

# 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:'''
<pre class="playonlinux code">
POL_SetupWindow_check_cdrom "Data/32_icon.ico"
</pre>

=== POL_SetupWindow_InstallMethod (4.0+) ===

'''Arguments:'''

# 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:'''
<pre class="playonlinux code">
POL_SetupWindow_InstallMethod "LOCAL,CD,STEAM"
</pre>

== POL_RequiredVersion (4.0.15+) ==

'''Arguments:'''

# 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, it itself only appeared in PlayOnLinux 4.0.15, and PlayOnLinux 4.0.14 is still the default in some distributions; 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_AdvisedVersion (4.0.15+) ==

'''Arguments:'''

# 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:'''

# Executable filename.
# Launcher name (often $TITLE).
# Optional name of the icon to download from PlayOnLinux website.
# Optional executable arguments.
# 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 [http://linux.die.net/man/7/glob 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 [http://standards.freedesktop.org/menu-spec/latest/apa.html main] and [http://standards.freedesktop.org/menu-spec/latest/apas02.html 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:'''
<pre class="playonlinux code">
POL_Shortcut "firefox.exe" "$TITLE"
</pre>

== POL_Shortcut_InsertBeforeWine (4.0+) ==

'''Arguments:'''

# Launcher name (often $TITLE).
# Command to add.

'''Description:'''

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

'''Example:'''
<pre class="playonlinux code">
POL_Shortcut_InsertBeforeWine "Jedi Knight II" "export __GL_ExtensionStringVersion=17700"
</pre>

== POL_Shortcut_QuietDebug (4.0.17+) ==
'''Arguments:'''

# 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:'''
# Launcher name (often $TITLE).
# 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:'''

# URL to open.

'''Description:'''

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

'''Example:'''
<pre class="playonlinux code">
POL_Browser "http://www.playonlinux.com"
</pre>

== POL_Download (4.0+) ==

'''Arguments:'''

# URL to download.
# (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:'''

# URL to download.
# Expected MD5 digest of the downloaded file
# (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:'''

# 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:'''
<pre class="playonlinux code">
POL_System_TmpCreate "$PREFIX"
</pre>

== POL_System_TmpDelete (4.0+) ==

'''Description:'''

Removes the script's temporary directory.

'''Example:'''
<pre class="playonlinux code">
POL_System_TmpDelete
</pre>

== POL_System_SetArch (4.0+) ==

'''Arguments:'''

# 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:'''
<pre class="playonlinux code">
POL_System_SetArch "auto"
</pre>

== POL_Call (4.0+) ==

'''Arguments:'''

# Function name.
# 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|Components and Functions]]).

'''Prerequisite:'''

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

'''Example:'''
<pre class="playonlinux code">
POL_Call POL_Install_vcrun6
</pre>

== Wine-related functions ==

=== POL_Wine_SelectPrefix (4.0+) ===

'''Arguments:'''

# 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:'''
<pre class="playonlinux code">
POL_Wine_SelectPrefix "$PREFIX"
</pre>

=== POL_Wine_PrefixExists (4.0+) ===

'''Arguments:'''

# 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:'''
<pre class="playonlinux code">
if [ "$(POL_Wine_PrefixExists "$PREFIX")" = "False" ]
then
# The préfixe doesn't exist
fi
</pre>

=== POL_Wine_PrefixCreate (4.0+) ===

'''Arguments:'''

# 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:'''
<pre class="playonlinux code">
POL_Wine_PrefixCreate "1.3.4"
</pre>

=== 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:'''

# 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:'''
<pre class="playonlinux code">
POL_SetupWindow_VMS "128"
</pre>

=== Set_OS (4.0+) ===

'''Arguments:'''

# Windows version to emulate.
# 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:'''
<pre class="playonlinux code">
Set_OS "win2k"
</pre>

=== Set_Managed (4.0+) ===

'''Arguments:'''

# 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:'''
<pre class="playonlinux code">
Set_Managed "Off"
</pre>

=== Set_SoundDriver (4.0+) ===

'''Arguments:'''

# alsa/oss/esd.

'''Description:'''

Set the audio driver Wine will use.

{{Info|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:'''
<pre class="playonlinux code">
Set_SoundDriver "alsa"
</pre>

=== POL_Wine_Direct3D (4.0+) ===

'''Arguments:'''

# Setting to create/modify.
# New setting value.

'''Description:'''

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

'''Allowed values:'''

See [http://wiki.winehq.org/UsefulRegistryKeys WineHQ's Wiki].

'''Prerequisite:'''

The commands POL_Wine_SelectPrefix and POL_Wine_PrefixCreate must have been used beforehand.

'''Example:'''
<pre class="playonlinux code">
POL_Wine_Direct3D "UseGLSL" "disabled"
</pre>

=== POL_Wine_X11Drv (4.0.14+) ===

'''Arguments:'''

# Setting to create/modify.
# New setting value.

'''Description:'''

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

'''Allowed values:'''

See [http://wiki.winehq.org/UsefulRegistryKeys WineHQ's Wiki].

'''Prerequisite:'''

The commands POL_Wine_SelectPrefix and POL_Wine_PrefixCreate must have been used beforehand.

'''Example:'''
<pre class="playonlinux code">
POL_Wine_X11Drv "DXGrab" "Y"
</pre>

=== POL_Wine_DirectSound (4.0+) ===

'''Arguments:'''

# Setting to create/modify.
# New setting value.

'''Description:'''

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

'''Allowed values:'''

See [http://wiki.winehq.org/UsefulRegistryKeys WineHQ's Wiki].

'''Prerequisite:'''

The commands POL_Wine_SelectPrefix and POL_Wine_PrefixCreate must have been used beforehand.

'''Example:'''
<pre class="playonlinux code">
POL_Wine_DirectSound "HardwareAcceleration" "Emulation"
</pre>

=== POL_Wine_DirectInput (4.0+) ===

'''Arguments:'''

# Setting to create/modify.
# New setting value.

'''Description:'''

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

'''Allowed values:'''

See [http://wiki.winehq.org/UsefulRegistryKeys WineHQ's Wiki].

'''Prerequisite:'''

The commands POL_Wine_SelectPrefix and POL_Wine_PrefixCreate must have been used beforehand.

'''Example:'''
<pre class="playonlinux code">
POL_Wine_DirectInput "MouseWarpOverride" "force"
</pre>

=== POL_Wine_GetRegValue (4.0+) ===

'''Arguments:'''

# 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:'''
<pre class="playonlinux code">
VALUE="$(POL_Wine_GetRegValue "MouseWarpOverride")"
</pre>

=== Set_Desktop (4.0+) ===

'''Arguments:'''

# On/Off.
# Virtual desktop width (if it is enabled).
# 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:'''
<pre class="playonlinux code">
Set_Desktop "On" "1024" "768"
</pre>

=== Set_WineWindowTitle (4.0+) ===

'''Arguments:'''

# 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:'''
<pre class="playonlinux code">
Set_WineWindowTitle "$TITLE"
</pre>

=== 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:'''
<pre class="playonlinux code">
POL_Wine_InstallFonts
</pre>

=== 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:'''
<pre class="playonlinux code">
POL_Wine_SetVideoDriver
</pre>

=== POL_Wine_OverrideDLL (4.0+) ===

'''Arguments:'''

# Mode of override.
# 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:'''
<pre class="playonlinux code">
POL_Wine_OverrideDLL "native" "msvcrt"
POL_Wine_OverrideDLL "" "msvcrt" # To disable the DLL
</pre>

=== POL_Wine_OverrideDLL_App (4.0+) ===

'''Arguments:'''

# Executable name.
# Mode of override.
# 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:'''
<pre class="playonlinux code">
POL_Wine_OverrideDLL_App "firefox.exe" "native" "msvcrt"
POL_Wine_OverrideDLL_App "firefox.exe" "" "msvcrt" # To disable the DLL
</pre>

=== POL_Wine_WaitBefore (4.0.15+) ===

'''Arguments:'''

# 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:'''

# 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:'''
<pre class="playonlinux code">
POL_Wine_WaitExit "$TITLE"
</pre>

=== 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:'''
<pre class="playonlinux code">
POL_Wine_reboot
</pre>

== Debugging commands ==

=== POL_Debug_Init (4.0+) ===

'''Description:'''

Start debugging system.

'''Example:'''
<pre class="playonlinux code">
POL_Debug_Init
</pre>

=== POL_Debug_Message (4.0+) ===

'''Arguments:'''

# 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:'''
<pre class="playonlinux code">
POL_Debug_Message "Modifying config.cfg file."
</pre>

=== POL_Debug_Warning (4.0+) ===

'''Arguments:'''

# 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:'''
<pre class="playonlinux code">
POL_Debug_Warning "File config.cfg did not exist, creating one."
</pre>

=== POL_Debug_Error (4.0+) ===

'''Arguments:'''

# 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:'''
<pre class="playonlinux code">
POL_Debug_Error "Error while modifying config.cfg file"
</pre>

=== POL_Debug_Fatal (4.0+) ===

'''Arguments:'''

# Message.

'''Description:'''

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

'''Prerequisite:'''

The command POL_Debug_Init must have been used beforehand.

'''Example:'''
<pre class="playonlinux code">
POL_Debug_Fatal "Error while modifying config.cfg file"
</pre>

'''Previous:''' [[Scripting - Chapter 10: Script Translation|Chapter 10: Script Translation]]

[[Category:Scripting]]

How to Contribute a Script

2015-07-22T19:20:45Z

Petch: Added static checks that can be done to verify scripts even before running them

== So, you have a script that you want to submit to PlayOnLinux? ==

There are a few things that should be followed, as far as our standards for icons, resources for install scripts, posting here for help or submitting to us for publication, and info that make this process more standardized.

== Static Checks ==
Even before running your script, you can test it for common (or not so common) mistakes using static analysers:

- http://www.shellcheck.net/ detects Bash scripting issues; It's not PlayOnLinux specific, but since PlayOnLinux scripts are a special case of Bash scripts, it can still be very useful;

- git clone the [https://github.com/PlayOnLinux/PlayOnLinux_Tools PlayOnLinux Tools] repository and run the script_checker.sh (from the PlayOnLinux_ScriptChecker subdirectory) on your script; That one will detect several PlayOnLinux mistakes, specially deprecated style issues.

== Testing, testing, testing ==

It is very important that you test your scripts thoroughly '''before''' trying to contribute them to the actual system. Although, please do feel free to post your script in the forum if you need help or want a review of it. Scripts that obviously have not been tested (because of spelling/syntax errors, non-existent Wine versions, etc..) will not be accepted and will be deleted from the contribution section, requesting that the author post in the forums for help correcting the script.

For instance, if your script has a WINEVERSION set to, say "4.2.3", it is apparent that the script was never tested to work correctly, because that Wine version does not exist. Things like this will result in deletion of the Script Contribution entry, and you will be requested to post in the forums to get the script set up correctly.

== Content of your posts in the forum (''Your Creations'' section) ==

Please use the following tips to help make the posts here more standardized:

* Make the title of your post something like:

<pre>
[Script] name of script
</pre>

* Post the following information in your post in this order:

# Description of the program (just a basic rundown of what it does)
# Anything you had to do or install OUTSIDE of Wine or PlayOnLinux to make it work
# Any extra notes about installation, or errors that it throws (if any)
# Contents of script

== Screenshot requirements ==

When submitting a screenshot, post them in your original post, reply to your own post with either the link to your screenshots, or just paste the screenshots into the post (we can download them and upload to our server.).

Also, do not submit screenshots with your background or desktop. Full-screen, program-only screenshots, unless you are posting the screenshots for troubleshooting of a related issue. What this means:

* Make sure that you are only taking a screenshot of the program related to this script.
* Window decorations are OK, as long as the program is the main feature of the picture.
* No lewd, pornographic, or otherwise controversial screenshots of ANYTHING (this will result in negative action without question.).
* Be sure to take screenshots of the game ACTUALLY running; no install shots.
* Though 1 screenshot works, we prefer 2. 3 is what we really like to see.
* Legible, fairly hi-def shots; no fuzzy text, not stretched/smashed, not distorted.

== Icons and install resources ==

So, there are 4 different icons and pictures that are desired for the script. They are listed as follows with their EXACT dimensions and file type requirements:

{{Warning|Do not forget to add the file extension to the name.}}

''' The icon that will be used for the installed program: '''
* Name: ''nameofprogram''-48x48
* File Type: PNG, JPEG
* Size: 48x48
''' The icon that will be used in the PlayOnLinux script list and the site: '''
* Name: ''nameofprogram''-22x22
* File Type: PNG, JPEG
* Size: 22x22
''' Sideways banner that is on the left side of the first window when script is ran: '''
* Name: left.jpg (or left.png)
* File Type: PNG, JPEG
* Size: 150x356 (W x H)
''' Top corner Icon for install script: '''
* Name: top.jpg (or top.png)
* File Type: PNG, JPEG
* Size: 64x64 (W x H)

== What to do after you have tested your script ==

After you have had your script on the forum, and its been verified to work, and the script is effective, clean, and portable, then submit in the following fashion:

# Go to [https://www.playonlinux.com PlayOnLinux] or [https://www.playonmac.com PlayOnMac]
# Click '''Supported Software'''
# Click '''Add a program'''
# Enter the name of the script you want to publish
# Fill out the form as completely as you can
# After your submit that, click '''Click here to see it'''
# When you return to your page, click the '''Contribute''' button
# Enter in a description, and below the description form, click '''I want to submit an improvement'''
# Copy/paste your script script in that field, and click '''Send'''

Now your script is awaiting approval. A staff member will look at the script and either:

* It will be approved, and will be then available in the POL/POM Install menu
* It will need improvements, which the staff member will inform you of. Then you just use the '''Contribute''' button to submit a new version of the script
* Your script will be deleted because it is empty, spam, a help request, or something else not related to that section

Scripting - Chapter 11: List of Functions

2015-07-04T18:06:36Z

Petch: /* POL_Shortcut (4.0+) */ After rereading the specs, it seems that category lists do not need to be terminated by ";" after all

== 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+) ===

'''Arguments:'''

# URL of top image.
# URL of left image.
# 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:'''
<pre class="playonlinux code">
POL_GetSetupImages "http://files.playonlinux.com/resources/setups/AC2/top.jpg" "http://files.playonlinux.com/resources/setups/AC2/left.jpg" "$TITLE"
</pre>

=== POL_SetupWindow_Init (4.0+) ===

'''Description:'''

Opens the installation wizard window.

'''Example:'''
<pre class="playonlinux code">
POL_SetupWindow_Init
</pre>

=== POL_SetupWindow_Close (4.0+) ===

'''Description:'''

Closes the installation wizard window.

'''Example:'''
<pre class="playonlinux code">
POL_SetupWindow_Close
</pre>

== PlayOnLinux graphical interface ==

{{Warning|All the functions below need the command POL_SetupWindow_Init to be executed beforehand.}}

=== POL_SetupWindow_presentation (4.0+) ===

'''Arguments:'''

# Software name (often $TITLE).
# Software publisher.
# Site of the publisher.
# Script author.
# Prefix name (usually $PREFIX).

'''Description:'''

Present the software.

'''Example:'''
<pre class="playonlinux code">
POL_SetupWindow_presentation "$TITLE" "Mozilla" "http://www.mozilla.com" "SuperPlumus and NSLW" "$PREFIX"
</pre>

=== POL_SetupWindow_free_presentation (4.0+) ===

'''Arguments:'''

# Software name (often $TITLE).
# Message.

'''Description:'''

Present the software with more freedom than POL_SetupWindow_presentation.

'''Example:'''
<pre class="playonlinux code">
POL_SetupWindow_free_presentation "$TITLE" "Welcome to Mozilla Firefox installation wizard."
</pre>

=== POL_SetupWindow_message (4.0+) ===

'''Arguments:'''

# Message.
# Title (often $TITLE).

'''Description:'''

Display a message.

'''Example:'''
<pre class="playonlinux code">
POL_SetupWindow_message "Hello world!" "$TITLE"
</pre>

=== check_one - POL_SetupWindow_missing (4.0-4.1.1) ===

'''Arguments for check_one:'''

# Program that must be present.
# 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:'''
<pre class="playonlinux code">
check_one "p7zip" "p7zip"
POL_SetupWindow_missing
</pre>

=== POL_SetupWindow_file (4.0+) ===

'''Arguments:'''

# Message.
# Title (often $TITLE).
# File to display.

'''Description:'''

Display the content of a file.

'''Example:'''
<pre class="playonlinux code">
POL_SetupWindow_file "Changelog" "$TITLE" "$POL_System_TmpDir/changelog.txt"
</pre>

=== POL_SetupWindow_licence (4.0+) ===

'''Arguments:'''

# Message.
# Title (often $TITLE).
# File to display.

'''Description:'''

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

Useful for displaying licenses.

'''Example:'''
<pre class="playonlinux code">
POL_SetupWindow_licence "Licence:" "$TITLE" "$POL_System_TmpDir/licence.txt"
</pre>

=== POL_SetupWindow_pulsebar - POL_SetupWindow_pulse - POL_SetupWindow_set_text (4.0+) ===

'''Arguments for POL_SetupWindow_pulsebar:'''

# Message.
# Title (often $TITLE).

'''Arguments for POL_SetupWindow_pulse:'''

# Percentage.

'''Arguments for POL_SetupWindow_set_text:'''

# 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:'''
<pre class="playonlinux code">
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"
</pre>

=== POL_SetupWindow_wait (4.0+) ===

'''Arguments:'''

# Message.
# Title (often $TITLE).

'''Description:'''

Display an indeterminate progress bar.

'''Example:'''
<pre class="playonlinux code">
POL_SetupWindow_wait "Please wait" "$TITLE"
</pre>

=== POL_SetupWindow_textbox (4.0+) ===

'''Arguments:'''

# Message.
# Title (often $TITLE).
# 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:'''
<pre class="playonlinux code">
POL_SetupWindow_textbox "Votre pseudo :" "$TITLE"
</pre>

=== POL_SetupWindow_textbox_multiline (4.0+) ===

'''Arguments:'''

# Message.
# Title (often $TITLE).
# 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:'''
<pre class="playonlinux code">
POL_SetupWindow_textbox_multiline "Enter a description for the program" "$TITLE"
</pre>

=== POL_SetupWindow_browse (4.0+) ===

'''Arguments:'''

# Message.
# Title (often $TITLE).
# 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:'''
<pre class="playonlinux code">
POL_SetupWindow_browse "Please select the program." "$TITLE"
</pre>

=== POL_SetupWindow_question (4.0+) ===

'''Arguments:'''

# Message.
# 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:'''
<pre class="playonlinux code">
POL_SetupWindow_question "Message" "Title"
</pre>

=== POL_SetupWindow_menu (4.0+) ===

'''Arguments:'''

# Message.
# Title (often $TITLE).
# Available choices.
# 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:'''
<pre class="playonlinux code">
POL_SetupWindow_menu "What's your favorite color?" "$TITLE" "Red~Green~Blue" "~"
</pre>

=== POL_SetupWindow_menu_num (4.0+) ===

'''Arguments:'''

# Message.
# Title (often $TITLE).
# Available choices.
# 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:'''
<pre class="playonlinux code">
POL_SetupWindow_menu_num "What's your favorite color?" "$TITLE" "Red~Green~Blue" "~"
</pre>

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

=== POL_SetupWindow_menu_list (4.0+) ===

'''Arguments:'''

# Message.
# Title (often $TITLE).
# Available choices.
# Separator character (often ~ or -).
# 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:'''
<pre class="playonlinux code">
POL_SetupWindow_menu_list "What's your favorite color?" "$TITLE" "Red~Green~Blue" "~"
</pre>

=== POL_SetupWindow_checkbox_list (4.0+) ===

'''Arguments:'''

# Message.
# Title (often $TITLE).
# Available choices.
# 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:'''
<pre class="playonlinux code">
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
</pre>

=== 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:'''
<pre class="playonlinux code">
POL_SetupWindow_cdrom
</pre>

=== POL_SetupWindow_check_cdrom (4.0+) ===

'''Arguments:'''

# 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:'''
<pre class="playonlinux code">
POL_SetupWindow_check_cdrom "Data/32_icon.ico"
</pre>

=== POL_SetupWindow_InstallMethod (4.0+) ===

'''Arguments:'''

# 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:'''
<pre class="playonlinux code">
POL_SetupWindow_InstallMethod "LOCAL,CD,STEAM"
</pre>

== POL_RequiredVersion (4.0.15+) ==

'''Arguments:'''

# 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, it itself only appeared in PlayOnLinux 4.0.15, and PlayOnLinux 4.0.14 is still the default in some distributions; 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_AdvisedVersion (4.0.15+) ==

'''Arguments:'''

# 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:'''

# Executable filename.
# Launcher name (often $TITLE).
# Optional name of the icon to download from PlayOnLinux website.
# Optional executable arguments.
# 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 [http://linux.die.net/man/7/glob 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 [http://standards.freedesktop.org/menu-spec/latest/apa.html main] and [http://standards.freedesktop.org/menu-spec/latest/apas02.html 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:'''
<pre class="playonlinux code">
POL_Shortcut "firefox.exe" "$TITLE"
</pre>

== POL_Shortcut_InsertBeforeWine (4.0+) ==

'''Arguments:'''

# Launcher name (often $TITLE).
# Command to add.

'''Description:'''

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

'''Example:'''
<pre class="playonlinux code">
POL_Shortcut_InsertBeforeWine "Jedi Knight II" "export __GL_ExtensionStringVersion=17700"
</pre>

== POL_Shortcut_QuietDebug (4.0.17+) ==
'''Arguments:'''

# 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:'''
# Launcher name (often $TITLE).
# 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:'''

# URL to open.

'''Description:'''

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

'''Example:'''
<pre class="playonlinux code">
POL_Browser "http://www.playonlinux.com"
</pre>

== POL_Download (4.0+) ==

'''Arguments:'''

# URL to download.
# (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:'''

# URL to download.
# Expected MD5 digest of the downloaded file
# (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:'''

# 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:'''
<pre class="playonlinux code">
POL_System_TmpCreate "$PREFIX"
</pre>

== POL_System_TmpDelete (4.0+) ==

'''Description:'''

Removes the script's temporary directory.

'''Example:'''
<pre class="playonlinux code">
POL_System_TmpDelete
</pre>

== POL_System_SetArch (4.0+) ==

'''Arguments:'''

# 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:'''
<pre class="playonlinux code">
POL_System_SetArch "auto"
</pre>

== POL_Call (4.0+) ==

'''Arguments:'''

# Function name.
# 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|Components and Functions]]).

'''Prerequisite:'''

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

'''Example:'''
<pre class="playonlinux code">
POL_Call POL_Install_vcrun6
</pre>

== Wine-related functions ==

=== POL_Wine_SelectPrefix (4.0+) ===

'''Arguments:'''

# 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:'''
<pre class="playonlinux code">
POL_Wine_SelectPrefix "$PREFIX"
</pre>

=== POL_Wine_PrefixExists (4.0+) ===

'''Arguments:'''

# 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:'''
<pre class="playonlinux code">
if [ "$(POL_Wine_PrefixExists "$PREFIX")" = "False" ]
then
# The préfixe doesn't exist
fi
</pre>

=== POL_Wine_PrefixCreate (4.0+) ===

'''Arguments:'''

# 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:'''
<pre class="playonlinux code">
POL_Wine_PrefixCreate "1.3.4"
</pre>

=== 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:'''

# 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:'''
<pre class="playonlinux code">
POL_SetupWindow_VMS "128"
</pre>

=== Set_OS (4.0+) ===

'''Arguments:'''

# Windows version to emulate.
# 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:'''
<pre class="playonlinux code">
Set_OS "win2k"
</pre>

=== Set_Managed (4.0+) ===

'''Arguments:'''

# 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:'''
<pre class="playonlinux code">
Set_Managed "Off"
</pre>

=== Set_SoundDriver (4.0+) ===

'''Arguments:'''

# alsa/oss/esd.

'''Description:'''

Set the audio driver Wine will use.

{{Info|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:'''
<pre class="playonlinux code">
Set_SoundDriver "alsa"
</pre>

=== POL_Wine_Direct3D (4.0+) ===

'''Arguments:'''

# Setting to create/modify.
# New setting value.

'''Description:'''

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

'''Allowed values:'''

See [http://wiki.winehq.org/UsefulRegistryKeys WineHQ's Wiki].

'''Prerequisite:'''

The commands POL_Wine_SelectPrefix and POL_Wine_PrefixCreate must have been used beforehand.

'''Example:'''
<pre class="playonlinux code">
POL_Wine_Direct3D "UseGLSL" "disabled"
</pre>

=== POL_Wine_X11Drv (4.0.14+) ===

'''Arguments:'''

# Setting to create/modify.
# New setting value.

'''Description:'''

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

'''Allowed values:'''

See [http://wiki.winehq.org/UsefulRegistryKeys WineHQ's Wiki].

'''Prerequisite:'''

The commands POL_Wine_SelectPrefix and POL_Wine_PrefixCreate must have been used beforehand.

'''Example:'''
<pre class="playonlinux code">
POL_Wine_X11Drv "DXGrab" "Y"
</pre>

=== POL_Wine_DirectSound (4.0+) ===

'''Arguments:'''

# Setting to create/modify.
# New setting value.

'''Description:'''

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

'''Allowed values:'''

See [http://wiki.winehq.org/UsefulRegistryKeys WineHQ's Wiki].

'''Prerequisite:'''

The commands POL_Wine_SelectPrefix and POL_Wine_PrefixCreate must have been used beforehand.

'''Example:'''
<pre class="playonlinux code">
POL_Wine_DirectSound "HardwareAcceleration" "Emulation"
</pre>

=== POL_Wine_DirectInput (4.0+) ===

'''Arguments:'''

# Setting to create/modify.
# New setting value.

'''Description:'''

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

'''Allowed values:'''

See [http://wiki.winehq.org/UsefulRegistryKeys WineHQ's Wiki].

'''Prerequisite:'''

The commands POL_Wine_SelectPrefix and POL_Wine_PrefixCreate must have been used beforehand.

'''Example:'''
<pre class="playonlinux code">
POL_Wine_DirectInput "MouseWarpOverride" "force"
</pre>

=== POL_Wine_GetRegValue (4.0+) ===

'''Arguments:'''

# 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:'''
<pre class="playonlinux code">
VALUE="$(POL_Wine_GetRegValue "MouseWarpOverride")"
</pre>

=== Set_Desktop (4.0+) ===

'''Arguments:'''

# On/Off.
# Virtual desktop width (if it is enabled).
# 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:'''
<pre class="playonlinux code">
Set_Desktop "On" "1024" "768"
</pre>

=== Set_WineWindowTitle (4.0+) ===

'''Arguments:'''

# 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:'''
<pre class="playonlinux code">
Set_WineWindowTitle "$TITLE"
</pre>

=== 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:'''
<pre class="playonlinux code">
POL_Wine_InstallFonts
</pre>

=== 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:'''
<pre class="playonlinux code">
POL_Wine_SetVideoDriver
</pre>

=== POL_Wine_OverrideDLL (4.0+) ===

'''Arguments:'''

# Mode of override.
# 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:'''
<pre class="playonlinux code">
POL_Wine_OverrideDLL "native" "msvcrt"
POL_Wine_OverrideDLL "" "msvcrt" # To disable the DLL
</pre>

=== POL_Wine_OverrideDLL_App (4.0+) ===

'''Arguments:'''

# Executable name.
# Mode of override.
# 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:'''
<pre class="playonlinux code">
POL_Wine_OverrideDLL_App "firefox.exe" "native" "msvcrt"
POL_Wine_OverrideDLL_App "firefox.exe" "" "msvcrt" # To disable the DLL
</pre>

=== POL_Wine_WaitBefore (4.0.15+) ===

'''Arguments:'''

# 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:'''

# 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:'''
<pre class="playonlinux code">
POL_Wine_WaitExit "$TITLE"
</pre>

=== 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:'''
<pre class="playonlinux code">
POL_Wine_reboot
</pre>

== Debugging commands ==

=== POL_Debug_Init (4.0+) ===

'''Description:'''

Start debugging system.

'''Example:'''
<pre class="playonlinux code">
POL_Debug_Init
</pre>

=== POL_Debug_Message (4.0+) ===

'''Arguments:'''

# 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:'''
<pre class="playonlinux code">
POL_Debug_Message "Modifying config.cfg file."
</pre>

=== POL_Debug_Warning (4.0+) ===

'''Arguments:'''

# 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:'''
<pre class="playonlinux code">
POL_Debug_Warning "File config.cfg did not exist, creating one."
</pre>

=== POL_Debug_Error (4.0+) ===

'''Arguments:'''

# 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:'''
<pre class="playonlinux code">
POL_Debug_Error "Error while modifying config.cfg file"
</pre>

=== POL_Debug_Fatal (4.0+) ===

'''Arguments:'''

# Message.

'''Description:'''

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

'''Prerequisite:'''

The command POL_Debug_Init must have been used beforehand.

'''Example:'''
<pre class="playonlinux code">
POL_Debug_Fatal "Error while modifying config.cfg file"
</pre>

'''Previous:''' [[Scripting - Chapter 10: Script Translation|Chapter 10: Script Translation]]

[[Category:Scripting]]

Scripting - Chapter 11: List of Functions

2015-06-18T13:13:44Z

Petch: /* POL_Shortcut (4.0+) */ Categories added in 4.2

== 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+) ===

'''Arguments:'''

# URL of top image.
# URL of left image.
# 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:'''
<pre class="playonlinux code">
POL_GetSetupImages "http://files.playonlinux.com/resources/setups/AC2/top.jpg" "http://files.playonlinux.com/resources/setups/AC2/left.jpg" "$TITLE"
</pre>

=== POL_SetupWindow_Init (4.0+) ===

'''Description:'''

Opens the installation wizard window.

'''Example:'''
<pre class="playonlinux code">
POL_SetupWindow_Init
</pre>

=== POL_SetupWindow_Close (4.0+) ===

'''Description:'''

Closes the installation wizard window.

'''Example:'''
<pre class="playonlinux code">
POL_SetupWindow_Close
</pre>

== PlayOnLinux graphical interface ==

{{Warning|All the functions below need the command POL_SetupWindow_Init to be executed beforehand.}}

=== POL_SetupWindow_presentation (4.0+) ===

'''Arguments:'''

# Software name (often $TITLE).
# Software publisher.
# Site of the publisher.
# Script author.
# Prefix name (usually $PREFIX).

'''Description:'''

Present the software.

'''Example:'''
<pre class="playonlinux code">
POL_SetupWindow_presentation "$TITLE" "Mozilla" "http://www.mozilla.com" "SuperPlumus and NSLW" "$PREFIX"
</pre>

=== POL_SetupWindow_free_presentation (4.0+) ===

'''Arguments:'''

# Software name (often $TITLE).
# Message.

'''Description:'''

Present the software with more freedom than POL_SetupWindow_presentation.

'''Example:'''
<pre class="playonlinux code">
POL_SetupWindow_free_presentation "$TITLE" "Welcome to Mozilla Firefox installation wizard."
</pre>

=== POL_SetupWindow_message (4.0+) ===

'''Arguments:'''

# Message.
# Title (often $TITLE).

'''Description:'''

Display a message.

'''Example:'''
<pre class="playonlinux code">
POL_SetupWindow_message "Hello world!" "$TITLE"
</pre>

=== check_one - POL_SetupWindow_missing (4.0-4.1.1) ===

'''Arguments for check_one:'''

# Program that must be present.
# 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:'''
<pre class="playonlinux code">
check_one "p7zip" "p7zip"
POL_SetupWindow_missing
</pre>

=== POL_SetupWindow_file (4.0+) ===

'''Arguments:'''

# Message.
# Title (often $TITLE).
# File to display.

'''Description:'''

Display the content of a file.

'''Example:'''
<pre class="playonlinux code">
POL_SetupWindow_file "Changelog" "$TITLE" "$POL_System_TmpDir/changelog.txt"
</pre>

=== POL_SetupWindow_licence (4.0+) ===

'''Arguments:'''

# Message.
# Title (often $TITLE).
# File to display.

'''Description:'''

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

Useful for displaying licenses.

'''Example:'''
<pre class="playonlinux code">
POL_SetupWindow_licence "Licence:" "$TITLE" "$POL_System_TmpDir/licence.txt"
</pre>

=== POL_SetupWindow_pulsebar - POL_SetupWindow_pulse - POL_SetupWindow_set_text (4.0+) ===

'''Arguments for POL_SetupWindow_pulsebar:'''

# Message.
# Title (often $TITLE).

'''Arguments for POL_SetupWindow_pulse:'''

# Percentage.

'''Arguments for POL_SetupWindow_set_text:'''

# 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:'''
<pre class="playonlinux code">
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"
</pre>

=== POL_SetupWindow_wait (4.0+) ===

'''Arguments:'''

# Message.
# Title (often $TITLE).

'''Description:'''

Display an indeterminate progress bar.

'''Example:'''
<pre class="playonlinux code">
POL_SetupWindow_wait "Please wait" "$TITLE"
</pre>

=== POL_SetupWindow_textbox (4.0+) ===

'''Arguments:'''

# Message.
# Title (often $TITLE).
# 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:'''
<pre class="playonlinux code">
POL_SetupWindow_textbox "Votre pseudo :" "$TITLE"
</pre>

=== POL_SetupWindow_textbox_multiline (4.0+) ===

'''Arguments:'''

# Message.
# Title (often $TITLE).
# 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:'''
<pre class="playonlinux code">
POL_SetupWindow_textbox_multiline "Enter a description for the program" "$TITLE"
</pre>

=== POL_SetupWindow_browse (4.0+) ===

'''Arguments:'''

# Message.
# Title (often $TITLE).
# 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:'''
<pre class="playonlinux code">
POL_SetupWindow_browse "Please select the program." "$TITLE"
</pre>

=== POL_SetupWindow_question (4.0+) ===

'''Arguments:'''

# Message.
# 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:'''
<pre class="playonlinux code">
POL_SetupWindow_question "Message" "Title"
</pre>

=== POL_SetupWindow_menu (4.0+) ===

'''Arguments:'''

# Message.
# Title (often $TITLE).
# Available choices.
# 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:'''
<pre class="playonlinux code">
POL_SetupWindow_menu "What's your favorite color?" "$TITLE" "Red~Green~Blue" "~"
</pre>

=== POL_SetupWindow_menu_num (4.0+) ===

'''Arguments:'''

# Message.
# Title (often $TITLE).
# Available choices.
# 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:'''
<pre class="playonlinux code">
POL_SetupWindow_menu_num "What's your favorite color?" "$TITLE" "Red~Green~Blue" "~"
</pre>

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

=== POL_SetupWindow_menu_list (4.0+) ===

'''Arguments:'''

# Message.
# Title (often $TITLE).
# Available choices.
# Separator character (often ~ or -).
# 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:'''
<pre class="playonlinux code">
POL_SetupWindow_menu_list "What's your favorite color?" "$TITLE" "Red~Green~Blue" "~"
</pre>

=== POL_SetupWindow_checkbox_list (4.0+) ===

'''Arguments:'''

# Message.
# Title (often $TITLE).
# Available choices.
# 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:'''
<pre class="playonlinux code">
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
</pre>

=== 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:'''
<pre class="playonlinux code">
POL_SetupWindow_cdrom
</pre>

=== POL_SetupWindow_check_cdrom (4.0+) ===

'''Arguments:'''

# 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:'''
<pre class="playonlinux code">
POL_SetupWindow_check_cdrom "Data/32_icon.ico"
</pre>

=== POL_SetupWindow_InstallMethod (4.0+) ===

'''Arguments:'''

# 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:'''
<pre class="playonlinux code">
POL_SetupWindow_InstallMethod "LOCAL,CD,STEAM"
</pre>

== POL_RequiredVersion (4.0.15+) ==

'''Arguments:'''

# 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, it itself only appeared in PlayOnLinux 4.0.15, and PlayOnLinux 4.0.14 is still the default in some distributions; 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_AdvisedVersion (4.0.15+) ==

'''Arguments:'''

# 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:'''

# Executable filename.
# Launcher name (often $TITLE).
# Optional name of the icon to download from PlayOnLinux website.
# Optional executable arguments.
# 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 [http://linux.die.net/man/7/glob 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 [http://standards.freedesktop.org/menu-spec/latest/apa.html main] and [http://standards.freedesktop.org/menu-spec/latest/apas02.html 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:'''
<pre class="playonlinux code">
POL_Shortcut "firefox.exe" "$TITLE"
</pre>

== POL_Shortcut_InsertBeforeWine (4.0+) ==

'''Arguments:'''

# Launcher name (often $TITLE).
# Command to add.

'''Description:'''

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

'''Example:'''
<pre class="playonlinux code">
POL_Shortcut_InsertBeforeWine "Jedi Knight II" "export __GL_ExtensionStringVersion=17700"
</pre>

== POL_Shortcut_QuietDebug (4.0.17+) ==
'''Arguments:'''

# 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:'''
# Launcher name (often $TITLE).
# 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:'''

# URL to open.

'''Description:'''

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

'''Example:'''
<pre class="playonlinux code">
POL_Browser "http://www.playonlinux.com"
</pre>

== POL_Download (4.0+) ==

'''Arguments:'''

# URL to download.
# (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:'''

# URL to download.
# Expected MD5 digest of the downloaded file
# (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:'''

# 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:'''
<pre class="playonlinux code">
POL_System_TmpCreate "$PREFIX"
</pre>

== POL_System_TmpDelete (4.0+) ==

'''Description:'''

Removes the script's temporary directory.

'''Example:'''
<pre class="playonlinux code">
POL_System_TmpDelete
</pre>

== POL_System_SetArch (4.0+) ==

'''Arguments:'''

# 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:'''
<pre class="playonlinux code">
POL_System_SetArch "auto"
</pre>

== POL_Call (4.0+) ==

'''Arguments:'''

# Function name.
# 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|Components and Functions]]).

'''Prerequisite:'''

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

'''Example:'''
<pre class="playonlinux code">
POL_Call POL_Install_vcrun6
</pre>

== Wine-related functions ==

=== POL_Wine_SelectPrefix (4.0+) ===

'''Arguments:'''

# 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:'''
<pre class="playonlinux code">
POL_Wine_SelectPrefix "$PREFIX"
</pre>

=== POL_Wine_PrefixExists (4.0+) ===

'''Arguments:'''

# 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:'''
<pre class="playonlinux code">
if [ "$(POL_Wine_PrefixExists "$PREFIX")" = "False" ]
then
# The préfixe doesn't exist
fi
</pre>

=== POL_Wine_PrefixCreate (4.0+) ===

'''Arguments:'''

# 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:'''
<pre class="playonlinux code">
POL_Wine_PrefixCreate "1.3.4"
</pre>

=== 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:'''

# 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:'''
<pre class="playonlinux code">
POL_SetupWindow_VMS "128"
</pre>

=== Set_OS (4.0+) ===

'''Arguments:'''

# Windows version to emulate.
# 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:'''
<pre class="playonlinux code">
Set_OS "win2k"
</pre>

=== Set_Managed (4.0+) ===

'''Arguments:'''

# 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:'''
<pre class="playonlinux code">
Set_Managed "Off"
</pre>

=== Set_SoundDriver (4.0+) ===

'''Arguments:'''

# alsa/oss/esd.

'''Description:'''

Set the audio driver Wine will use.

{{Info|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:'''
<pre class="playonlinux code">
Set_SoundDriver "alsa"
</pre>

=== POL_Wine_Direct3D (4.0+) ===

'''Arguments:'''

# Setting to create/modify.
# New setting value.

'''Description:'''

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

'''Allowed values:'''

See [http://wiki.winehq.org/UsefulRegistryKeys WineHQ's Wiki].

'''Prerequisite:'''

The commands POL_Wine_SelectPrefix and POL_Wine_PrefixCreate must have been used beforehand.

'''Example:'''
<pre class="playonlinux code">
POL_Wine_Direct3D "UseGLSL" "disabled"
</pre>

=== POL_Wine_X11Drv (4.0.14+) ===

'''Arguments:'''

# Setting to create/modify.
# New setting value.

'''Description:'''

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

'''Allowed values:'''

See [http://wiki.winehq.org/UsefulRegistryKeys WineHQ's Wiki].

'''Prerequisite:'''

The commands POL_Wine_SelectPrefix and POL_Wine_PrefixCreate must have been used beforehand.

'''Example:'''
<pre class="playonlinux code">
POL_Wine_X11Drv "DXGrab" "Y"
</pre>

=== POL_Wine_DirectSound (4.0+) ===

'''Arguments:'''

# Setting to create/modify.
# New setting value.

'''Description:'''

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

'''Allowed values:'''

See [http://wiki.winehq.org/UsefulRegistryKeys WineHQ's Wiki].

'''Prerequisite:'''

The commands POL_Wine_SelectPrefix and POL_Wine_PrefixCreate must have been used beforehand.

'''Example:'''
<pre class="playonlinux code">
POL_Wine_DirectSound "HardwareAcceleration" "Emulation"
</pre>

=== POL_Wine_DirectInput (4.0+) ===

'''Arguments:'''

# Setting to create/modify.
# New setting value.

'''Description:'''

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

'''Allowed values:'''

See [http://wiki.winehq.org/UsefulRegistryKeys WineHQ's Wiki].

'''Prerequisite:'''

The commands POL_Wine_SelectPrefix and POL_Wine_PrefixCreate must have been used beforehand.

'''Example:'''
<pre class="playonlinux code">
POL_Wine_DirectInput "MouseWarpOverride" "force"
</pre>

=== POL_Wine_GetRegValue (4.0+) ===

'''Arguments:'''

# 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:'''
<pre class="playonlinux code">
VALUE="$(POL_Wine_GetRegValue "MouseWarpOverride")"
</pre>

=== Set_Desktop (4.0+) ===

'''Arguments:'''

# On/Off.
# Virtual desktop width (if it is enabled).
# 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:'''
<pre class="playonlinux code">
Set_Desktop "On" "1024" "768"
</pre>

=== Set_WineWindowTitle (4.0+) ===

'''Arguments:'''

# 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:'''
<pre class="playonlinux code">
Set_WineWindowTitle "$TITLE"
</pre>

=== 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:'''
<pre class="playonlinux code">
POL_Wine_InstallFonts
</pre>

=== 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:'''
<pre class="playonlinux code">
POL_Wine_SetVideoDriver
</pre>

=== POL_Wine_OverrideDLL (4.0+) ===

'''Arguments:'''

# Mode of override.
# 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:'''
<pre class="playonlinux code">
POL_Wine_OverrideDLL "native" "msvcrt"
POL_Wine_OverrideDLL "" "msvcrt" # To disable the DLL
</pre>

=== POL_Wine_OverrideDLL_App (4.0+) ===

'''Arguments:'''

# Executable name.
# Mode of override.
# 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:'''
<pre class="playonlinux code">
POL_Wine_OverrideDLL_App "firefox.exe" "native" "msvcrt"
POL_Wine_OverrideDLL_App "firefox.exe" "" "msvcrt" # To disable the DLL
</pre>

=== POL_Wine_WaitBefore (4.0.15+) ===

'''Arguments:'''

# 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:'''

# 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:'''
<pre class="playonlinux code">
POL_Wine_WaitExit "$TITLE"
</pre>

=== 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:'''
<pre class="playonlinux code">
POL_Wine_reboot
</pre>

== Debugging commands ==

=== POL_Debug_Init (4.0+) ===

'''Description:'''

Start debugging system.

'''Example:'''
<pre class="playonlinux code">
POL_Debug_Init
</pre>

=== POL_Debug_Message (4.0+) ===

'''Arguments:'''

# 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:'''
<pre class="playonlinux code">
POL_Debug_Message "Modifying config.cfg file."
</pre>

=== POL_Debug_Warning (4.0+) ===

'''Arguments:'''

# 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:'''
<pre class="playonlinux code">
POL_Debug_Warning "File config.cfg did not exist, creating one."
</pre>

=== POL_Debug_Error (4.0+) ===

'''Arguments:'''

# 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:'''
<pre class="playonlinux code">
POL_Debug_Error "Error while modifying config.cfg file"
</pre>

=== POL_Debug_Fatal (4.0+) ===

'''Arguments:'''

# Message.

'''Description:'''

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

'''Prerequisite:'''

The command POL_Debug_Init must have been used beforehand.

'''Example:'''
<pre class="playonlinux code">
POL_Debug_Fatal "Error while modifying config.cfg file"
</pre>

'''Previous:''' [[Scripting - Chapter 10: Script Translation|Chapter 10: Script Translation]]

[[Category:Scripting]]

Main Page

2015-05-03T20:55:57Z

Petch: Moved DOSBox support to "Advanced PlayOnLinux" section, still unsure it's the best place

Welcome to the PlayOnLinux and PlayOnMac wiki. Here you will find tutorials regarding the use of PlayOnLinux or PlayOnMac, and explanations of their various features. You'll also find guides explaining how to create installation scripts, a description of the commands available, API documentation, advanced topics, and more.

For any additional questions that do not have an answer in this wiki, do not hesitate to go to the [https://www.playonlinux.com/en/forums.html forums].

== User Documentation ==
* [[Installing PlayOnLinux]]
* [[Installing PlayOnMac]]
* [[First Use|Guide for first use of the software]]
* [[The Configuration Window|The Configuration Window]]
* [[The PlayOnLinux Filesystem|The PlayOnLinux Filesystem]]
* [[The PlayOnMac Filesystem|The PlayOnMac Filesystem]]
* [[Managing Wine Versions|Managing Wine Versions]]
* [[Manual Installations|Manual Installations]]
* [[Components and Functions|Components and Functions]]
* [[FAQ|Frequently Asked Questions]]

== Troubleshooting ==
* [[Troubleshooting Common Problems|Troubleshooting Common Problems]]
* [[Graphics Card Drivers|Graphics Card Drivers]]
* [[How to Read Debug Logs|How to Read Debug Logs]]
* [[Common Linux Libraries That Wine Might Need|Common Linux Libraries That Wine Might Need]]

== The Forums, Bug Reports, and Script Contribution ==
* [[How to Post in the Forums|How to Post in the Forums]]
* [[How to Post a Bug Report|How to Post a Bug Report]]
* [[How to Contribute a Script|How to Contribute a Script]]
* [[How to Request a Patched Version of Wine|How to Request a Patched Version of Wine]]

== Writing a script ==
* [[Scripting - Chapter 1: Getting to know Bash|Chapter 1: Getting to know Bash]]
* [[Scripting - Chapter 2: Basic Functions|Chapter 2: Basic Functions]]
* [[Scripting - Chapter 3: Variables|Chapter 3: Variables]]
* [[Scripting - Chapter 4: Conditions|Chapter 4: Conditions]]
* [[Scripting - Chapter 5: Wine|Chapter 5: Wine]]
* [[Scripting - Chapter 6: The Filesystem|Chapter 6: The Filesystem]]
* [[Scripting - Chapter 7: Installation Media|Chapter 7: Installation Media]]
* [[Scripting - Chapter 8: My First Real Script|Chapter 8: My First Real Script]]
* [[Scripting - Chapter 9: Standardization|Chapter 9: Standardization]]
* [[Scripting - Chapter 10: Script Translation|Chapter 10: Script Translation]]
* [[Scripting - Chapter 11: List of Functions|Chapter 11: List of Functions]]
== Glossary ==
* [[POL & POM Terminology|POL & POM Terminology]]
* [[Wine; what is it?|Wine; what is it?]]

== Advanced PlayOnLinux ==
* [[How to move PlayOnLinux virtual drives to another disk|How to move PlayOnLinux virtual drives to another disk]]
* [[PlayOnLinux DOSBox support HOWTO]]
* [https://github.com/PlayOnLinux/POL-POM-4 PlayOnLinux/PlayOnMac source code]
* [https://github.com/PlayOnLinux/wine-patches Patch repository]
* [[Setting up WineASIO with PlayOnLinux|Setting up WineASIO with PlayOnLinux]]

== Advanced PlayOnMac ==

* [https://github.com/PlayOnLinux/POL-POM-4 PlayOnLinux/PlayOnMac source code]
* [https://github.com/PlayOnLinux/wine-patches Patch repository]

== Advanced Wine ==
''' Wine-Wiki '''

* [http://wine-wiki.org/ Wine-wiki. Somewhat outdated, but covers a LOT of advanced Wine topics]

''' WineHQ '''

* [https://www.winehq.org/devel/ Wine development links]
* [http://wiki.winehq.org/DeveloperFaq Wine developer FAQ]
* [https://www.winehq.org/docs/winedev-guide/index Wine developer's guide]
* [http://wiki.winehq.org/Developers-Hints Wine developer hints]
* [http://wiki.winehq.org/HackingTips Wine hacking tips]

== Advanced WineBuild ==
* [[Cross-compile Wine for OSX on Linux| How to cross-compile Wine for Mac OSX on Linux]]
* [https://github.com/PlayOnLinux/WineBuild POL's WineBuild source code]

PlayOnLinux DOSBox support HOWTO

2015-05-03T20:53:44Z

Petch: Some reformatting, one extra example

(Taken from https://www.playonlinux.com/en/topic-8747-Ultima_123_GOGcom_Edition.html, "Friday 11 May 2012 at 10:43" message)

To use the PlayOnLinux DOSBox support for a virtual drive,

* First, you must use some "Wine version" with DOSBox support for your virtual disk, latest is currently '''1.6.2-dos_support_0.6''';

* DOSBox will get default settings from this support. To override some, you'll need to create a '''$WINEPREFIX/playonlinux_dos.cfg''' file; Lines must have the format:

sectionname_settingname=value

For example

dosbox_memsize=16

See DOSBox 0.74 documentation for valid section and setting names.

''Remark 1'': this file will be sourced, so be sure to single quote values that could be interpreted by Bash; Example
cpu_cycles='max 95% limit 33000'
''Remark 2'': there's a new set of functions '''POL_Config_DosPrefixRead''' / '''POL_Config_DosPrefixWrite''' / '''POL_Config_DosPrefixDelete''' to manage those files, but they only exist since '''POL 4.0.18''', so if you use them you'll also need to add '''POL_RequiredVersion "4.0.18"''' just after POL_SetupWindow_Init.

* The C: drive will be mapped to the virtual disk root, and by default the support will try to map the same drives as the Wine environment. If you don't want the latter, just C: mapping, you can add the pseudo-setting

manual_mount=true

* If there's an '''autoexec.bat''' file at the root of your virtual disk, it will be interpreted at the beginning of each DOSBox session in this virtual disk. It's the recommended place to put mount and imgmount statements.

* That should be enough to create working shortcuts on '''exe''' files in this virtual disk; The support can tell apart MS-DOS from Windows executables and start DOSBox when necessary.

* You should also be able to create shortcuts on MS-DOS batch ('''bat''') files if they start with an '''@ECHO OFF''' line so they're recognized as such (by the "file" command actually). You'll also probably want an '''EXIT''' statement at the end of batch files so the DOSBox window closes itself after program exit (unless debug mode is enabled for the shortcut).

* If you have specific needs, like starting MS-DOS com files, or set shortcut-specific initializations, you can create extra batch files and make shortcut out of them.

That's mostly all there is to it. The fact that C: drive is always mapped to the root of the virtual disk sometimes requires some arrangements during installation, like moving some files around back into the root directory of the virtual disk. The Linux-to-DOSBox path translation ("shortizing") in the support is not perfect; Another reason for further arrangements are subdirectories with similar prefix side-by-side, you may also have to give them standard MS-DOS names (8+3 characters) to work around this problem.

PlayOnLinux DOSBox support HOWTO

2015-05-03T20:33:17Z

Petch: PlayOnLinux DOSBox support howto

(Taken from https://www.playonlinux.com/en/topic-8747-Ultima_123_GOGcom_Edition.html, "Friday 11 May 2012 at 10:43" message)

* First, you must use some "Wine version" with dos support for your virtual disk, latest is currently '''1.6.2-dos_support_0.6''';

* DOSBox will get default settings from this support. To override some, you'll need a '''$WINEPREFIX/playonlinux_dos.cfg''' file; Lines must have the format:

sectionname_settingname=value

For example

dosbox_memsize=16

See DOSBox 0.74 documentation for valid section and setting names.

''Remark 1'': this file will be sourced, so be sure to single quote values that could be interpreted by Bash;

''Remark 2'': there's a new set of functions POL_Config_DosPrefixRead / POL_Config_DosPrefixWrite / POL_Config_DosPrefixDelete to manage those files, but they only exist since '''POL 4.0.18''', so if you use them you'll also need to add '''POL_RequiredVersion "4.0.18"''' just after POL_SetupWindow_Init.

* The C: drive will be mapped to the virtual disk root, and by default the support will try to map the same drives as the Wine environment. If you don't want the latter, just C: mapping, you can add the pseudo-setting

manual_mount=true

* If there's an '''autoexec.bat''' file at the root of your virtual disk, it will be interpreted at the beginning of each DOSBox session in this virtual disk. It's the recommended place to put mount and imgmount statements.

* That should be enough to create working shortcuts on '''exe''' files in this virtual disk; The support can tell apart MS-DOS from Windows executables and start DOSBox when necessary.

* You should also be able to create shortcuts on MS-DOS batch ('''bat''') files if they start with an '''@ECHO OFF''' line so they're recognized as such (by the "file" command actually). You'll also probably want an '''EXIT''' statement at the end of batch files so the DOSBox window closes itself after program exit (unless debug mode is enabled for the shortcut).

* If you have specific needs, like starting MS-DOS com files, or set shortcut-specific initializations, you can create extra batch files and make shortcut out of them.

That's mostly all there is to it. The fact that C: drive is always mapped to the root of the virtual disk sometimes requires some arrangements during installation, like moving some files around back into the root directory of the virtual disk.
The Linux-to-DOSBox path translation ("shortizing") in the support is not perfect; Another reason for further arrangements are subdirectories with similar prefix side-by-side, you may also have to give them standard MS-DOS names (8+3 characters) to work around this problem.

Main Page

2015-05-03T20:19:53Z

Petch: /* Advanced PlayOnLinux */ Add (or try to add) DOSBox HOWTO link

Welcome to the PlayOnLinux and PlayOnMac wiki. Here you will find tutorials regarding the use of PlayOnLinux or PlayOnMac, and explanations of their various features. You'll also find guides explaining how to create installation scripts, a description of the commands available, API documentation, advanced topics, and more.

For any additional questions that do not have an answer in this wiki, do not hesitate to go to the [https://www.playonlinux.com/en/forums.html forums].

== User Documentation ==
* [[Installing PlayOnLinux]]
* [[Installing PlayOnMac]]
* [[First Use|Guide for first use of the software]]
* [[The Configuration Window|The Configuration Window]]
* [[The PlayOnLinux Filesystem|The PlayOnLinux Filesystem]]
* [[The PlayOnMac Filesystem|The PlayOnMac Filesystem]]
* [[Managing Wine Versions|Managing Wine Versions]]
* [[Manual Installations|Manual Installations]]
* [[Components and Functions|Components and Functions]]
* [[FAQ|Frequently Asked Questions]]

== Troubleshooting ==
* [[Troubleshooting Common Problems|Troubleshooting Common Problems]]
* [[Graphics Card Drivers|Graphics Card Drivers]]
* [[How to Read Debug Logs|How to Read Debug Logs]]
* [[Common Linux Libraries That Wine Might Need|Common Linux Libraries That Wine Might Need]]

== The Forums, Bug Reports, and Script Contribution ==
* [[How to Post in the Forums|How to Post in the Forums]]
* [[How to Post a Bug Report|How to Post a Bug Report]]
* [[How to Contribute a Script|How to Contribute a Script]]
* [[How to Request a Patched Version of Wine|How to Request a Patched Version of Wine]]

== Writing a script ==
* [[Scripting - Chapter 1: Getting to know Bash|Chapter 1: Getting to know Bash]]
* [[Scripting - Chapter 2: Basic Functions|Chapter 2: Basic Functions]]
* [[Scripting - Chapter 3: Variables|Chapter 3: Variables]]
* [[Scripting - Chapter 4: Conditions|Chapter 4: Conditions]]
* [[Scripting - Chapter 5: Wine|Chapter 5: Wine]]
* [[Scripting - Chapter 6: The Filesystem|Chapter 6: The Filesystem]]
* [[Scripting - Chapter 7: Installation Media|Chapter 7: Installation Media]]
* [[Scripting - Chapter 8: My First Real Script|Chapter 8: My First Real Script]]
* [[Scripting - Chapter 9: Standardization|Chapter 9: Standardization]]
* [[Scripting - Chapter 10: Script Translation|Chapter 10: Script Translation]]
* [[Scripting - Chapter 11: List of Functions|Chapter 11: List of Functions]]
[[PlayOnLinux DOSBox support HOWTO]]

== Glossary ==
* [[POL & POM Terminology|POL & POM Terminology]]
* [[Wine; what is it?|Wine; what is it?]]

== Advanced PlayOnLinux ==
* [[How to move PlayOnLinux virtual drives to another disk|How to move PlayOnLinux virtual drives to another disk]]
* [https://github.com/PlayOnLinux/POL-POM-4 PlayOnLinux/PlayOnMac source code]
* [https://github.com/PlayOnLinux/wine-patches Patch repository]
* [[Setting up WineASIO with PlayOnLinux|Setting up WineASIO with PlayOnLinux]]

== Advanced PlayOnMac ==

* [https://github.com/PlayOnLinux/POL-POM-4 PlayOnLinux/PlayOnMac source code]
* [https://github.com/PlayOnLinux/wine-patches Patch repository]

== Advanced Wine ==
''' Wine-Wiki '''

* [http://wine-wiki.org/ Wine-wiki. Somewhat outdated, but covers a LOT of advanced Wine topics]

''' WineHQ '''

* [https://www.winehq.org/devel/ Wine development links]
* [http://wiki.winehq.org/DeveloperFaq Wine developer FAQ]
* [https://www.winehq.org/docs/winedev-guide/index Wine developer's guide]
* [http://wiki.winehq.org/Developers-Hints Wine developer hints]
* [http://wiki.winehq.org/HackingTips Wine hacking tips]

== Advanced WineBuild ==
* [[Cross-compile Wine for OSX on Linux| How to cross-compile Wine for Mac OSX on Linux]]
* [https://github.com/PlayOnLinux/WineBuild POL's WineBuild source code]

Installing PlayOnLinux

2015-05-01T07:34:45Z

Petch: Move Mac specific instructions to PlayOnMac page

PlayOnLinux is available in the repositories of a lot of distributions, but with the exception of pacman, the versions found in these repositories are rarely the latest versions available. We genuinely encourage every use to use the latest version possible, as many things can change between releases.

You will find below the three methods that you are offered to install PlayOnLinux on your machine.

=== Distribution Repository ===

This method is probably the one that most users will use first. It has the advantage that it will provide generally a package approved by your distribution and thus generally better integrated with your OS.

Unfortunately, this method is not guaranteed to have the most updated version of the software. As for that, the updates on the repositories are not maintained by the PlayOnLinux team. It is because of this that distribution repository version are delayed by one or two revision. This may have the negative effect of not being able to properly use the tools that interact with the site (eg uploading of error reporting).

We urge you to follow instead the following method that guarantees you always use an updated software.

=== Following the guide on the site ===

You will find on the site a "Download" section. This section explains how to install PlayOnLinux on your machine while ensuring that you always use the software to its latest stable version.

Users using pacman will still have the latest version available. However, for other distributions, it is recommended to add the repo for PlayOnLinux in your repository list. To do this, just follow the information for your distribution.

For users' Debian wheezy '' and '' Ubuntu Precise (and higher), '' they'll need to install the i386 version of Wine. For this, we must enable support for i386 in your repository manager.

==== On Debian wheezy ====

To install wine:i386 Debian, you must first enable support for this architecture (with dpkg). You can then update the repository and install wine:i386

<pre class="code bash">
sudo dpkg --add-i386
sudo apt-get update
sudo apt-get install wine:i386
</pre>

==== On Ubuntu Precise (and higher) ====

To install wine:i386 on Ubuntu, you must first enable support for this architecture (with dpkg configuration file). You can then update the repository and install wine:i386

<pre class='code bash'>
sudo echo "foreign-i386 architecture"> /etc/dpkg/dpkg.cfg.d/multiarch
sudo apt-get update
sudo apt-get install wine:i386
</pre>

=== Using GIT Version ===

The git version can always have the updated program. It is only recommended for advanced users and programmers. It has the advantage of providing automatic update button, unlike other version of the program. To install it on your computer, you must install and configure git. Once this is done, you can download PlayOnLinux using the following command:

<pre class='code bash'>
git clone https://github.com/PlayOnLinux/POL-POM-4
</pre>

{{Info|This command will download the program to your current folder. Consider making use of 'cd' before running the command to get to where you want the files to be downloaded to. }}Unlike package installations, this method won't install PlayOnLinux system-wide; To run the development version you'll have to run the "playonlinux" script found in the root directory of the cloned repository.

=== Next? ===

Now that you have installed on your computer PlayOnLinux, I suggest you to read our [[First Use| guide for first use of the software]] who will explain the basics to know to install and uninstall Windows programs with PlayOnLinux.

Installing PlayOnMac

2015-05-01T07:34:02Z

Petch: /* Installation */ Move Mac specific instructions to PlayOnMac page ;)

PlayOnMac installs on your computer is extremely easy. All you have to do is follow these four small steps that are described in the following section.

=== Installation ===

# Go [http://www.playonmac.com/fr/download.html the download page PlayOnMac]
# Download the latest version of PlayOnMac
# Once download, install 'PlayOnMac_X.XXdmg' 'on your desktop (double click on the file)
# You will find inside an uninstall software (to remove PlayOnMac your computer) and the software. You simply drag / drop it in your '' Applications ''

=== Using GIT Version ===

The git version can always have the updated program. It is only recommended for advanced users and programmers. It has the advantage of providing automatic update button, unlike other version of the program. To install it on your computer, you must install and configure git. Once this is done, you can download PlayOnMac using the following command:

git clone https://github.com/PlayOnLinux/POL-POM-4

{{Info|This command will download the program to your current folder. Consider making use of 'cd' before running the command to get to where you want the files to be downloaded to. }}Unlike packaged installation, this method won't install PlayOnMac system-wide

{{Info|On Mac, the easier way to use the development version is to first deploy a stable version of PlayOnMac, then to replace /Applications/PlayOnMac.app/Contents/Resources/playonlinux folder with a clone of the git repository.}}

=== Next? ===
Now that you have installed on your computer PlayOnMac, I suggest you to read our [[First Use| guide for first use of the software]] who will explain the basics to know to install and uninstall Windows programs with PlayOnMac.

Scripting - Chapter 11: List of Functions

2015-04-14T01:20:23Z

Petch: /* POL_Shortcut_InsertBeforeWine (4.0+) */ Added POL_Shortcut_QuietDebug

== 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+) ===

'''Arguments:'''

# URL of top image.
# URL of left image.
# 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:'''
<pre class="playonlinux code">
POL_GetSetupImages "http://files.playonlinux.com/resources/setups/AC2/top.jpg" "http://files.playonlinux.com/resources/setups/AC2/left.jpg" "$TITLE"
</pre>

=== POL_SetupWindow_Init (4.0+) ===

'''Description:'''

Opens the installation wizard window.

'''Example:'''
<pre class="playonlinux code">
POL_SetupWindow_Init
</pre>

=== POL_SetupWindow_Close (4.0+) ===

'''Description:'''

Closes the installation wizard window.

'''Example:'''
<pre class="playonlinux code">
POL_SetupWindow_Close
</pre>

== PlayOnLinux graphical interface ==

{{Warning|All the functions below need the command POL_SetupWindow_Init to be executed beforehand.}}

=== POL_SetupWindow_presentation (4.0+) ===

'''Arguments:'''

# Software name (often $TITLE).
# Software publisher.
# Site of the publisher.
# Script author.
# Prefix name (usually $PREFIX).

'''Description:'''

Present the software.

'''Example:'''
<pre class="playonlinux code">
POL_SetupWindow_presentation "$TITLE" "Mozilla" "http://www.mozilla.com" "SuperPlumus and NSLW" "$PREFIX"
</pre>

=== POL_SetupWindow_free_presentation (4.0+) ===

'''Arguments:'''

# Software name (often $TITLE).
# Message.

'''Description:'''

Present the software with more freedom than POL_SetupWindow_presentation.

'''Example:'''
<pre class="playonlinux code">
POL_SetupWindow_free_presentation "$TITLE" "Welcome to Mozilla Firefox installation wizard."
</pre>

=== POL_SetupWindow_message (4.0+) ===

'''Arguments:'''

# Message.
# Title (often $TITLE).

'''Description:'''

Display a message.

'''Example:'''
<pre class="playonlinux code">
POL_SetupWindow_message "Hello world!" "$TITLE"
</pre>

=== check_one - POL_SetupWindow_missing (4.0-4.1.1) ===

'''Arguments for check_one:'''

# Program that must be present.
# 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:'''
<pre class="playonlinux code">
check_one "p7zip" "p7zip"
POL_SetupWindow_missing
</pre>

=== POL_SetupWindow_file (4.0+) ===

'''Arguments:'''

# Message.
# Title (often $TITLE).
# File to display.

'''Description:'''

Display the content of a file.

'''Example:'''
<pre class="playonlinux code">
POL_SetupWindow_file "Changelog" "$TITLE" "$POL_System_TmpDir/changelog.txt"
</pre>

=== POL_SetupWindow_licence (4.0+) ===

'''Arguments:'''

# Message.
# Title (often $TITLE).
# File to display.

'''Description:'''

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

Useful for displaying licenses.

'''Example:'''
<pre class="playonlinux code">
POL_SetupWindow_licence "Licence:" "$TITLE" "$POL_System_TmpDir/licence.txt"
</pre>

=== POL_SetupWindow_pulsebar - POL_SetupWindow_pulse - POL_SetupWindow_set_text (4.0+) ===

'''Arguments for POL_SetupWindow_pulsebar:'''

# Message.
# Title (often $TITLE).

'''Arguments for POL_SetupWindow_pulse:'''

# Percentage.

'''Arguments for POL_SetupWindow_set_text:'''

# 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:'''
<pre class="playonlinux code">
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"
</pre>

=== POL_SetupWindow_wait (4.0+) ===

'''Arguments:'''

# Message.
# Title (often $TITLE).

'''Description:'''

Display an indeterminate progress bar.

'''Example:'''
<pre class="playonlinux code">
POL_SetupWindow_wait "Please wait" "$TITLE"
</pre>

=== POL_SetupWindow_textbox (4.0+) ===

'''Arguments:'''

# Message.
# Title (often $TITLE).
# 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:'''
<pre class="playonlinux code">
POL_SetupWindow_textbox "Votre pseudo :" "$TITLE"
</pre>

=== POL_SetupWindow_textbox_multiline (4.0+) ===

'''Arguments:'''

# Message.
# Title (often $TITLE).
# 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:'''
<pre class="playonlinux code">
POL_SetupWindow_textbox_multiline "Enter a description for the program" "$TITLE"
</pre>

=== POL_SetupWindow_browse (4.0+) ===

'''Arguments:'''

# Message.
# Title (often $TITLE).
# 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:'''
<pre class="playonlinux code">
POL_SetupWindow_browse "Please select the program." "$TITLE"
</pre>

=== POL_SetupWindow_question (4.0+) ===

'''Arguments:'''

# Message.
# 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:'''
<pre class="playonlinux code">
POL_SetupWindow_question "Message" "Title"
</pre>

=== POL_SetupWindow_menu (4.0+) ===

'''Arguments:'''

# Message.
# Title (often $TITLE).
# Available choices.
# 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:'''
<pre class="playonlinux code">
POL_SetupWindow_menu "What's your favorite color?" "$TITLE" "Red~Green~Blue" "~"
</pre>

=== POL_SetupWindow_menu_num (4.0+) ===

'''Arguments:'''

# Message.
# Title (often $TITLE).
# Available choices.
# 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:'''
<pre class="playonlinux code">
POL_SetupWindow_menu_num "What's your favorite color?" "$TITLE" "Red~Green~Blue" "~"
</pre>

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

=== POL_SetupWindow_menu_list (4.0+) ===

'''Arguments:'''

# Message.
# Title (often $TITLE).
# Available choices.
# Separator character (often ~ or -).
# 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:'''
<pre class="playonlinux code">
POL_SetupWindow_menu_list "What's your favorite color?" "$TITLE" "Red~Green~Blue" "~"
</pre>

=== POL_SetupWindow_checkbox_list (4.0+) ===

'''Arguments:'''

# Message.
# Title (often $TITLE).
# Available choices.
# 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:'''
<pre class="playonlinux code">
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
</pre>

=== 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:'''
<pre class="playonlinux code">
POL_SetupWindow_cdrom
</pre>

=== POL_SetupWindow_check_cdrom (4.0+) ===

'''Arguments:'''

# 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:'''
<pre class="playonlinux code">
POL_SetupWindow_check_cdrom "Data/32_icon.ico"
</pre>

=== POL_SetupWindow_InstallMethod (4.0+) ===

'''Arguments:'''

# 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:'''
<pre class="playonlinux code">
POL_SetupWindow_InstallMethod "LOCAL,CD,STEAM"
</pre>

== POL_RequiredVersion (4.0.15+) ==

'''Arguments:'''

# 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, it itself only appeared in PlayOnLinux 4.0.15, and PlayOnLinux 4.0.14 is still the default in some distributions; 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_AdvisedVersion (4.0.15+) ==

'''Arguments:'''

# 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:'''

# Executable filename.
# Launcher name (often $TITLE).
# Optional name of the icon to download from PlayOnLinux website.
# Optional executable arguments.
# 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 [http://linux.die.net/man/7/glob 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 [http://standards.freedesktop.org/menu-spec/latest/apa.html main] and [http://standards.freedesktop.org/menu-spec/latest/apas02.html 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:'''
<pre class="playonlinux code">
POL_Shortcut "firefox.exe" "$TITLE"
</pre>

== POL_Shortcut_InsertBeforeWine (4.0+) ==

'''Arguments:'''

# Launcher name (often $TITLE).
# Command to add.

'''Description:'''

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

'''Example:'''
<pre class="playonlinux code">
POL_Shortcut_InsertBeforeWine "Jedi Knight II" "export __GL_ExtensionStringVersion=17700"
</pre>

== POL_Shortcut_QuietDebug (4.0.17+) ==
'''Arguments:'''

# 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:'''
# Launcher name (often $TITLE).
# 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:'''

# URL to open.

'''Description:'''

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

'''Example:'''
<pre class="playonlinux code">
POL_Browser "http://www.playonlinux.com"
</pre>

== POL_Download (4.0+) ==

'''Arguments:'''

# URL to download.
# (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:'''

# URL to download.
# Expected MD5 digest of the downloaded file
# (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:'''

# 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:'''
<pre class="playonlinux code">
POL_System_TmpCreate "$PREFIX"
</pre>

== POL_System_TmpDelete (4.0+) ==

'''Description:'''

Removes the script's temporary directory.

'''Example:'''
<pre class="playonlinux code">
POL_System_TmpDelete
</pre>

== POL_System_SetArch (4.0+) ==

'''Arguments:'''

# 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:'''
<pre class="playonlinux code">
POL_System_SetArch "auto"
</pre>

== POL_Call (4.0+) ==

'''Arguments:'''

# Function name.
# 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|Components and Functions]]).

'''Prerequisite:'''

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

'''Example:'''
<pre class="playonlinux code">
POL_Call POL_Install_vcrun6
</pre>

== Wine-related functions ==

=== POL_Wine_SelectPrefix (4.0+) ===

'''Arguments:'''

# 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:'''
<pre class="playonlinux code">
POL_Wine_SelectPrefix "$PREFIX"
</pre>

=== POL_Wine_PrefixExists (4.0+) ===

'''Arguments:'''

# 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:'''
<pre class="playonlinux code">
if [ "$(POL_Wine_PrefixExists "$PREFIX")" = "False" ]
then
# The préfixe doesn't exist
fi
</pre>

=== POL_Wine_PrefixCreate (4.0+) ===

'''Arguments:'''

# 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:'''
<pre class="playonlinux code">
POL_Wine_PrefixCreate "1.3.4"
</pre>

=== 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:'''

# 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:'''
<pre class="playonlinux code">
POL_SetupWindow_VMS "128"
</pre>

=== Set_OS (4.0+) ===

'''Arguments:'''

# Windows version to emulate.
# 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:'''
<pre class="playonlinux code">
Set_OS "win2k"
</pre>

=== Set_Managed (4.0+) ===

'''Arguments:'''

# 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:'''
<pre class="playonlinux code">
Set_Managed "Off"
</pre>

=== Set_SoundDriver (4.0+) ===

'''Arguments:'''

# alsa/oss/esd.

'''Description:'''

Set the audio driver Wine will use.

{{Info|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:'''
<pre class="playonlinux code">
Set_SoundDriver "alsa"
</pre>

=== POL_Wine_Direct3D (4.0+) ===

'''Arguments:'''

# Setting to create/modify.
# New setting value.

'''Description:'''

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

'''Allowed values:'''

See [http://wiki.winehq.org/UsefulRegistryKeys WineHQ's Wiki].

'''Prerequisite:'''

The commands POL_Wine_SelectPrefix and POL_Wine_PrefixCreate must have been used beforehand.

'''Example:'''
<pre class="playonlinux code">
POL_Wine_Direct3D "UseGLSL" "disabled"
</pre>

=== POL_Wine_X11Drv (4.0.14+) ===

'''Arguments:'''

# Setting to create/modify.
# New setting value.

'''Description:'''

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

'''Allowed values:'''

See [http://wiki.winehq.org/UsefulRegistryKeys WineHQ's Wiki].

'''Prerequisite:'''

The commands POL_Wine_SelectPrefix and POL_Wine_PrefixCreate must have been used beforehand.

'''Example:'''
<pre class="playonlinux code">
POL_Wine_X11Drv "DXGrab" "Y"
</pre>

=== POL_Wine_DirectSound (4.0+) ===

'''Arguments:'''

# Setting to create/modify.
# New setting value.

'''Description:'''

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

'''Allowed values:'''

See [http://wiki.winehq.org/UsefulRegistryKeys WineHQ's Wiki].

'''Prerequisite:'''

The commands POL_Wine_SelectPrefix and POL_Wine_PrefixCreate must have been used beforehand.

'''Example:'''
<pre class="playonlinux code">
POL_Wine_DirectSound "HardwareAcceleration" "Emulation"
</pre>

=== POL_Wine_DirectInput (4.0+) ===

'''Arguments:'''

# Setting to create/modify.
# New setting value.

'''Description:'''

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

'''Allowed values:'''

See [http://wiki.winehq.org/UsefulRegistryKeys WineHQ's Wiki].

'''Prerequisite:'''

The commands POL_Wine_SelectPrefix and POL_Wine_PrefixCreate must have been used beforehand.

'''Example:'''
<pre class="playonlinux code">
POL_Wine_DirectInput "MouseWarpOverride" "force"
</pre>

=== POL_Wine_GetRegValue (4.0+) ===

'''Arguments:'''

# 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:'''
<pre class="playonlinux code">
VALUE="$(POL_Wine_GetRegValue "MouseWarpOverride")"
</pre>

=== Set_Desktop (4.0+) ===

'''Arguments:'''

# On/Off.
# Virtual desktop width (if it is enabled).
# 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:'''
<pre class="playonlinux code">
Set_Desktop "On" "1024" "768"
</pre>

=== Set_WineWindowTitle (4.0+) ===

'''Arguments:'''

# 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:'''
<pre class="playonlinux code">
Set_WineWindowTitle "$TITLE"
</pre>

=== 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:'''
<pre class="playonlinux code">
POL_Wine_InstallFonts
</pre>

=== 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:'''
<pre class="playonlinux code">
POL_Wine_SetVideoDriver
</pre>

=== POL_Wine_OverrideDLL (4.0+) ===

'''Arguments:'''

# Mode of override.
# 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:'''
<pre class="playonlinux code">
POL_Wine_OverrideDLL "native" "msvcrt"
POL_Wine_OverrideDLL "" "msvcrt" # To disable the DLL
</pre>

=== POL_Wine_OverrideDLL_App (4.0+) ===

'''Arguments:'''

# Executable name.
# Mode of override.
# 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:'''
<pre class="playonlinux code">
POL_Wine_OverrideDLL_App "firefox.exe" "native" "msvcrt"
POL_Wine_OverrideDLL_App "firefox.exe" "" "msvcrt" # To disable the DLL
</pre>

=== POL_Wine_WaitBefore (4.0.15+) ===

'''Arguments:'''

# 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:'''

# 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:'''
<pre class="playonlinux code">
POL_Wine_WaitExit "$TITLE"
</pre>

=== 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:'''
<pre class="playonlinux code">
POL_Wine_reboot
</pre>

== Debugging commands ==

=== POL_Debug_Init (4.0+) ===

'''Description:'''

Start debugging system.

'''Example:'''
<pre class="playonlinux code">
POL_Debug_Init
</pre>

=== POL_Debug_Message (4.0+) ===

'''Arguments:'''

# 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:'''
<pre class="playonlinux code">
POL_Debug_Message "Modifying config.cfg file."
</pre>

=== POL_Debug_Warning (4.0+) ===

'''Arguments:'''

# 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:'''
<pre class="playonlinux code">
POL_Debug_Warning "File config.cfg did not exist, creating one."
</pre>

=== POL_Debug_Error (4.0+) ===

'''Arguments:'''

# 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:'''
<pre class="playonlinux code">
POL_Debug_Error "Error while modifying config.cfg file"
</pre>

=== POL_Debug_Fatal (4.0+) ===

'''Arguments:'''

# Message.

'''Description:'''

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

'''Prerequisite:'''

The command POL_Debug_Init must have been used beforehand.

'''Example:'''
<pre class="playonlinux code">
POL_Debug_Fatal "Error while modifying config.cfg file"
</pre>

'''Previous:''' [[Scripting - Chapter 10: Script Translation|Chapter 10: Script Translation]]

[[Category:Scripting]]

Scripting - Chapter 11: List of Functions

2015-04-12T20:41:17Z

Petch: /* POL_SetupWindow_VMS (4.0+) */ wording

== 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+) ===

'''Arguments:'''

# URL of top image.
# URL of left image.
# 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:'''
<pre class="playonlinux code">
POL_GetSetupImages "http://files.playonlinux.com/resources/setups/AC2/top.jpg" "http://files.playonlinux.com/resources/setups/AC2/left.jpg" "$TITLE"
</pre>

=== POL_SetupWindow_Init (4.0+) ===

'''Description:'''

Opens the installation wizard window.

'''Example:'''
<pre class="playonlinux code">
POL_SetupWindow_Init
</pre>

=== POL_SetupWindow_Close (4.0+) ===

'''Description:'''

Closes the installation wizard window.

'''Example:'''
<pre class="playonlinux code">
POL_SetupWindow_Close
</pre>

== PlayOnLinux graphical interface ==

{{Warning|All the functions below need the command POL_SetupWindow_Init to be executed beforehand.}}

=== POL_SetupWindow_presentation (4.0+) ===

'''Arguments:'''

# Software name (often $TITLE).
# Software publisher.
# Site of the publisher.
# Script author.
# Prefix name (usually $PREFIX).

'''Description:'''

Present the software.

'''Example:'''
<pre class="playonlinux code">
POL_SetupWindow_presentation "$TITLE" "Mozilla" "http://www.mozilla.com" "SuperPlumus and NSLW" "$PREFIX"
</pre>

=== POL_SetupWindow_free_presentation (4.0+) ===

'''Arguments:'''

# Software name (often $TITLE).
# Message.

'''Description:'''

Present the software with more freedom than POL_SetupWindow_presentation.

'''Example:'''
<pre class="playonlinux code">
POL_SetupWindow_free_presentation "$TITLE" "Welcome to Mozilla Firefox installation wizard."
</pre>

=== POL_SetupWindow_message (4.0+) ===

'''Arguments:'''

# Message.
# Title (often $TITLE).

'''Description:'''

Display a message.

'''Example:'''
<pre class="playonlinux code">
POL_SetupWindow_message "Hello world!" "$TITLE"
</pre>

=== check_one - POL_SetupWindow_missing (4.0-4.1.1) ===

'''Arguments for check_one:'''

# Program that must be present.
# 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:'''
<pre class="playonlinux code">
check_one "p7zip" "p7zip"
POL_SetupWindow_missing
</pre>

=== POL_SetupWindow_file (4.0+) ===

'''Arguments:'''

# Message.
# Title (often $TITLE).
# File to display.

'''Description:'''

Display the content of a file.

'''Example:'''
<pre class="playonlinux code">
POL_SetupWindow_file "Changelog" "$TITLE" "$POL_System_TmpDir/changelog.txt"
</pre>

=== POL_SetupWindow_licence (4.0+) ===

'''Arguments:'''

# Message.
# Title (often $TITLE).
# File to display.

'''Description:'''

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

Useful for displaying licenses.

'''Example:'''
<pre class="playonlinux code">
POL_SetupWindow_licence "Licence:" "$TITLE" "$POL_System_TmpDir/licence.txt"
</pre>

=== POL_SetupWindow_pulsebar - POL_SetupWindow_pulse - POL_SetupWindow_set_text (4.0+) ===

'''Arguments for POL_SetupWindow_pulsebar:'''

# Message.
# Title (often $TITLE).

'''Arguments for POL_SetupWindow_pulse:'''

# Percentage.

'''Arguments for POL_SetupWindow_set_text:'''

# 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:'''
<pre class="playonlinux code">
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"
</pre>

=== POL_SetupWindow_wait (4.0+) ===

'''Arguments:'''

# Message.
# Title (often $TITLE).

'''Description:'''

Display an indeterminate progress bar.

'''Example:'''
<pre class="playonlinux code">
POL_SetupWindow_wait "Please wait" "$TITLE"
</pre>

=== POL_SetupWindow_textbox (4.0+) ===

'''Arguments:'''

# Message.
# Title (often $TITLE).
# 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:'''
<pre class="playonlinux code">
POL_SetupWindow_textbox "Votre pseudo :" "$TITLE"
</pre>

=== POL_SetupWindow_textbox_multiline (4.0+) ===

'''Arguments:'''

# Message.
# Title (often $TITLE).
# 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:'''
<pre class="playonlinux code">
POL_SetupWindow_textbox_multiline "Enter a description for the program" "$TITLE"
</pre>

=== POL_SetupWindow_browse (4.0+) ===

'''Arguments:'''

# Message.
# Title (often $TITLE).
# 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:'''
<pre class="playonlinux code">
POL_SetupWindow_browse "Please select the program." "$TITLE"
</pre>

=== POL_SetupWindow_question (4.0+) ===

'''Arguments:'''

# Message.
# 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:'''
<pre class="playonlinux code">
POL_SetupWindow_question "Message" "Title"
</pre>

=== POL_SetupWindow_menu (4.0+) ===

'''Arguments:'''

# Message.
# Title (often $TITLE).
# Available choices.
# 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:'''
<pre class="playonlinux code">
POL_SetupWindow_menu "What's your favorite color?" "$TITLE" "Red~Green~Blue" "~"
</pre>

=== POL_SetupWindow_menu_num (4.0+) ===

'''Arguments:'''

# Message.
# Title (often $TITLE).
# Available choices.
# 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:'''
<pre class="playonlinux code">
POL_SetupWindow_menu_num "What's your favorite color?" "$TITLE" "Red~Green~Blue" "~"
</pre>

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

=== POL_SetupWindow_menu_list (4.0+) ===

'''Arguments:'''

# Message.
# Title (often $TITLE).
# Available choices.
# Separator character (often ~ or -).
# 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:'''
<pre class="playonlinux code">
POL_SetupWindow_menu_list "What's your favorite color?" "$TITLE" "Red~Green~Blue" "~"
</pre>

=== POL_SetupWindow_checkbox_list (4.0+) ===

'''Arguments:'''

# Message.
# Title (often $TITLE).
# Available choices.
# 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:'''
<pre class="playonlinux code">
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
</pre>

=== 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:'''
<pre class="playonlinux code">
POL_SetupWindow_cdrom
</pre>

=== POL_SetupWindow_check_cdrom (4.0+) ===

'''Arguments:'''

# 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:'''
<pre class="playonlinux code">
POL_SetupWindow_check_cdrom "Data/32_icon.ico"
</pre>

=== POL_SetupWindow_InstallMethod (4.0+) ===

'''Arguments:'''

# 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:'''
<pre class="playonlinux code">
POL_SetupWindow_InstallMethod "LOCAL,CD,STEAM"
</pre>

== POL_RequiredVersion (4.0.15+) ==

'''Arguments:'''

# 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, it itself only appeared in PlayOnLinux 4.0.15, and PlayOnLinux 4.0.14 is still the default in some distributions; 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_AdvisedVersion (4.0.15+) ==

'''Arguments:'''

# 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:'''

# Executable filename.
# Launcher name (often $TITLE).
# Optional name of the icon to download from PlayOnLinux website.
# Optional executable arguments.
# 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 [http://linux.die.net/man/7/glob 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 [http://standards.freedesktop.org/menu-spec/latest/apa.html main] and [http://standards.freedesktop.org/menu-spec/latest/apas02.html 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:'''
<pre class="playonlinux code">
POL_Shortcut "firefox.exe" "$TITLE"
</pre>

== POL_Shortcut_InsertBeforeWine (4.0+) ==

'''Arguments:'''

# Launcher name (often $TITLE).
# Command to add.

'''Description:'''

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

'''Example:'''
<pre class="playonlinux code">
POL_Shortcut_InsertBeforeWine "Jedi Knight II" "export __GL_ExtensionStringVersion=17700"
</pre>

== POL_Shortcut_Document (4.0.15+) ==
'''Arguments:'''
# Launcher name (often $TITLE).
# 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:'''

# URL to open.

'''Description:'''

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

'''Example:'''
<pre class="playonlinux code">
POL_Browser "http://www.playonlinux.com"
</pre>

== POL_Download (4.0+) ==

'''Arguments:'''

# URL to download.
# (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:'''

# URL to download.
# Expected MD5 digest of the downloaded file
# (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:'''

# 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:'''
<pre class="playonlinux code">
POL_System_TmpCreate "$PREFIX"
</pre>

== POL_System_TmpDelete (4.0+) ==

'''Description:'''

Removes the script's temporary directory.

'''Example:'''
<pre class="playonlinux code">
POL_System_TmpDelete
</pre>

== POL_System_SetArch (4.0+) ==

'''Arguments:'''

# 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:'''
<pre class="playonlinux code">
POL_System_SetArch "auto"
</pre>

== POL_Call (4.0+) ==

'''Arguments:'''

# Function name.
# 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|Components and Functions]]).

'''Prerequisite:'''

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

'''Example:'''
<pre class="playonlinux code">
POL_Call POL_Install_vcrun6
</pre>

== Wine-related functions ==

=== POL_Wine_SelectPrefix (4.0+) ===

'''Arguments:'''

# 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:'''
<pre class="playonlinux code">
POL_Wine_SelectPrefix "$PREFIX"
</pre>

=== POL_Wine_PrefixExists (4.0+) ===

'''Arguments:'''

# 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:'''
<pre class="playonlinux code">
if [ "$(POL_Wine_PrefixExists "$PREFIX")" = "False" ]
then
# The préfixe doesn't exist
fi
</pre>

=== POL_Wine_PrefixCreate (4.0+) ===

'''Arguments:'''

# 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:'''
<pre class="playonlinux code">
POL_Wine_PrefixCreate "1.3.4"
</pre>

=== 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:'''

# 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:'''
<pre class="playonlinux code">
POL_SetupWindow_VMS "128"
</pre>

=== Set_OS (4.0+) ===

'''Arguments:'''

# Windows version to emulate.
# 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:'''
<pre class="playonlinux code">
Set_OS "win2k"
</pre>

=== Set_Managed (4.0+) ===

'''Arguments:'''

# 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:'''
<pre class="playonlinux code">
Set_Managed "Off"
</pre>

=== Set_SoundDriver (4.0+) ===

'''Arguments:'''

# alsa/oss/esd.

'''Description:'''

Set the audio driver Wine will use.

{{Info|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:'''
<pre class="playonlinux code">
Set_SoundDriver "alsa"
</pre>

=== POL_Wine_Direct3D (4.0+) ===

'''Arguments:'''

# Setting to create/modify.
# New setting value.

'''Description:'''

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

'''Allowed values:'''

See [http://wiki.winehq.org/UsefulRegistryKeys WineHQ's Wiki].

'''Prerequisite:'''

The commands POL_Wine_SelectPrefix and POL_Wine_PrefixCreate must have been used beforehand.

'''Example:'''
<pre class="playonlinux code">
POL_Wine_Direct3D "UseGLSL" "disabled"
</pre>

=== POL_Wine_X11Drv (4.0.14+) ===

'''Arguments:'''

# Setting to create/modify.
# New setting value.

'''Description:'''

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

'''Allowed values:'''

See [http://wiki.winehq.org/UsefulRegistryKeys WineHQ's Wiki].

'''Prerequisite:'''

The commands POL_Wine_SelectPrefix and POL_Wine_PrefixCreate must have been used beforehand.

'''Example:'''
<pre class="playonlinux code">
POL_Wine_X11Drv "DXGrab" "Y"
</pre>

=== POL_Wine_DirectSound (4.0+) ===

'''Arguments:'''

# Setting to create/modify.
# New setting value.

'''Description:'''

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

'''Allowed values:'''

See [http://wiki.winehq.org/UsefulRegistryKeys WineHQ's Wiki].

'''Prerequisite:'''

The commands POL_Wine_SelectPrefix and POL_Wine_PrefixCreate must have been used beforehand.

'''Example:'''
<pre class="playonlinux code">
POL_Wine_DirectSound "HardwareAcceleration" "Emulation"
</pre>

=== POL_Wine_DirectInput (4.0+) ===

'''Arguments:'''

# Setting to create/modify.
# New setting value.

'''Description:'''

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

'''Allowed values:'''

See [http://wiki.winehq.org/UsefulRegistryKeys WineHQ's Wiki].

'''Prerequisite:'''

The commands POL_Wine_SelectPrefix and POL_Wine_PrefixCreate must have been used beforehand.

'''Example:'''
<pre class="playonlinux code">
POL_Wine_DirectInput "MouseWarpOverride" "force"
</pre>

=== POL_Wine_GetRegValue (4.0+) ===

'''Arguments:'''

# 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:'''
<pre class="playonlinux code">
VALUE="$(POL_Wine_GetRegValue "MouseWarpOverride")"
</pre>

=== Set_Desktop (4.0+) ===

'''Arguments:'''

# On/Off.
# Virtual desktop width (if it is enabled).
# 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:'''
<pre class="playonlinux code">
Set_Desktop "On" "1024" "768"
</pre>

=== Set_WineWindowTitle (4.0+) ===

'''Arguments:'''

# 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:'''
<pre class="playonlinux code">
Set_WineWindowTitle "$TITLE"
</pre>

=== 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:'''
<pre class="playonlinux code">
POL_Wine_InstallFonts
</pre>

=== 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:'''
<pre class="playonlinux code">
POL_Wine_SetVideoDriver
</pre>

=== POL_Wine_OverrideDLL (4.0+) ===

'''Arguments:'''

# Mode of override.
# 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:'''
<pre class="playonlinux code">
POL_Wine_OverrideDLL "native" "msvcrt"
POL_Wine_OverrideDLL "" "msvcrt" # To disable the DLL
</pre>

=== POL_Wine_OverrideDLL_App (4.0+) ===

'''Arguments:'''

# Executable name.
# Mode of override.
# 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:'''
<pre class="playonlinux code">
POL_Wine_OverrideDLL_App "firefox.exe" "native" "msvcrt"
POL_Wine_OverrideDLL_App "firefox.exe" "" "msvcrt" # To disable the DLL
</pre>

=== POL_Wine_WaitBefore (4.0.15+) ===

'''Arguments:'''

# 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:'''

# 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:'''
<pre class="playonlinux code">
POL_Wine_WaitExit "$TITLE"
</pre>

=== 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:'''
<pre class="playonlinux code">
POL_Wine_reboot
</pre>

== Debugging commands ==

=== POL_Debug_Init (4.0+) ===

'''Description:'''

Start debugging system.

'''Example:'''
<pre class="playonlinux code">
POL_Debug_Init
</pre>

=== POL_Debug_Message (4.0+) ===

'''Arguments:'''

# 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:'''
<pre class="playonlinux code">
POL_Debug_Message "Modifying config.cfg file."
</pre>

=== POL_Debug_Warning (4.0+) ===

'''Arguments:'''

# 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:'''
<pre class="playonlinux code">
POL_Debug_Warning "File config.cfg did not exist, creating one."
</pre>

=== POL_Debug_Error (4.0+) ===

'''Arguments:'''

# 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:'''
<pre class="playonlinux code">
POL_Debug_Error "Error while modifying config.cfg file"
</pre>

=== POL_Debug_Fatal (4.0+) ===

'''Arguments:'''

# Message.

'''Description:'''

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

'''Prerequisite:'''

The command POL_Debug_Init must have been used beforehand.

'''Example:'''
<pre class="playonlinux code">
POL_Debug_Fatal "Error while modifying config.cfg file"
</pre>

'''Previous:''' [[Scripting - Chapter 10: Script Translation|Chapter 10: Script Translation]]

[[Category:Scripting]]

Scripting - Chapter 11: List of Functions

2015-04-12T20:37:30Z

Petch: /* POL_SetupWindow_VMS (4.0+) */ Better describe this statement behavior

== 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+) ===

'''Arguments:'''

# URL of top image.
# URL of left image.
# 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:'''
<pre class="playonlinux code">
POL_GetSetupImages "http://files.playonlinux.com/resources/setups/AC2/top.jpg" "http://files.playonlinux.com/resources/setups/AC2/left.jpg" "$TITLE"
</pre>

=== POL_SetupWindow_Init (4.0+) ===

'''Description:'''

Opens the installation wizard window.

'''Example:'''
<pre class="playonlinux code">
POL_SetupWindow_Init
</pre>

=== POL_SetupWindow_Close (4.0+) ===

'''Description:'''

Closes the installation wizard window.

'''Example:'''
<pre class="playonlinux code">
POL_SetupWindow_Close
</pre>

== PlayOnLinux graphical interface ==

{{Warning|All the functions below need the command POL_SetupWindow_Init to be executed beforehand.}}

=== POL_SetupWindow_presentation (4.0+) ===

'''Arguments:'''

# Software name (often $TITLE).
# Software publisher.
# Site of the publisher.
# Script author.
# Prefix name (usually $PREFIX).

'''Description:'''

Present the software.

'''Example:'''
<pre class="playonlinux code">
POL_SetupWindow_presentation "$TITLE" "Mozilla" "http://www.mozilla.com" "SuperPlumus and NSLW" "$PREFIX"
</pre>

=== POL_SetupWindow_free_presentation (4.0+) ===

'''Arguments:'''

# Software name (often $TITLE).
# Message.

'''Description:'''

Present the software with more freedom than POL_SetupWindow_presentation.

'''Example:'''
<pre class="playonlinux code">
POL_SetupWindow_free_presentation "$TITLE" "Welcome to Mozilla Firefox installation wizard."
</pre>

=== POL_SetupWindow_message (4.0+) ===

'''Arguments:'''

# Message.
# Title (often $TITLE).

'''Description:'''

Display a message.

'''Example:'''
<pre class="playonlinux code">
POL_SetupWindow_message "Hello world!" "$TITLE"
</pre>

=== check_one - POL_SetupWindow_missing (4.0-4.1.1) ===

'''Arguments for check_one:'''

# Program that must be present.
# 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:'''
<pre class="playonlinux code">
check_one "p7zip" "p7zip"
POL_SetupWindow_missing
</pre>

=== POL_SetupWindow_file (4.0+) ===

'''Arguments:'''

# Message.
# Title (often $TITLE).
# File to display.

'''Description:'''

Display the content of a file.

'''Example:'''
<pre class="playonlinux code">
POL_SetupWindow_file "Changelog" "$TITLE" "$POL_System_TmpDir/changelog.txt"
</pre>

=== POL_SetupWindow_licence (4.0+) ===

'''Arguments:'''

# Message.
# Title (often $TITLE).
# File to display.

'''Description:'''

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

Useful for displaying licenses.

'''Example:'''
<pre class="playonlinux code">
POL_SetupWindow_licence "Licence:" "$TITLE" "$POL_System_TmpDir/licence.txt"
</pre>

=== POL_SetupWindow_pulsebar - POL_SetupWindow_pulse - POL_SetupWindow_set_text (4.0+) ===

'''Arguments for POL_SetupWindow_pulsebar:'''

# Message.
# Title (often $TITLE).

'''Arguments for POL_SetupWindow_pulse:'''

# Percentage.

'''Arguments for POL_SetupWindow_set_text:'''

# 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:'''
<pre class="playonlinux code">
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"
</pre>

=== POL_SetupWindow_wait (4.0+) ===

'''Arguments:'''

# Message.
# Title (often $TITLE).

'''Description:'''

Display an indeterminate progress bar.

'''Example:'''
<pre class="playonlinux code">
POL_SetupWindow_wait "Please wait" "$TITLE"
</pre>

=== POL_SetupWindow_textbox (4.0+) ===

'''Arguments:'''

# Message.
# Title (often $TITLE).
# 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:'''
<pre class="playonlinux code">
POL_SetupWindow_textbox "Votre pseudo :" "$TITLE"
</pre>

=== POL_SetupWindow_textbox_multiline (4.0+) ===

'''Arguments:'''

# Message.
# Title (often $TITLE).
# 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:'''
<pre class="playonlinux code">
POL_SetupWindow_textbox_multiline "Enter a description for the program" "$TITLE"
</pre>

=== POL_SetupWindow_browse (4.0+) ===

'''Arguments:'''

# Message.
# Title (often $TITLE).
# 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:'''
<pre class="playonlinux code">
POL_SetupWindow_browse "Please select the program." "$TITLE"
</pre>

=== POL_SetupWindow_question (4.0+) ===

'''Arguments:'''

# Message.
# 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:'''
<pre class="playonlinux code">
POL_SetupWindow_question "Message" "Title"
</pre>

=== POL_SetupWindow_menu (4.0+) ===

'''Arguments:'''

# Message.
# Title (often $TITLE).
# Available choices.
# 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:'''
<pre class="playonlinux code">
POL_SetupWindow_menu "What's your favorite color?" "$TITLE" "Red~Green~Blue" "~"
</pre>

=== POL_SetupWindow_menu_num (4.0+) ===

'''Arguments:'''

# Message.
# Title (often $TITLE).
# Available choices.
# 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:'''
<pre class="playonlinux code">
POL_SetupWindow_menu_num "What's your favorite color?" "$TITLE" "Red~Green~Blue" "~"
</pre>

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

=== POL_SetupWindow_menu_list (4.0+) ===

'''Arguments:'''

# Message.
# Title (often $TITLE).
# Available choices.
# Separator character (often ~ or -).
# 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:'''
<pre class="playonlinux code">
POL_SetupWindow_menu_list "What's your favorite color?" "$TITLE" "Red~Green~Blue" "~"
</pre>

=== POL_SetupWindow_checkbox_list (4.0+) ===

'''Arguments:'''

# Message.
# Title (often $TITLE).
# Available choices.
# 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:'''
<pre class="playonlinux code">
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
</pre>

=== 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:'''
<pre class="playonlinux code">
POL_SetupWindow_cdrom
</pre>

=== POL_SetupWindow_check_cdrom (4.0+) ===

'''Arguments:'''

# 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:'''
<pre class="playonlinux code">
POL_SetupWindow_check_cdrom "Data/32_icon.ico"
</pre>

=== POL_SetupWindow_InstallMethod (4.0+) ===

'''Arguments:'''

# 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:'''
<pre class="playonlinux code">
POL_SetupWindow_InstallMethod "LOCAL,CD,STEAM"
</pre>

== POL_RequiredVersion (4.0.15+) ==

'''Arguments:'''

# 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, it itself only appeared in PlayOnLinux 4.0.15, and PlayOnLinux 4.0.14 is still the default in some distributions; 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_AdvisedVersion (4.0.15+) ==

'''Arguments:'''

# 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:'''

# Executable filename.
# Launcher name (often $TITLE).
# Optional name of the icon to download from PlayOnLinux website.
# Optional executable arguments.
# 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 [http://linux.die.net/man/7/glob 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 [http://standards.freedesktop.org/menu-spec/latest/apa.html main] and [http://standards.freedesktop.org/menu-spec/latest/apas02.html 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:'''
<pre class="playonlinux code">
POL_Shortcut "firefox.exe" "$TITLE"
</pre>

== POL_Shortcut_InsertBeforeWine (4.0+) ==

'''Arguments:'''

# Launcher name (often $TITLE).
# Command to add.

'''Description:'''

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

'''Example:'''
<pre class="playonlinux code">
POL_Shortcut_InsertBeforeWine "Jedi Knight II" "export __GL_ExtensionStringVersion=17700"
</pre>

== POL_Shortcut_Document (4.0.15+) ==
'''Arguments:'''
# Launcher name (often $TITLE).
# 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:'''

# URL to open.

'''Description:'''

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

'''Example:'''
<pre class="playonlinux code">
POL_Browser "http://www.playonlinux.com"
</pre>

== POL_Download (4.0+) ==

'''Arguments:'''

# URL to download.
# (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:'''

# URL to download.
# Expected MD5 digest of the downloaded file
# (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:'''

# 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:'''
<pre class="playonlinux code">
POL_System_TmpCreate "$PREFIX"
</pre>

== POL_System_TmpDelete (4.0+) ==

'''Description:'''

Removes the script's temporary directory.

'''Example:'''
<pre class="playonlinux code">
POL_System_TmpDelete
</pre>

== POL_System_SetArch (4.0+) ==

'''Arguments:'''

# 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:'''
<pre class="playonlinux code">
POL_System_SetArch "auto"
</pre>

== POL_Call (4.0+) ==

'''Arguments:'''

# Function name.
# 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|Components and Functions]]).

'''Prerequisite:'''

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

'''Example:'''
<pre class="playonlinux code">
POL_Call POL_Install_vcrun6
</pre>

== Wine-related functions ==

=== POL_Wine_SelectPrefix (4.0+) ===

'''Arguments:'''

# 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:'''
<pre class="playonlinux code">
POL_Wine_SelectPrefix "$PREFIX"
</pre>

=== POL_Wine_PrefixExists (4.0+) ===

'''Arguments:'''

# 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:'''
<pre class="playonlinux code">
if [ "$(POL_Wine_PrefixExists "$PREFIX")" = "False" ]
then
# The préfixe doesn't exist
fi
</pre>

=== POL_Wine_PrefixCreate (4.0+) ===

'''Arguments:'''

# 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:'''
<pre class="playonlinux code">
POL_Wine_PrefixCreate "1.3.4"
</pre>

=== 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:'''

# 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 in the global PlayOnLinux configuration, so the user is not asked again during next installations. In case of mistake, or if this value 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:'''
<pre class="playonlinux code">
POL_SetupWindow_VMS "128"
</pre>

=== Set_OS (4.0+) ===

'''Arguments:'''

# Windows version to emulate.
# 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:'''
<pre class="playonlinux code">
Set_OS "win2k"
</pre>

=== Set_Managed (4.0+) ===

'''Arguments:'''

# 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:'''
<pre class="playonlinux code">
Set_Managed "Off"
</pre>

=== Set_SoundDriver (4.0+) ===

'''Arguments:'''

# alsa/oss/esd.

'''Description:'''

Set the audio driver Wine will use.

{{Info|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:'''
<pre class="playonlinux code">
Set_SoundDriver "alsa"
</pre>

=== POL_Wine_Direct3D (4.0+) ===

'''Arguments:'''

# Setting to create/modify.
# New setting value.

'''Description:'''

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

'''Allowed values:'''

See [http://wiki.winehq.org/UsefulRegistryKeys WineHQ's Wiki].

'''Prerequisite:'''

The commands POL_Wine_SelectPrefix and POL_Wine_PrefixCreate must have been used beforehand.

'''Example:'''
<pre class="playonlinux code">
POL_Wine_Direct3D "UseGLSL" "disabled"
</pre>

=== POL_Wine_X11Drv (4.0.14+) ===

'''Arguments:'''

# Setting to create/modify.
# New setting value.

'''Description:'''

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

'''Allowed values:'''

See [http://wiki.winehq.org/UsefulRegistryKeys WineHQ's Wiki].

'''Prerequisite:'''

The commands POL_Wine_SelectPrefix and POL_Wine_PrefixCreate must have been used beforehand.

'''Example:'''
<pre class="playonlinux code">
POL_Wine_X11Drv "DXGrab" "Y"
</pre>

=== POL_Wine_DirectSound (4.0+) ===

'''Arguments:'''

# Setting to create/modify.
# New setting value.

'''Description:'''

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

'''Allowed values:'''

See [http://wiki.winehq.org/UsefulRegistryKeys WineHQ's Wiki].

'''Prerequisite:'''

The commands POL_Wine_SelectPrefix and POL_Wine_PrefixCreate must have been used beforehand.

'''Example:'''
<pre class="playonlinux code">
POL_Wine_DirectSound "HardwareAcceleration" "Emulation"
</pre>

=== POL_Wine_DirectInput (4.0+) ===

'''Arguments:'''

# Setting to create/modify.
# New setting value.

'''Description:'''

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

'''Allowed values:'''

See [http://wiki.winehq.org/UsefulRegistryKeys WineHQ's Wiki].

'''Prerequisite:'''

The commands POL_Wine_SelectPrefix and POL_Wine_PrefixCreate must have been used beforehand.

'''Example:'''
<pre class="playonlinux code">
POL_Wine_DirectInput "MouseWarpOverride" "force"
</pre>

=== POL_Wine_GetRegValue (4.0+) ===

'''Arguments:'''

# 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:'''
<pre class="playonlinux code">
VALUE="$(POL_Wine_GetRegValue "MouseWarpOverride")"
</pre>

=== Set_Desktop (4.0+) ===

'''Arguments:'''

# On/Off.
# Virtual desktop width (if it is enabled).
# 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:'''
<pre class="playonlinux code">
Set_Desktop "On" "1024" "768"
</pre>

=== Set_WineWindowTitle (4.0+) ===

'''Arguments:'''

# 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:'''
<pre class="playonlinux code">
Set_WineWindowTitle "$TITLE"
</pre>

=== 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:'''
<pre class="playonlinux code">
POL_Wine_InstallFonts
</pre>

=== 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:'''
<pre class="playonlinux code">
POL_Wine_SetVideoDriver
</pre>

=== POL_Wine_OverrideDLL (4.0+) ===

'''Arguments:'''

# Mode of override.
# 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:'''
<pre class="playonlinux code">
POL_Wine_OverrideDLL "native" "msvcrt"
POL_Wine_OverrideDLL "" "msvcrt" # To disable the DLL
</pre>

=== POL_Wine_OverrideDLL_App (4.0+) ===

'''Arguments:'''

# Executable name.
# Mode of override.
# 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:'''
<pre class="playonlinux code">
POL_Wine_OverrideDLL_App "firefox.exe" "native" "msvcrt"
POL_Wine_OverrideDLL_App "firefox.exe" "" "msvcrt" # To disable the DLL
</pre>

=== POL_Wine_WaitBefore (4.0.15+) ===

'''Arguments:'''

# 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:'''

# 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:'''
<pre class="playonlinux code">
POL_Wine_WaitExit "$TITLE"
</pre>

=== 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:'''
<pre class="playonlinux code">
POL_Wine_reboot
</pre>

== Debugging commands ==

=== POL_Debug_Init (4.0+) ===

'''Description:'''

Start debugging system.

'''Example:'''
<pre class="playonlinux code">
POL_Debug_Init
</pre>

=== POL_Debug_Message (4.0+) ===

'''Arguments:'''

# 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:'''
<pre class="playonlinux code">
POL_Debug_Message "Modifying config.cfg file."
</pre>

=== POL_Debug_Warning (4.0+) ===

'''Arguments:'''

# 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:'''
<pre class="playonlinux code">
POL_Debug_Warning "File config.cfg did not exist, creating one."
</pre>

=== POL_Debug_Error (4.0+) ===

'''Arguments:'''

# 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:'''
<pre class="playonlinux code">
POL_Debug_Error "Error while modifying config.cfg file"
</pre>

=== POL_Debug_Fatal (4.0+) ===

'''Arguments:'''

# Message.

'''Description:'''

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

'''Prerequisite:'''

The command POL_Debug_Init must have been used beforehand.

'''Example:'''
<pre class="playonlinux code">
POL_Debug_Fatal "Error while modifying config.cfg file"
</pre>

'''Previous:''' [[Scripting - Chapter 10: Script Translation|Chapter 10: Script Translation]]

[[Category:Scripting]]

Installing PlayOnLinux

2015-04-12T09:53:45Z

Petch: /* Using GIT Version */ Some details about usage of cloned repositories on Linux and Mac

PlayOnLinux is available in the repositories of a lot of distributions, but with the exception of pacman, the versions found in these repositories are rarely the latest versions available. We genuinely encourage every use to use the latest version possible, as many things can change between releases.

You will find below the three methods that you are offered to install PlayOnLinux on your machine.

=== Distribution Repository ===

This method is probably the one that most users will use first. It has the advantage that it will provide generally a package approved by your distribution and thus generally better integrated with your OS.

Unfortunately, this method is not guaranteed to have the most updated version of the software. As for that, the updates on the repositories are not maintained by the PlayOnLinux team. It is because of this that distribution repository version are delayed by one or two revision. This may have the negative effect of not being able to properly use the tools that interact with the site (eg uploading of error reporting).

We urge you to follow instead the following method that guarantees you always use an updated software.

=== Following the guide on the site ===

You will find on the site a "Download" section. This section explains how to install PlayOnLinux on your machine while ensuring that you always use the software to its latest stable version.

Users using pacman will still have the latest version available. However, for other distributions, it is recommended to add the repo for PlayOnLinux in your repository list. To do this, just follow the information for your distribution.

For users' Debian wheezy '' and '' Ubuntu Precise (and higher), '' they'll need to install the i386 version of Wine. For this, we must enable support for i386 in your repository manager.

==== On Debian wheezy ====

To install wine:i386 Debian, you must first enable support for this architecture (with dpkg). You can then update the repository and install wine:i386

<pre class="code bash">
sudo dpkg --add-i386
sudo apt-get update
sudo apt-get install wine:i386
</pre>

==== On Ubuntu Precise (and higher) ====

To install wine:i386 on Ubuntu, you must first enable support for this architecture (with dpkg configuration file). You can then update the repository and install wine:i386

<pre class='code bash'>
sudo echo "foreign-i386 architecture"> /etc/dpkg/dpkg.cfg.d/multiarch
sudo apt-get update
sudo apt-get install wine:i386
</pre>

=== Using GIT Version ===

The git version can always have the updated program. It is only recommended for advanced users and programmers. It has the advantage of providing automatic update button, unlike other version of the program. To install it on your computer, you must install and configure git. Once this is done, you can download PlayOnLinux using the following command:

<pre class='code bash'>
git clone https://github.com/PlayOnLinux/POL-POM-4
</pre>

{{Info|This command will download the program to your current folder. Consider making use of 'cd' before running the command to get to where you want the files to be downloaded to. }}Unlike package installations, this method won't install PlayOnLinux system-wide; To run the development version you'll have to run the "playonlinux" script found in the root directory of the cloned repository.

{{Info|On Mac, the easier way to use the development version is to first deploy a stable version of PlayOnMac, then to replace /Applications/PlayOnMac.app/Contents/Resources/playonlinux folder with a clone of the git repository.}}

=== Next? ===

Now that you have installed on your computer PlayOnLinux, I suggest you to read our [[First Use| guide for first use of the software]] who will explain the basics to know to install and uninstall Windows programs with PlayOnLinux.

Talk:Scripting - Chapter 11: List of Functions

2015-03-29T12:30:31Z

Petch: Remove "check_one - POL_SetupWindow_missing" since they're obsolete?

Remove "check_one - POL_SetupWindow_missing" since they're obsolete?

Scripting - Chapter 11: List of Functions

2015-03-29T12:27:34Z

Petch: /* POL_Wine_OverrideDLL_App (4.0+) */ Quote accepted values to lift ambiguities

== 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+) ===

'''Arguments:'''

# URL of top image.
# URL of left image.
# 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:'''
<pre class="playonlinux code">
POL_GetSetupImages "http://files.playonlinux.com/resources/setups/AC2/top.jpg" "http://files.playonlinux.com/resources/setups/AC2/left.jpg" "$TITLE"
</pre>

=== POL_SetupWindow_Init (4.0+) ===

'''Description:'''

Opens the installation wizard window.

'''Example:'''
<pre class="playonlinux code">
POL_SetupWindow_Init
</pre>

=== POL_SetupWindow_Close (4.0+) ===

'''Description:'''

Closes the installation wizard window.

'''Example:'''
<pre class="playonlinux code">
POL_SetupWindow_Close
</pre>

== PlayOnLinux graphical interface ==

{{Warning|All the functions below need the command POL_SetupWindow_Init to be executed beforehand.}}

=== POL_SetupWindow_presentation (4.0+) ===

'''Arguments:'''

# Software name (often $TITLE).
# Software publisher.
# Site of the publisher.
# Script author.
# Prefix name (usually $PREFIX).

'''Description:'''

Present the software.

'''Example:'''
<pre class="playonlinux code">
POL_SetupWindow_presentation "$TITLE" "Mozilla" "http://www.mozilla.com" "SuperPlumus and NSLW" "$PREFIX"
</pre>

=== POL_SetupWindow_free_presentation (4.0+) ===

'''Arguments:'''

# Software name (often $TITLE).
# Message.

'''Description:'''

Present the software with more freedom than POL_SetupWindow_presentation.

'''Example:'''
<pre class="playonlinux code">
POL_SetupWindow_free_presentation "$TITLE" "Welcome to Mozilla Firefox installation wizard."
</pre>

=== POL_SetupWindow_message (4.0+) ===

'''Arguments:'''

# Message.
# Title (often $TITLE).

'''Description:'''

Display a message.

'''Example:'''
<pre class="playonlinux code">
POL_SetupWindow_message "Hello world!" "$TITLE"
</pre>

=== check_one - POL_SetupWindow_missing (4.0-4.1.1) ===

'''Arguments for check_one:'''

# Program that must be present.
# 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:'''
<pre class="playonlinux code">
check_one "p7zip" "p7zip"
POL_SetupWindow_missing
</pre>

=== POL_SetupWindow_file (4.0+) ===

'''Arguments:'''

# Message.
# Title (often $TITLE).
# File to display.

'''Description:'''

Display the content of a file.

'''Example:'''
<pre class="playonlinux code">
POL_SetupWindow_file "Changelog" "$TITLE" "$POL_System_TmpDir/changelog.txt"
</pre>

=== POL_SetupWindow_licence (4.0+) ===

'''Arguments:'''

# Message.
# Title (often $TITLE).
# File to display.

'''Description:'''

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

Useful for displaying licenses.

'''Example:'''
<pre class="playonlinux code">
POL_SetupWindow_licence "Licence:" "$TITLE" "$POL_System_TmpDir/licence.txt"
</pre>

=== POL_SetupWindow_pulsebar - POL_SetupWindow_pulse - POL_SetupWindow_set_text (4.0+) ===

'''Arguments for POL_SetupWindow_pulsebar:'''

# Message.
# Title (often $TITLE).

'''Arguments for POL_SetupWindow_pulse:'''

# Percentage.

'''Arguments for POL_SetupWindow_set_text:'''

# 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:'''
<pre class="playonlinux code">
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"
</pre>

=== POL_SetupWindow_wait (4.0+) ===

'''Arguments:'''

# Message.
# Title (often $TITLE).

'''Description:'''

Display an indeterminate progress bar.

'''Example:'''
<pre class="playonlinux code">
POL_SetupWindow_wait "Please wait" "$TITLE"
</pre>

=== POL_SetupWindow_textbox (4.0+) ===

'''Arguments:'''

# Message.
# Title (often $TITLE).
# 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:'''
<pre class="playonlinux code">
POL_SetupWindow_textbox "Votre pseudo :" "$TITLE"
</pre>

=== POL_SetupWindow_textbox_multiline (4.0+) ===

'''Arguments:'''

# Message.
# Title (often $TITLE).
# 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:'''
<pre class="playonlinux code">
POL_SetupWindow_textbox_multiline "Enter a description for the program" "$TITLE"
</pre>

=== POL_SetupWindow_browse (4.0+) ===

'''Arguments:'''

# Message.
# Title (often $TITLE).
# 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:'''
<pre class="playonlinux code">
POL_SetupWindow_browse "Please select the program." "$TITLE"
</pre>

=== POL_SetupWindow_question (4.0+) ===

'''Arguments:'''

# Message.
# 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:'''
<pre class="playonlinux code">
POL_SetupWindow_question "Message" "Title"
</pre>

=== POL_SetupWindow_menu (4.0+) ===

'''Arguments:'''

# Message.
# Title (often $TITLE).
# Available choices.
# 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:'''
<pre class="playonlinux code">
POL_SetupWindow_menu "What's your favorite color?" "$TITLE" "Red~Green~Blue" "~"
</pre>

=== POL_SetupWindow_menu_num (4.0+) ===

'''Arguments:'''

# Message.
# Title (often $TITLE).
# Available choices.
# 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:'''
<pre class="playonlinux code">
POL_SetupWindow_menu_num "What's your favorite color?" "$TITLE" "Red~Green~Blue" "~"
</pre>

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

=== POL_SetupWindow_menu_list (4.0+) ===

'''Arguments:'''

# Message.
# Title (often $TITLE).
# Available choices.
# Separator character (often ~ or -).
# 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:'''
<pre class="playonlinux code">
POL_SetupWindow_menu_list "What's your favorite color?" "$TITLE" "Red~Green~Blue" "~"
</pre>

=== POL_SetupWindow_checkbox_list (4.0+) ===

'''Arguments:'''

# Message.
# Title (often $TITLE).
# Available choices.
# 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:'''
<pre class="playonlinux code">
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
</pre>

=== 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:'''
<pre class="playonlinux code">
POL_SetupWindow_cdrom
</pre>

=== POL_SetupWindow_check_cdrom (4.0+) ===

'''Arguments:'''

# 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:'''
<pre class="playonlinux code">
POL_SetupWindow_check_cdrom "Data/32_icon.ico"
</pre>

=== POL_SetupWindow_InstallMethod (4.0+) ===

'''Arguments:'''

# 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:'''
<pre class="playonlinux code">
POL_SetupWindow_InstallMethod "LOCAL,CD,STEAM"
</pre>

== POL_RequiredVersion (4.0.15+) ==

'''Arguments:'''

# 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, it itself only appeared in PlayOnLinux 4.0.15, and PlayOnLinux 4.0.14 is still the default in some distributions; 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_AdvisedVersion (4.0.15+) ==

'''Arguments:'''

# 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:'''

# Executable filename.
# Launcher name (often $TITLE).
# Optional name of the icon to download from PlayOnLinux website.
# Optional executable arguments.
# 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 [http://linux.die.net/man/7/glob 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 [http://standards.freedesktop.org/menu-spec/latest/apa.html main] and [http://standards.freedesktop.org/menu-spec/latest/apas02.html 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:'''
<pre class="playonlinux code">
POL_Shortcut "firefox.exe" "$TITLE"
</pre>

== POL_Shortcut_InsertBeforeWine (4.0+) ==

'''Arguments:'''

# Launcher name (often $TITLE).
# Command to add.

'''Description:'''

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

'''Example:'''
<pre class="playonlinux code">
POL_Shortcut_InsertBeforeWine "Jedi Knight II" "export __GL_ExtensionStringVersion=17700"
</pre>

== POL_Shortcut_Document (4.0.15+) ==
'''Arguments:'''
# Launcher name (often $TITLE).
# 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:'''

# URL to open.

'''Description:'''

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

'''Example:'''
<pre class="playonlinux code">
POL_Browser "http://www.playonlinux.com"
</pre>

== POL_Download (4.0+) ==

'''Arguments:'''

# URL to download.
# (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:'''

# URL to download.
# Expected MD5 digest of the downloaded file
# (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:'''

# 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:'''
<pre class="playonlinux code">
POL_System_TmpCreate "$PREFIX"
</pre>

== POL_System_TmpDelete (4.0+) ==

'''Description:'''

Removes the script's temporary directory.

'''Example:'''
<pre class="playonlinux code">
POL_System_TmpDelete
</pre>

== POL_System_SetArch (4.0+) ==

'''Arguments:'''

# 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:'''
<pre class="playonlinux code">
POL_System_SetArch "auto"
</pre>

== POL_Call (4.0+) ==

'''Arguments:'''

# Function name.
# 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|Components and Functions]]).

'''Prerequisite:'''

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

'''Example:'''
<pre class="playonlinux code">
POL_Call POL_Install_vcrun6
</pre>

== Wine-related functions ==

=== POL_Wine_SelectPrefix (4.0+) ===

'''Arguments:'''

# 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:'''
<pre class="playonlinux code">
POL_Wine_SelectPrefix "$PREFIX"
</pre>

=== POL_Wine_PrefixExists (4.0+) ===

'''Arguments:'''

# 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:'''
<pre class="playonlinux code">
if [ "$(POL_Wine_PrefixExists "$PREFIX")" = "False" ]
then
# The préfixe doesn't exist
fi
</pre>

=== POL_Wine_PrefixCreate (4.0+) ===

'''Arguments:'''

# 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:'''
<pre class="playonlinux code">
POL_Wine_PrefixCreate "1.3.4"
</pre>

=== 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:'''

# 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:'''
<pre class="playonlinux code">
POL_SetupWindow_VMS "128"
</pre>

=== Set_OS (4.0+) ===

'''Arguments:'''

# Windows version to emulate.
# 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:'''
<pre class="playonlinux code">
Set_OS "win2k"
</pre>

=== Set_Managed (4.0+) ===

'''Arguments:'''

# 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:'''
<pre class="playonlinux code">
Set_Managed "Off"
</pre>

=== Set_SoundDriver (4.0+) ===

'''Arguments:'''

# alsa/oss/esd.

'''Description:'''

Set the audio driver Wine will use.

{{Info|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:'''
<pre class="playonlinux code">
Set_SoundDriver "alsa"
</pre>

=== POL_Wine_Direct3D (4.0+) ===

'''Arguments:'''

# Setting to create/modify.
# New setting value.

'''Description:'''

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

'''Allowed values:'''

See [http://wiki.winehq.org/UsefulRegistryKeys WineHQ's Wiki].

'''Prerequisite:'''

The commands POL_Wine_SelectPrefix and POL_Wine_PrefixCreate must have been used beforehand.

'''Example:'''
<pre class="playonlinux code">
POL_Wine_Direct3D "UseGLSL" "disabled"
</pre>

=== POL_Wine_X11Drv (4.0.14+) ===

'''Arguments:'''

# Setting to create/modify.
# New setting value.

'''Description:'''

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

'''Allowed values:'''

See [http://wiki.winehq.org/UsefulRegistryKeys WineHQ's Wiki].

'''Prerequisite:'''

The commands POL_Wine_SelectPrefix and POL_Wine_PrefixCreate must have been used beforehand.

'''Example:'''
<pre class="playonlinux code">
POL_Wine_X11Drv "DXGrab" "Y"
</pre>

=== POL_Wine_DirectSound (4.0+) ===

'''Arguments:'''

# Setting to create/modify.
# New setting value.

'''Description:'''

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

'''Allowed values:'''

See [http://wiki.winehq.org/UsefulRegistryKeys WineHQ's Wiki].

'''Prerequisite:'''

The commands POL_Wine_SelectPrefix and POL_Wine_PrefixCreate must have been used beforehand.

'''Example:'''
<pre class="playonlinux code">
POL_Wine_DirectSound "HardwareAcceleration" "Emulation"
</pre>

=== POL_Wine_DirectInput (4.0+) ===

'''Arguments:'''

# Setting to create/modify.
# New setting value.

'''Description:'''

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

'''Allowed values:'''

See [http://wiki.winehq.org/UsefulRegistryKeys WineHQ's Wiki].

'''Prerequisite:'''

The commands POL_Wine_SelectPrefix and POL_Wine_PrefixCreate must have been used beforehand.

'''Example:'''
<pre class="playonlinux code">
POL_Wine_DirectInput "MouseWarpOverride" "force"
</pre>

=== POL_Wine_GetRegValue (4.0+) ===

'''Arguments:'''

# 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:'''
<pre class="playonlinux code">
VALUE="$(POL_Wine_GetRegValue "MouseWarpOverride")"
</pre>

=== Set_Desktop (4.0+) ===

'''Arguments:'''

# On/Off.
# Virtual desktop width (if it is enabled).
# 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:'''
<pre class="playonlinux code">
Set_Desktop "On" "1024" "768"
</pre>

=== Set_WineWindowTitle (4.0+) ===

'''Arguments:'''

# 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:'''
<pre class="playonlinux code">
Set_WineWindowTitle "$TITLE"
</pre>

=== 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:'''
<pre class="playonlinux code">
POL_Wine_InstallFonts
</pre>

=== 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:'''
<pre class="playonlinux code">
POL_Wine_SetVideoDriver
</pre>

=== POL_Wine_OverrideDLL (4.0+) ===

'''Arguments:'''

# Mode of override.
# 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:'''
<pre class="playonlinux code">
POL_Wine_OverrideDLL "native" "msvcrt"
POL_Wine_OverrideDLL "" "msvcrt" # To disable the DLL
</pre>

=== POL_Wine_OverrideDLL_App (4.0+) ===

'''Arguments:'''

# Executable name.
# Mode of override.
# 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:'''
<pre class="playonlinux code">
POL_Wine_OverrideDLL_App "firefox.exe" "native" "msvcrt"
POL_Wine_OverrideDLL_App "firefox.exe" "" "msvcrt" # To disable the DLL
</pre>

=== POL_Wine_WaitBefore (4.0.15+) ===

'''Arguments:'''

# 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:'''

# 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:'''
<pre class="playonlinux code">
POL_Wine_WaitExit "$TITLE"
</pre>

=== 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:'''
<pre class="playonlinux code">
POL_Wine_reboot
</pre>

== Debugging commands ==

=== POL_Debug_Init (4.0+) ===

'''Description:'''

Start debugging system.

'''Example:'''
<pre class="playonlinux code">
POL_Debug_Init
</pre>

=== POL_Debug_Message (4.0+) ===

'''Arguments:'''

# 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:'''
<pre class="playonlinux code">
POL_Debug_Message "Modifying config.cfg file."
</pre>

=== POL_Debug_Warning (4.0+) ===

'''Arguments:'''

# 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:'''
<pre class="playonlinux code">
POL_Debug_Warning "File config.cfg did not exist, creating one."
</pre>

=== POL_Debug_Error (4.0+) ===

'''Arguments:'''

# 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:'''
<pre class="playonlinux code">
POL_Debug_Error "Error while modifying config.cfg file"
</pre>

=== POL_Debug_Fatal (4.0+) ===

'''Arguments:'''

# Message.

'''Description:'''

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

'''Prerequisite:'''

The command POL_Debug_Init must have been used beforehand.

'''Example:'''
<pre class="playonlinux code">
POL_Debug_Fatal "Error while modifying config.cfg file"
</pre>

'''Previous:''' [[Scripting - Chapter 10: Script Translation|Chapter 10: Script Translation]]

[[Category:Scripting]]

Scripting - Chapter 11: List of Functions

2015-03-29T12:27:00Z

Petch: /* POL_Wine_OverrideDLL (4.0+) */ Quote accepted values to lift ambiguities

== 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+) ===

'''Arguments:'''

# URL of top image.
# URL of left image.
# 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:'''
<pre class="playonlinux code">
POL_GetSetupImages "http://files.playonlinux.com/resources/setups/AC2/top.jpg" "http://files.playonlinux.com/resources/setups/AC2/left.jpg" "$TITLE"
</pre>

=== POL_SetupWindow_Init (4.0+) ===

'''Description:'''

Opens the installation wizard window.

'''Example:'''
<pre class="playonlinux code">
POL_SetupWindow_Init
</pre>

=== POL_SetupWindow_Close (4.0+) ===

'''Description:'''

Closes the installation wizard window.

'''Example:'''
<pre class="playonlinux code">
POL_SetupWindow_Close
</pre>

== PlayOnLinux graphical interface ==

{{Warning|All the functions below need the command POL_SetupWindow_Init to be executed beforehand.}}

=== POL_SetupWindow_presentation (4.0+) ===

'''Arguments:'''

# Software name (often $TITLE).
# Software publisher.
# Site of the publisher.
# Script author.
# Prefix name (usually $PREFIX).

'''Description:'''

Present the software.

'''Example:'''
<pre class="playonlinux code">
POL_SetupWindow_presentation "$TITLE" "Mozilla" "http://www.mozilla.com" "SuperPlumus and NSLW" "$PREFIX"
</pre>

=== POL_SetupWindow_free_presentation (4.0+) ===

'''Arguments:'''

# Software name (often $TITLE).
# Message.

'''Description:'''

Present the software with more freedom than POL_SetupWindow_presentation.

'''Example:'''
<pre class="playonlinux code">
POL_SetupWindow_free_presentation "$TITLE" "Welcome to Mozilla Firefox installation wizard."
</pre>

=== POL_SetupWindow_message (4.0+) ===

'''Arguments:'''

# Message.
# Title (often $TITLE).

'''Description:'''

Display a message.

'''Example:'''
<pre class="playonlinux code">
POL_SetupWindow_message "Hello world!" "$TITLE"
</pre>

=== check_one - POL_SetupWindow_missing (4.0-4.1.1) ===

'''Arguments for check_one:'''

# Program that must be present.
# 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:'''
<pre class="playonlinux code">
check_one "p7zip" "p7zip"
POL_SetupWindow_missing
</pre>

=== POL_SetupWindow_file (4.0+) ===

'''Arguments:'''

# Message.
# Title (often $TITLE).
# File to display.

'''Description:'''

Display the content of a file.

'''Example:'''
<pre class="playonlinux code">
POL_SetupWindow_file "Changelog" "$TITLE" "$POL_System_TmpDir/changelog.txt"
</pre>

=== POL_SetupWindow_licence (4.0+) ===

'''Arguments:'''

# Message.
# Title (often $TITLE).
# File to display.

'''Description:'''

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

Useful for displaying licenses.

'''Example:'''
<pre class="playonlinux code">
POL_SetupWindow_licence "Licence:" "$TITLE" "$POL_System_TmpDir/licence.txt"
</pre>

=== POL_SetupWindow_pulsebar - POL_SetupWindow_pulse - POL_SetupWindow_set_text (4.0+) ===

'''Arguments for POL_SetupWindow_pulsebar:'''

# Message.
# Title (often $TITLE).

'''Arguments for POL_SetupWindow_pulse:'''

# Percentage.

'''Arguments for POL_SetupWindow_set_text:'''

# 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:'''
<pre class="playonlinux code">
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"
</pre>

=== POL_SetupWindow_wait (4.0+) ===

'''Arguments:'''

# Message.
# Title (often $TITLE).

'''Description:'''

Display an indeterminate progress bar.

'''Example:'''
<pre class="playonlinux code">
POL_SetupWindow_wait "Please wait" "$TITLE"
</pre>

=== POL_SetupWindow_textbox (4.0+) ===

'''Arguments:'''

# Message.
# Title (often $TITLE).
# 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:'''
<pre class="playonlinux code">
POL_SetupWindow_textbox "Votre pseudo :" "$TITLE"
</pre>

=== POL_SetupWindow_textbox_multiline (4.0+) ===

'''Arguments:'''

# Message.
# Title (often $TITLE).
# 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:'''
<pre class="playonlinux code">
POL_SetupWindow_textbox_multiline "Enter a description for the program" "$TITLE"
</pre>

=== POL_SetupWindow_browse (4.0+) ===

'''Arguments:'''

# Message.
# Title (often $TITLE).
# 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:'''
<pre class="playonlinux code">
POL_SetupWindow_browse "Please select the program." "$TITLE"
</pre>

=== POL_SetupWindow_question (4.0+) ===

'''Arguments:'''

# Message.
# 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:'''
<pre class="playonlinux code">
POL_SetupWindow_question "Message" "Title"
</pre>

=== POL_SetupWindow_menu (4.0+) ===

'''Arguments:'''

# Message.
# Title (often $TITLE).
# Available choices.
# 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:'''
<pre class="playonlinux code">
POL_SetupWindow_menu "What's your favorite color?" "$TITLE" "Red~Green~Blue" "~"
</pre>

=== POL_SetupWindow_menu_num (4.0+) ===

'''Arguments:'''

# Message.
# Title (often $TITLE).
# Available choices.
# 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:'''
<pre class="playonlinux code">
POL_SetupWindow_menu_num "What's your favorite color?" "$TITLE" "Red~Green~Blue" "~"
</pre>

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

=== POL_SetupWindow_menu_list (4.0+) ===

'''Arguments:'''

# Message.
# Title (often $TITLE).
# Available choices.
# Separator character (often ~ or -).
# 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:'''
<pre class="playonlinux code">
POL_SetupWindow_menu_list "What's your favorite color?" "$TITLE" "Red~Green~Blue" "~"
</pre>

=== POL_SetupWindow_checkbox_list (4.0+) ===

'''Arguments:'''

# Message.
# Title (often $TITLE).
# Available choices.
# 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:'''
<pre class="playonlinux code">
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
</pre>

=== 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:'''
<pre class="playonlinux code">
POL_SetupWindow_cdrom
</pre>

=== POL_SetupWindow_check_cdrom (4.0+) ===

'''Arguments:'''

# 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:'''
<pre class="playonlinux code">
POL_SetupWindow_check_cdrom "Data/32_icon.ico"
</pre>

=== POL_SetupWindow_InstallMethod (4.0+) ===

'''Arguments:'''

# 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:'''
<pre class="playonlinux code">
POL_SetupWindow_InstallMethod "LOCAL,CD,STEAM"
</pre>

== POL_RequiredVersion (4.0.15+) ==

'''Arguments:'''

# 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, it itself only appeared in PlayOnLinux 4.0.15, and PlayOnLinux 4.0.14 is still the default in some distributions; 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_AdvisedVersion (4.0.15+) ==

'''Arguments:'''

# 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:'''

# Executable filename.
# Launcher name (often $TITLE).
# Optional name of the icon to download from PlayOnLinux website.
# Optional executable arguments.
# 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 [http://linux.die.net/man/7/glob 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 [http://standards.freedesktop.org/menu-spec/latest/apa.html main] and [http://standards.freedesktop.org/menu-spec/latest/apas02.html 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:'''
<pre class="playonlinux code">
POL_Shortcut "firefox.exe" "$TITLE"
</pre>

== POL_Shortcut_InsertBeforeWine (4.0+) ==

'''Arguments:'''

# Launcher name (often $TITLE).
# Command to add.

'''Description:'''

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

'''Example:'''
<pre class="playonlinux code">
POL_Shortcut_InsertBeforeWine "Jedi Knight II" "export __GL_ExtensionStringVersion=17700"
</pre>

== POL_Shortcut_Document (4.0.15+) ==
'''Arguments:'''
# Launcher name (often $TITLE).
# 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:'''

# URL to open.

'''Description:'''

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

'''Example:'''
<pre class="playonlinux code">
POL_Browser "http://www.playonlinux.com"
</pre>

== POL_Download (4.0+) ==

'''Arguments:'''

# URL to download.
# (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:'''

# URL to download.
# Expected MD5 digest of the downloaded file
# (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:'''

# 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:'''
<pre class="playonlinux code">
POL_System_TmpCreate "$PREFIX"
</pre>

== POL_System_TmpDelete (4.0+) ==

'''Description:'''

Removes the script's temporary directory.

'''Example:'''
<pre class="playonlinux code">
POL_System_TmpDelete
</pre>

== POL_System_SetArch (4.0+) ==

'''Arguments:'''

# 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:'''
<pre class="playonlinux code">
POL_System_SetArch "auto"
</pre>

== POL_Call (4.0+) ==

'''Arguments:'''

# Function name.
# 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|Components and Functions]]).

'''Prerequisite:'''

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

'''Example:'''
<pre class="playonlinux code">
POL_Call POL_Install_vcrun6
</pre>

== Wine-related functions ==

=== POL_Wine_SelectPrefix (4.0+) ===

'''Arguments:'''

# 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:'''
<pre class="playonlinux code">
POL_Wine_SelectPrefix "$PREFIX"
</pre>

=== POL_Wine_PrefixExists (4.0+) ===

'''Arguments:'''

# 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:'''
<pre class="playonlinux code">
if [ "$(POL_Wine_PrefixExists "$PREFIX")" = "False" ]
then
# The préfixe doesn't exist
fi
</pre>

=== POL_Wine_PrefixCreate (4.0+) ===

'''Arguments:'''

# 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:'''
<pre class="playonlinux code">
POL_Wine_PrefixCreate "1.3.4"
</pre>

=== 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:'''

# 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:'''
<pre class="playonlinux code">
POL_SetupWindow_VMS "128"
</pre>

=== Set_OS (4.0+) ===

'''Arguments:'''

# Windows version to emulate.
# 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:'''
<pre class="playonlinux code">
Set_OS "win2k"
</pre>

=== Set_Managed (4.0+) ===

'''Arguments:'''

# 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:'''
<pre class="playonlinux code">
Set_Managed "Off"
</pre>

=== Set_SoundDriver (4.0+) ===

'''Arguments:'''

# alsa/oss/esd.

'''Description:'''

Set the audio driver Wine will use.

{{Info|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:'''
<pre class="playonlinux code">
Set_SoundDriver "alsa"
</pre>

=== POL_Wine_Direct3D (4.0+) ===

'''Arguments:'''

# Setting to create/modify.
# New setting value.

'''Description:'''

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

'''Allowed values:'''

See [http://wiki.winehq.org/UsefulRegistryKeys WineHQ's Wiki].

'''Prerequisite:'''

The commands POL_Wine_SelectPrefix and POL_Wine_PrefixCreate must have been used beforehand.

'''Example:'''
<pre class="playonlinux code">
POL_Wine_Direct3D "UseGLSL" "disabled"
</pre>

=== POL_Wine_X11Drv (4.0.14+) ===

'''Arguments:'''

# Setting to create/modify.
# New setting value.

'''Description:'''

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

'''Allowed values:'''

See [http://wiki.winehq.org/UsefulRegistryKeys WineHQ's Wiki].

'''Prerequisite:'''

The commands POL_Wine_SelectPrefix and POL_Wine_PrefixCreate must have been used beforehand.

'''Example:'''
<pre class="playonlinux code">
POL_Wine_X11Drv "DXGrab" "Y"
</pre>

=== POL_Wine_DirectSound (4.0+) ===

'''Arguments:'''

# Setting to create/modify.
# New setting value.

'''Description:'''

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

'''Allowed values:'''

See [http://wiki.winehq.org/UsefulRegistryKeys WineHQ's Wiki].

'''Prerequisite:'''

The commands POL_Wine_SelectPrefix and POL_Wine_PrefixCreate must have been used beforehand.

'''Example:'''
<pre class="playonlinux code">
POL_Wine_DirectSound "HardwareAcceleration" "Emulation"
</pre>

=== POL_Wine_DirectInput (4.0+) ===

'''Arguments:'''

# Setting to create/modify.
# New setting value.

'''Description:'''

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

'''Allowed values:'''

See [http://wiki.winehq.org/UsefulRegistryKeys WineHQ's Wiki].

'''Prerequisite:'''

The commands POL_Wine_SelectPrefix and POL_Wine_PrefixCreate must have been used beforehand.

'''Example:'''
<pre class="playonlinux code">
POL_Wine_DirectInput "MouseWarpOverride" "force"
</pre>

=== POL_Wine_GetRegValue (4.0+) ===

'''Arguments:'''

# 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:'''
<pre class="playonlinux code">
VALUE="$(POL_Wine_GetRegValue "MouseWarpOverride")"
</pre>

=== Set_Desktop (4.0+) ===

'''Arguments:'''

# On/Off.
# Virtual desktop width (if it is enabled).
# 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:'''
<pre class="playonlinux code">
Set_Desktop "On" "1024" "768"
</pre>

=== Set_WineWindowTitle (4.0+) ===

'''Arguments:'''

# 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:'''
<pre class="playonlinux code">
Set_WineWindowTitle "$TITLE"
</pre>

=== 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:'''
<pre class="playonlinux code">
POL_Wine_InstallFonts
</pre>

=== 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:'''
<pre class="playonlinux code">
POL_Wine_SetVideoDriver
</pre>

=== POL_Wine_OverrideDLL (4.0+) ===

'''Arguments:'''

# Mode of override.
# 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:'''
<pre class="playonlinux code">
POL_Wine_OverrideDLL "native" "msvcrt"
POL_Wine_OverrideDLL "" "msvcrt" # To disable the DLL
</pre>

=== POL_Wine_OverrideDLL_App (4.0+) ===

'''Arguments:'''

# Executable name.
# Mode of override.
# 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:'''
<pre class="playonlinux code">
POL_Wine_OverrideDLL_App "firefox.exe" "native" "msvcrt"
POL_Wine_OverrideDLL_App "firefox.exe" "" "msvcrt" # To disable the DLL
</pre>

=== POL_Wine_WaitBefore (4.0.15+) ===

'''Arguments:'''

# 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:'''

# 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:'''
<pre class="playonlinux code">
POL_Wine_WaitExit "$TITLE"
</pre>

=== 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:'''
<pre class="playonlinux code">
POL_Wine_reboot
</pre>

== Debugging commands ==

=== POL_Debug_Init (4.0+) ===

'''Description:'''

Start debugging system.

'''Example:'''
<pre class="playonlinux code">
POL_Debug_Init
</pre>

=== POL_Debug_Message (4.0+) ===

'''Arguments:'''

# 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:'''
<pre class="playonlinux code">
POL_Debug_Message "Modifying config.cfg file."
</pre>

=== POL_Debug_Warning (4.0+) ===

'''Arguments:'''

# 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:'''
<pre class="playonlinux code">
POL_Debug_Warning "File config.cfg did not exist, creating one."
</pre>

=== POL_Debug_Error (4.0+) ===

'''Arguments:'''

# 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:'''
<pre class="playonlinux code">
POL_Debug_Error "Error while modifying config.cfg file"
</pre>

=== POL_Debug_Fatal (4.0+) ===

'''Arguments:'''

# Message.

'''Description:'''

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

'''Prerequisite:'''

The command POL_Debug_Init must have been used beforehand.

'''Example:'''
<pre class="playonlinux code">
POL_Debug_Fatal "Error while modifying config.cfg file"
</pre>

'''Previous:''' [[Scripting - Chapter 10: Script Translation|Chapter 10: Script Translation]]

[[Category:Scripting]]

Scripting - Chapter 11: List of Functions

2015-03-29T12:25:35Z

Petch: Document the version each statement appeared in

== 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+) ===

'''Arguments:'''

# URL of top image.
# URL of left image.
# 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:'''
<pre class="playonlinux code">
POL_GetSetupImages "http://files.playonlinux.com/resources/setups/AC2/top.jpg" "http://files.playonlinux.com/resources/setups/AC2/left.jpg" "$TITLE"
</pre>

=== POL_SetupWindow_Init (4.0+) ===

'''Description:'''

Opens the installation wizard window.

'''Example:'''
<pre class="playonlinux code">
POL_SetupWindow_Init
</pre>

=== POL_SetupWindow_Close (4.0+) ===

'''Description:'''

Closes the installation wizard window.

'''Example:'''
<pre class="playonlinux code">
POL_SetupWindow_Close
</pre>

== PlayOnLinux graphical interface ==

{{Warning|All the functions below need the command POL_SetupWindow_Init to be executed beforehand.}}

=== POL_SetupWindow_presentation (4.0+) ===

'''Arguments:'''

# Software name (often $TITLE).
# Software publisher.
# Site of the publisher.
# Script author.
# Prefix name (usually $PREFIX).

'''Description:'''

Present the software.

'''Example:'''
<pre class="playonlinux code">
POL_SetupWindow_presentation "$TITLE" "Mozilla" "http://www.mozilla.com" "SuperPlumus and NSLW" "$PREFIX"
</pre>

=== POL_SetupWindow_free_presentation (4.0+) ===

'''Arguments:'''

# Software name (often $TITLE).
# Message.

'''Description:'''

Present the software with more freedom than POL_SetupWindow_presentation.

'''Example:'''
<pre class="playonlinux code">
POL_SetupWindow_free_presentation "$TITLE" "Welcome to Mozilla Firefox installation wizard."
</pre>

=== POL_SetupWindow_message (4.0+) ===

'''Arguments:'''

# Message.
# Title (often $TITLE).

'''Description:'''

Display a message.

'''Example:'''
<pre class="playonlinux code">
POL_SetupWindow_message "Hello world!" "$TITLE"
</pre>

=== check_one - POL_SetupWindow_missing (4.0-4.1.1) ===

'''Arguments for check_one:'''

# Program that must be present.
# 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:'''
<pre class="playonlinux code">
check_one "p7zip" "p7zip"
POL_SetupWindow_missing
</pre>

=== POL_SetupWindow_file (4.0+) ===

'''Arguments:'''

# Message.
# Title (often $TITLE).
# File to display.

'''Description:'''

Display the content of a file.

'''Example:'''
<pre class="playonlinux code">
POL_SetupWindow_file "Changelog" "$TITLE" "$POL_System_TmpDir/changelog.txt"
</pre>

=== POL_SetupWindow_licence (4.0+) ===

'''Arguments:'''

# Message.
# Title (often $TITLE).
# File to display.

'''Description:'''

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

Useful for displaying licenses.

'''Example:'''
<pre class="playonlinux code">
POL_SetupWindow_licence "Licence:" "$TITLE" "$POL_System_TmpDir/licence.txt"
</pre>

=== POL_SetupWindow_pulsebar - POL_SetupWindow_pulse - POL_SetupWindow_set_text (4.0+) ===

'''Arguments for POL_SetupWindow_pulsebar:'''

# Message.
# Title (often $TITLE).

'''Arguments for POL_SetupWindow_pulse:'''

# Percentage.

'''Arguments for POL_SetupWindow_set_text:'''

# 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:'''
<pre class="playonlinux code">
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"
</pre>

=== POL_SetupWindow_wait (4.0+) ===

'''Arguments:'''

# Message.
# Title (often $TITLE).

'''Description:'''

Display an indeterminate progress bar.

'''Example:'''
<pre class="playonlinux code">
POL_SetupWindow_wait "Please wait" "$TITLE"
</pre>

=== POL_SetupWindow_textbox (4.0+) ===

'''Arguments:'''

# Message.
# Title (often $TITLE).
# 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:'''
<pre class="playonlinux code">
POL_SetupWindow_textbox "Votre pseudo :" "$TITLE"
</pre>

=== POL_SetupWindow_textbox_multiline (4.0+) ===

'''Arguments:'''

# Message.
# Title (often $TITLE).
# 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:'''
<pre class="playonlinux code">
POL_SetupWindow_textbox_multiline "Enter a description for the program" "$TITLE"
</pre>

=== POL_SetupWindow_browse (4.0+) ===

'''Arguments:'''

# Message.
# Title (often $TITLE).
# 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:'''
<pre class="playonlinux code">
POL_SetupWindow_browse "Please select the program." "$TITLE"
</pre>

=== POL_SetupWindow_question (4.0+) ===

'''Arguments:'''

# Message.
# 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:'''
<pre class="playonlinux code">
POL_SetupWindow_question "Message" "Title"
</pre>

=== POL_SetupWindow_menu (4.0+) ===

'''Arguments:'''

# Message.
# Title (often $TITLE).
# Available choices.
# 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:'''
<pre class="playonlinux code">
POL_SetupWindow_menu "What's your favorite color?" "$TITLE" "Red~Green~Blue" "~"
</pre>

=== POL_SetupWindow_menu_num (4.0+) ===

'''Arguments:'''

# Message.
# Title (often $TITLE).
# Available choices.
# 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:'''
<pre class="playonlinux code">
POL_SetupWindow_menu_num "What's your favorite color?" "$TITLE" "Red~Green~Blue" "~"
</pre>

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

=== POL_SetupWindow_menu_list (4.0+) ===

'''Arguments:'''

# Message.
# Title (often $TITLE).
# Available choices.
# Separator character (often ~ or -).
# 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:'''
<pre class="playonlinux code">
POL_SetupWindow_menu_list "What's your favorite color?" "$TITLE" "Red~Green~Blue" "~"
</pre>

=== POL_SetupWindow_checkbox_list (4.0+) ===

'''Arguments:'''

# Message.
# Title (often $TITLE).
# Available choices.
# 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:'''
<pre class="playonlinux code">
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
</pre>

=== 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:'''
<pre class="playonlinux code">
POL_SetupWindow_cdrom
</pre>

=== POL_SetupWindow_check_cdrom (4.0+) ===

'''Arguments:'''

# 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:'''
<pre class="playonlinux code">
POL_SetupWindow_check_cdrom "Data/32_icon.ico"
</pre>

=== POL_SetupWindow_InstallMethod (4.0+) ===

'''Arguments:'''

# 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:'''
<pre class="playonlinux code">
POL_SetupWindow_InstallMethod "LOCAL,CD,STEAM"
</pre>

== POL_RequiredVersion (4.0.15+) ==

'''Arguments:'''

# 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, it itself only appeared in PlayOnLinux 4.0.15, and PlayOnLinux 4.0.14 is still the default in some distributions; 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_AdvisedVersion (4.0.15+) ==

'''Arguments:'''

# 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:'''

# Executable filename.
# Launcher name (often $TITLE).
# Optional name of the icon to download from PlayOnLinux website.
# Optional executable arguments.
# 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 [http://linux.die.net/man/7/glob 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 [http://standards.freedesktop.org/menu-spec/latest/apa.html main] and [http://standards.freedesktop.org/menu-spec/latest/apas02.html 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:'''
<pre class="playonlinux code">
POL_Shortcut "firefox.exe" "$TITLE"
</pre>

== POL_Shortcut_InsertBeforeWine (4.0+) ==

'''Arguments:'''

# Launcher name (often $TITLE).
# Command to add.

'''Description:'''

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

'''Example:'''
<pre class="playonlinux code">
POL_Shortcut_InsertBeforeWine "Jedi Knight II" "export __GL_ExtensionStringVersion=17700"
</pre>

== POL_Shortcut_Document (4.0.15+) ==
'''Arguments:'''
# Launcher name (often $TITLE).
# 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:'''

# URL to open.

'''Description:'''

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

'''Example:'''
<pre class="playonlinux code">
POL_Browser "http://www.playonlinux.com"
</pre>

== POL_Download (4.0+) ==

'''Arguments:'''

# URL to download.
# (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:'''

# URL to download.
# Expected MD5 digest of the downloaded file
# (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:'''

# 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:'''
<pre class="playonlinux code">
POL_System_TmpCreate "$PREFIX"
</pre>

== POL_System_TmpDelete (4.0+) ==

'''Description:'''

Removes the script's temporary directory.

'''Example:'''
<pre class="playonlinux code">
POL_System_TmpDelete
</pre>

== POL_System_SetArch (4.0+) ==

'''Arguments:'''

# 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:'''
<pre class="playonlinux code">
POL_System_SetArch "auto"
</pre>

== POL_Call (4.0+) ==

'''Arguments:'''

# Function name.
# 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|Components and Functions]]).

'''Prerequisite:'''

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

'''Example:'''
<pre class="playonlinux code">
POL_Call POL_Install_vcrun6
</pre>

== Wine-related functions ==

=== POL_Wine_SelectPrefix (4.0+) ===

'''Arguments:'''

# 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:'''
<pre class="playonlinux code">
POL_Wine_SelectPrefix "$PREFIX"
</pre>

=== POL_Wine_PrefixExists (4.0+) ===

'''Arguments:'''

# 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:'''
<pre class="playonlinux code">
if [ "$(POL_Wine_PrefixExists "$PREFIX")" = "False" ]
then
# The préfixe doesn't exist
fi
</pre>

=== POL_Wine_PrefixCreate (4.0+) ===

'''Arguments:'''

# 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:'''
<pre class="playonlinux code">
POL_Wine_PrefixCreate "1.3.4"
</pre>

=== 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:'''

# 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:'''
<pre class="playonlinux code">
POL_SetupWindow_VMS "128"
</pre>

=== Set_OS (4.0+) ===

'''Arguments:'''

# Windows version to emulate.
# 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:'''
<pre class="playonlinux code">
Set_OS "win2k"
</pre>

=== Set_Managed (4.0+) ===

'''Arguments:'''

# 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:'''
<pre class="playonlinux code">
Set_Managed "Off"
</pre>

=== Set_SoundDriver (4.0+) ===

'''Arguments:'''

# alsa/oss/esd.

'''Description:'''

Set the audio driver Wine will use.

{{Info|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:'''
<pre class="playonlinux code">
Set_SoundDriver "alsa"
</pre>

=== POL_Wine_Direct3D (4.0+) ===

'''Arguments:'''

# Setting to create/modify.
# New setting value.

'''Description:'''

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

'''Allowed values:'''

See [http://wiki.winehq.org/UsefulRegistryKeys WineHQ's Wiki].

'''Prerequisite:'''

The commands POL_Wine_SelectPrefix and POL_Wine_PrefixCreate must have been used beforehand.

'''Example:'''
<pre class="playonlinux code">
POL_Wine_Direct3D "UseGLSL" "disabled"
</pre>

=== POL_Wine_X11Drv (4.0.14+) ===

'''Arguments:'''

# Setting to create/modify.
# New setting value.

'''Description:'''

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

'''Allowed values:'''

See [http://wiki.winehq.org/UsefulRegistryKeys WineHQ's Wiki].

'''Prerequisite:'''

The commands POL_Wine_SelectPrefix and POL_Wine_PrefixCreate must have been used beforehand.

'''Example:'''
<pre class="playonlinux code">
POL_Wine_X11Drv "DXGrab" "Y"
</pre>

=== POL_Wine_DirectSound (4.0+) ===

'''Arguments:'''

# Setting to create/modify.
# New setting value.

'''Description:'''

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

'''Allowed values:'''

See [http://wiki.winehq.org/UsefulRegistryKeys WineHQ's Wiki].

'''Prerequisite:'''

The commands POL_Wine_SelectPrefix and POL_Wine_PrefixCreate must have been used beforehand.

'''Example:'''
<pre class="playonlinux code">
POL_Wine_DirectSound "HardwareAcceleration" "Emulation"
</pre>

=== POL_Wine_DirectInput (4.0+) ===

'''Arguments:'''

# Setting to create/modify.
# New setting value.

'''Description:'''

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

'''Allowed values:'''

See [http://wiki.winehq.org/UsefulRegistryKeys WineHQ's Wiki].

'''Prerequisite:'''

The commands POL_Wine_SelectPrefix and POL_Wine_PrefixCreate must have been used beforehand.

'''Example:'''
<pre class="playonlinux code">
POL_Wine_DirectInput "MouseWarpOverride" "force"
</pre>

=== POL_Wine_GetRegValue (4.0+) ===

'''Arguments:'''

# 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:'''
<pre class="playonlinux code">
VALUE="$(POL_Wine_GetRegValue "MouseWarpOverride")"
</pre>

=== Set_Desktop (4.0+) ===

'''Arguments:'''

# On/Off.
# Virtual desktop width (if it is enabled).
# 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:'''
<pre class="playonlinux code">
Set_Desktop "On" "1024" "768"
</pre>

=== Set_WineWindowTitle (4.0+) ===

'''Arguments:'''

# 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:'''
<pre class="playonlinux code">
Set_WineWindowTitle "$TITLE"
</pre>

=== 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:'''
<pre class="playonlinux code">
POL_Wine_InstallFonts
</pre>

=== 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:'''
<pre class="playonlinux code">
POL_Wine_SetVideoDriver
</pre>

=== POL_Wine_OverrideDLL (4.0+) ===

'''Arguments:'''

# Mode of override.
# 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:'''
<pre class="playonlinux code">
POL_Wine_OverrideDLL "native" "msvcrt"
POL_Wine_OverrideDLL "" "msvcrt" # To disable the DLL
</pre>

=== POL_Wine_OverrideDLL_App (4.0+) ===

'''Arguments:'''

# Executable name.
# Mode of override.
# 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:'''
<pre class="playonlinux code">
POL_Wine_OverrideDLL_App "firefox.exe" "native" "msvcrt"
POL_Wine_OverrideDLL_App "firefox.exe" "" "msvcrt" # To disable the DLL
</pre>

=== POL_Wine_WaitBefore (4.0.15+) ===

'''Arguments:'''

# 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:'''

# 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:'''
<pre class="playonlinux code">
POL_Wine_WaitExit "$TITLE"
</pre>

=== 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:'''
<pre class="playonlinux code">
POL_Wine_reboot
</pre>

== Debugging commands ==

=== POL_Debug_Init (4.0+) ===

'''Description:'''

Start debugging system.

'''Example:'''
<pre class="playonlinux code">
POL_Debug_Init
</pre>

=== POL_Debug_Message (4.0+) ===

'''Arguments:'''

# 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:'''
<pre class="playonlinux code">
POL_Debug_Message "Modifying config.cfg file."
</pre>

=== POL_Debug_Warning (4.0+) ===

'''Arguments:'''

# 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:'''
<pre class="playonlinux code">
POL_Debug_Warning "File config.cfg did not exist, creating one."
</pre>

=== POL_Debug_Error (4.0+) ===

'''Arguments:'''

# 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:'''
<pre class="playonlinux code">
POL_Debug_Error "Error while modifying config.cfg file"
</pre>

=== POL_Debug_Fatal (4.0+) ===

'''Arguments:'''

# Message.

'''Description:'''

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

'''Prerequisite:'''

The command POL_Debug_Init must have been used beforehand.

'''Example:'''
<pre class="playonlinux code">
POL_Debug_Fatal "Error while modifying config.cfg file"
</pre>

'''Previous:''' [[Scripting - Chapter 10: Script Translation|Chapter 10: Script Translation]]

[[Category:Scripting]]

Scripting - Chapter 11: List of Functions

2015-03-29T10:37:09Z

Petch: /* POL_AdvisedVersion (4.0.15+) */ Fix example

== 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:'''

# URL of top image.
# URL of left image.
# 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:'''
<pre class="playonlinux code">
POL_GetSetupImages "http://files.playonlinux.com/resources/setups/AC2/top.jpg" "http://files.playonlinux.com/resources/setups/AC2/left.jpg" "$TITLE"
</pre>

=== POL_SetupWindow_Init ===

'''Description:'''

Opens the installation wizard window.

'''Example:'''
<pre class="playonlinux code">
POL_SetupWindow_Init
</pre>

=== POL_SetupWindow_Close ===

'''Description:'''

Closes the installation wizard window.

'''Example:'''
<pre class="playonlinux code">
POL_SetupWindow_Close
</pre>

== PlayOnLinux graphical interface ==

{{Warning|All the functions below need the command POL_SetupWindow_Init to be executed beforehand.}}

=== POL_SetupWindow_presentation ===

'''Arguments:'''

# Software name (often $TITLE).
# Software publisher.
# Site of the publisher.
# Script author.
# Prefix name (usually $PREFIX).

'''Description:'''

Present the software.

'''Example:'''
<pre class="playonlinux code">
POL_SetupWindow_presentation "$TITLE" "Mozilla" "http://www.mozilla.com" "SuperPlumus and NSLW" "$PREFIX"
</pre>

=== POL_SetupWindow_free_presentation ===

'''Arguments:'''

# Software name (often $TITLE).
# Message.

'''Description:'''

Present the software with more freedom than POL_SetupWindow_presentation.

'''Example:'''
<pre class="playonlinux code">
POL_SetupWindow_free_presentation "$TITLE" "Welcome to Mozilla Firefox installation wizard."
</pre>

=== POL_SetupWindow_message ===

'''Arguments:'''

# Message.
# Title (often $TITLE).

'''Description:'''

Display a message.

'''Example:'''
<pre class="playonlinux code">
POL_SetupWindow_message "Hello world!" "$TITLE"
</pre>

=== check_one - POL_SetupWindow_missing ===

'''Arguments for check_one:'''

# Program that must be present.
# 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:'''
<pre class="playonlinux code">
check_one "p7zip" "p7zip"
POL_SetupWindow_missing
</pre>

=== POL_SetupWindow_file ===

'''Arguments:'''

# Message.
# Title (often $TITLE).
# File to display.

'''Description:'''

Display the content of a file.

'''Example:'''
<pre class="playonlinux code">
POL_SetupWindow_file "Changelog" "$TITLE" "$POL_System_TmpDir/changelog.txt"
</pre>

=== POL_SetupWindow_licence ===

'''Arguments:'''

# Message.
# Title (often $TITLE).
# File to display.

'''Description:'''

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

Useful for displaying licenses.

'''Example:'''
<pre class="playonlinux code">
POL_SetupWindow_licence "Licence:" "$TITLE" "$POL_System_TmpDir/licence.txt"
</pre>

=== POL_SetupWindow_pulsebar - POL_SetupWindow_pulse - POL_SetupWindow_set_text ===

'''Arguments for POL_SetupWindow_pulsebar:'''

# Message.
# Title (often $TITLE).

'''Arguments for POL_SetupWindow_pulse:'''

# Percentage.

'''Arguments for POL_SetupWindow_set_text:'''

# 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:'''
<pre class="playonlinux code">
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"
</pre>

=== POL_SetupWindow_wait ===

'''Arguments:'''

# Message.
# Title (often $TITLE).

'''Description:'''

Display an indeterminate progress bar.

'''Example:'''
<pre class="playonlinux code">
POL_SetupWindow_wait "Please wait" "$TITLE"
</pre>

=== POL_SetupWindow_textbox ===

'''Arguments:'''

# Message.
# Title (often $TITLE).
# 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:'''
<pre class="playonlinux code">
POL_SetupWindow_textbox "Votre pseudo :" "$TITLE"
</pre>

=== POL_SetupWindow_textbox_multiline ===

'''Arguments:'''

# Message.
# Title (often $TITLE).
# 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:'''
<pre class="playonlinux code">
POL_SetupWindow_textbox_multiline "Enter a description for the program" "$TITLE"
</pre>

=== POL_SetupWindow_browse ===

'''Arguments:'''

# Message.
# Title (often $TITLE).
# 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:'''
<pre class="playonlinux code">
POL_SetupWindow_browse "Please select the program." "$TITLE"
</pre>

=== POL_SetupWindow_question ===

'''Arguments:'''

# Message.
# 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:'''
<pre class="playonlinux code">
POL_SetupWindow_question "Message" "Title"
</pre>

=== POL_SetupWindow_menu ===

'''Arguments:'''

# Message.
# Title (often $TITLE).
# Available choices.
# 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:'''
<pre class="playonlinux code">
POL_SetupWindow_menu "What's your favorite color?" "$TITLE" "Red~Green~Blue" "~"
</pre>

=== POL_SetupWindow_menu_num ===

'''Arguments:'''

# Message.
# Title (often $TITLE).
# Available choices.
# 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:'''
<pre class="playonlinux code">
POL_SetupWindow_menu_num "What's your favorite color?" "$TITLE" "Red~Green~Blue" "~"
</pre>

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

=== POL_SetupWindow_menu_list ===

'''Arguments:'''

# Message.
# Title (often $TITLE).
# Available choices.
# Separator character (often ~ or -).
# 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:'''
<pre class="playonlinux code">
POL_SetupWindow_menu_list "What's your favorite color?" "$TITLE" "Red~Green~Blue" "~"
</pre>

=== POL_SetupWindow_checkbox_list ===

'''Arguments:'''

# Message.
# Title (often $TITLE).
# Available choices.
# 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:'''
<pre class="playonlinux code">
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
</pre>

=== 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:'''
<pre class="playonlinux code">
POL_SetupWindow_cdrom
</pre>

=== POL_SetupWindow_check_cdrom ===

'''Arguments:'''

# 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:'''
<pre class="playonlinux code">
POL_SetupWindow_check_cdrom "Data/32_icon.ico"
</pre>

=== POL_SetupWindow_InstallMethod ===

'''Arguments:'''

# 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:'''
<pre class="playonlinux code">
POL_SetupWindow_InstallMethod "LOCAL,CD,STEAM"
</pre>

== POL_RequiredVersion (4.0.15+) ==

'''Arguments:'''

# 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, it itself only appeared in PlayOnLinux 4.0.15, and PlayOnLinux 4.0.14 is still the default in some distributions; 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_AdvisedVersion (4.0.15+) ==

'''Arguments:'''

# 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 ==

'''Arguments:'''

# Executable filename.
# Launcher name (often $TITLE).
# Optional name of the icon to download from PlayOnLinux website.
# Optional executable arguments.
# 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 [http://linux.die.net/man/7/glob 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 [http://standards.freedesktop.org/menu-spec/latest/apa.html main] and [http://standards.freedesktop.org/menu-spec/latest/apas02.html 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:'''
<pre class="playonlinux code">
POL_Shortcut "firefox.exe" "$TITLE"
</pre>

== POL_Shortcut_InsertBeforeWine ==

'''Arguments:'''

# Launcher name (often $TITLE).
# Command to add.

'''Description:'''

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

'''Example:'''
<pre class="playonlinux code">
POL_Shortcut_InsertBeforeWine "Jedi Knight II" "export __GL_ExtensionStringVersion=17700"
</pre>

== POL_Shortcut_Document ==
'''Arguments:'''
# Launcher name (often $TITLE).
# 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:'''

# URL to open.

'''Description:'''

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

'''Example:'''
<pre class="playonlinux code">
POL_Browser "http://www.playonlinux.com"
</pre>

== POL_Download ==

'''Arguments:'''

# URL to download.
# (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 ==

'''Arguments:'''

# URL to download.
# Expected MD5 digest of the downloaded file
# (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 ==

'''Arguments:'''

# 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:'''
<pre class="playonlinux code">
POL_System_TmpCreate "$PREFIX"
</pre>

== POL_System_TmpDelete ==

'''Description:'''

Removes the script's temporary directory.

'''Example:'''
<pre class="playonlinux code">
POL_System_TmpDelete
</pre>

== POL_System_SetArch ==

'''Arguments:'''

# 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:'''
<pre class="playonlinux code">
POL_System_SetArch "auto"
</pre>

== POL_Call ==

'''Arguments:'''

# Function name.
# 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|Components and Functions]]).

'''Prerequisite:'''

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

'''Example:'''
<pre class="playonlinux code">
POL_Call POL_Install_vcrun6
</pre>

== Wine-related functions ==

=== POL_Wine_SelectPrefix ===

'''Arguments:'''

# 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:'''
<pre class="playonlinux code">
POL_Wine_SelectPrefix "$PREFIX"
</pre>

=== POL_Wine_PrefixExists ===

'''Arguments:'''

# 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:'''
<pre class="playonlinux code">
if [ "$(POL_Wine_PrefixExists "$PREFIX")" = "False" ]
then
# The préfixe doesn't exist
fi
</pre>

=== POL_Wine_PrefixCreate ===

'''Arguments:'''

# 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:'''
<pre class="playonlinux code">
POL_Wine_PrefixCreate "1.3.4"
</pre>

=== 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:'''

# 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:'''
<pre class="playonlinux code">
POL_SetupWindow_VMS "128"
</pre>

=== Set_OS ===

'''Arguments:'''

# Windows version to emulate.
# 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:'''
<pre class="playonlinux code">
Set_OS "win2k"
</pre>

=== Set_Managed ===

'''Arguments:'''

# 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:'''
<pre class="playonlinux code">
Set_Managed "Off"
</pre>

=== Set_SoundDriver ===

'''Arguments:'''

# alsa/oss/esd.

'''Description:'''

Set the audio driver Wine will use.

{{Info|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:'''
<pre class="playonlinux code">
Set_SoundDriver "alsa"
</pre>

=== POL_Wine_Direct3D ===

'''Arguments:'''

# Setting to create/modify.
# New setting value.

'''Description:'''

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

'''Allowed values:'''

See [http://wiki.winehq.org/UsefulRegistryKeys WineHQ's Wiki].

'''Prerequisite:'''

The commands POL_Wine_SelectPrefix and POL_Wine_PrefixCreate must have been used beforehand.

'''Example:'''
<pre class="playonlinux code">
POL_Wine_Direct3D "UseGLSL" "disabled"
</pre>

=== POL_Wine_X11Drv ===

'''Arguments:'''

# Setting to create/modify.
# New setting value.

'''Description:'''

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

'''Allowed values:'''

See [http://wiki.winehq.org/UsefulRegistryKeys WineHQ's Wiki].

'''Prerequisite:'''

The commands POL_Wine_SelectPrefix and POL_Wine_PrefixCreate must have been used beforehand.

'''Example:'''
<pre class="playonlinux code">
POL_Wine_X11Drv "DXGrab" "Y"
</pre>

=== POL_Wine_DirectSound ===

'''Arguments:'''

# Setting to create/modify.
# New setting value.

'''Description:'''

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

'''Allowed values:'''

See [http://wiki.winehq.org/UsefulRegistryKeys WineHQ's Wiki].

'''Prerequisite:'''

The commands POL_Wine_SelectPrefix and POL_Wine_PrefixCreate must have been used beforehand.

'''Example:'''
<pre class="playonlinux code">
POL_Wine_DirectSound "HardwareAcceleration" "Emulation"
</pre>

=== POL_Wine_DirectInput ===

'''Arguments:'''

# Setting to create/modify.
# New setting value.

'''Description:'''

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

'''Allowed values:'''

See [http://wiki.winehq.org/UsefulRegistryKeys WineHQ's Wiki].

'''Prerequisite:'''

The commands POL_Wine_SelectPrefix and POL_Wine_PrefixCreate must have been used beforehand.

'''Example:'''
<pre class="playonlinux code">
POL_Wine_DirectInput "MouseWarpOverride" "force"
</pre>

=== POL_Wine_GetRegValue ===

'''Arguments:'''

# 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:'''
<pre class="playonlinux code">
VALUE="$(POL_Wine_GetRegValue "MouseWarpOverride")"
</pre>

=== Set_Desktop ===

'''Arguments:'''

# On/Off.
# Virtual desktop width (if it is enabled).
# 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:'''
<pre class="playonlinux code">
Set_Desktop "On" "1024" "768"
</pre>

=== Set_WineWindowTitle ===

'''Arguments:'''

# 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:'''
<pre class="playonlinux code">
Set_WineWindowTitle "$TITLE"
</pre>

=== 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:'''
<pre class="playonlinux code">
POL_Wine_InstallFonts
</pre>

=== 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:'''
<pre class="playonlinux code">
POL_Wine_SetVideoDriver
</pre>

=== POL_Wine_OverrideDLL ===

'''Arguments:'''

# Mode of override.
# 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:'''
<pre class="playonlinux code">
POL_Wine_OverrideDLL "native" "msvcrt"
POL_Wine_OverrideDLL "" "msvcrt" # To disable the DLL
</pre>

=== POL_Wine_OverrideDLL_App ===

'''Arguments:'''

# Executable name.
# Mode of override.
# 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:'''
<pre class="playonlinux code">
POL_Wine_OverrideDLL_App "firefox.exe" "native" "msvcrt"
POL_Wine_OverrideDLL_App "firefox.exe" "" "msvcrt" # To disable the DLL
</pre>

=== POL_Wine_WaitBefore ===

'''Arguments:'''

# 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:'''

# 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:'''
<pre class="playonlinux code">
POL_Wine_WaitExit "$TITLE"
</pre>

=== POL_Wine_reboot ===

'''Description:'''

Emulate a Windows reboot.

'''Prerequisite:'''

The commands POL_Wine_SelectPrefix and POL_Wine_PrefixCreate must have been used beforehand.

'''Example:'''
<pre class="playonlinux code">
POL_Wine_reboot
</pre>

== Debugging commands ==

=== POL_Debug_Init ===

'''Description:'''

Start debugging system.

'''Example:'''
<pre class="playonlinux code">
POL_Debug_Init
</pre>

=== POL_Debug_Message ===

'''Arguments:'''

# 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:'''
<pre class="playonlinux code">
POL_Debug_Message "Modifying config.cfg file."
</pre>

=== POL_Debug_Warning ===

'''Arguments:'''

# 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:'''
<pre class="playonlinux code">
POL_Debug_Warning "File config.cfg did not exist, creating one."
</pre>

=== POL_Debug_Error ===

'''Arguments:'''

# 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:'''
<pre class="playonlinux code">
POL_Debug_Error "Error while modifying config.cfg file"
</pre>

=== POL_Debug_Fatal ===

'''Arguments:'''

# Message.

'''Description:'''

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

'''Prerequisite:'''

The command POL_Debug_Init must have been used beforehand.

'''Example:'''
<pre class="playonlinux code">
POL_Debug_Fatal "Error while modifying config.cfg file"
</pre>

'''Previous:''' [[Scripting - Chapter 10: Script Translation|Chapter 10: Script Translation]]

[[Category:Scripting]]

Scripting - Chapter 11: List of Functions

2015-03-29T10:34:31Z

Petch: /* POL_RequiredVersion (4.0.15+) */ Fix example

== 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:'''

# URL of top image.
# URL of left image.
# 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:'''
<pre class="playonlinux code">
POL_GetSetupImages "http://files.playonlinux.com/resources/setups/AC2/top.jpg" "http://files.playonlinux.com/resources/setups/AC2/left.jpg" "$TITLE"
</pre>

=== POL_SetupWindow_Init ===

'''Description:'''

Opens the installation wizard window.

'''Example:'''
<pre class="playonlinux code">
POL_SetupWindow_Init
</pre>

=== POL_SetupWindow_Close ===

'''Description:'''

Closes the installation wizard window.

'''Example:'''
<pre class="playonlinux code">
POL_SetupWindow_Close
</pre>

== PlayOnLinux graphical interface ==

{{Warning|All the functions below need the command POL_SetupWindow_Init to be executed beforehand.}}

=== POL_SetupWindow_presentation ===

'''Arguments:'''

# Software name (often $TITLE).
# Software publisher.
# Site of the publisher.
# Script author.
# Prefix name (usually $PREFIX).

'''Description:'''

Present the software.

'''Example:'''
<pre class="playonlinux code">
POL_SetupWindow_presentation "$TITLE" "Mozilla" "http://www.mozilla.com" "SuperPlumus and NSLW" "$PREFIX"
</pre>

=== POL_SetupWindow_free_presentation ===

'''Arguments:'''

# Software name (often $TITLE).
# Message.

'''Description:'''

Present the software with more freedom than POL_SetupWindow_presentation.

'''Example:'''
<pre class="playonlinux code">
POL_SetupWindow_free_presentation "$TITLE" "Welcome to Mozilla Firefox installation wizard."
</pre>

=== POL_SetupWindow_message ===

'''Arguments:'''

# Message.
# Title (often $TITLE).

'''Description:'''

Display a message.

'''Example:'''
<pre class="playonlinux code">
POL_SetupWindow_message "Hello world!" "$TITLE"
</pre>

=== check_one - POL_SetupWindow_missing ===

'''Arguments for check_one:'''

# Program that must be present.
# 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:'''
<pre class="playonlinux code">
check_one "p7zip" "p7zip"
POL_SetupWindow_missing
</pre>

=== POL_SetupWindow_file ===

'''Arguments:'''

# Message.
# Title (often $TITLE).
# File to display.

'''Description:'''

Display the content of a file.

'''Example:'''
<pre class="playonlinux code">
POL_SetupWindow_file "Changelog" "$TITLE" "$POL_System_TmpDir/changelog.txt"
</pre>

=== POL_SetupWindow_licence ===

'''Arguments:'''

# Message.
# Title (often $TITLE).
# File to display.

'''Description:'''

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

Useful for displaying licenses.

'''Example:'''
<pre class="playonlinux code">
POL_SetupWindow_licence "Licence:" "$TITLE" "$POL_System_TmpDir/licence.txt"
</pre>

=== POL_SetupWindow_pulsebar - POL_SetupWindow_pulse - POL_SetupWindow_set_text ===

'''Arguments for POL_SetupWindow_pulsebar:'''

# Message.
# Title (often $TITLE).

'''Arguments for POL_SetupWindow_pulse:'''

# Percentage.

'''Arguments for POL_SetupWindow_set_text:'''

# 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:'''
<pre class="playonlinux code">
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"
</pre>

=== POL_SetupWindow_wait ===

'''Arguments:'''

# Message.
# Title (often $TITLE).

'''Description:'''

Display an indeterminate progress bar.

'''Example:'''
<pre class="playonlinux code">
POL_SetupWindow_wait "Please wait" "$TITLE"
</pre>

=== POL_SetupWindow_textbox ===

'''Arguments:'''

# Message.
# Title (often $TITLE).
# 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:'''
<pre class="playonlinux code">
POL_SetupWindow_textbox "Votre pseudo :" "$TITLE"
</pre>

=== POL_SetupWindow_textbox_multiline ===

'''Arguments:'''

# Message.
# Title (often $TITLE).
# 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:'''
<pre class="playonlinux code">
POL_SetupWindow_textbox_multiline "Enter a description for the program" "$TITLE"
</pre>

=== POL_SetupWindow_browse ===

'''Arguments:'''

# Message.
# Title (often $TITLE).
# 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:'''
<pre class="playonlinux code">
POL_SetupWindow_browse "Please select the program." "$TITLE"
</pre>

=== POL_SetupWindow_question ===

'''Arguments:'''

# Message.
# 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:'''
<pre class="playonlinux code">
POL_SetupWindow_question "Message" "Title"
</pre>

=== POL_SetupWindow_menu ===

'''Arguments:'''

# Message.
# Title (often $TITLE).
# Available choices.
# 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:'''
<pre class="playonlinux code">
POL_SetupWindow_menu "What's your favorite color?" "$TITLE" "Red~Green~Blue" "~"
</pre>

=== POL_SetupWindow_menu_num ===

'''Arguments:'''

# Message.
# Title (often $TITLE).
# Available choices.
# 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:'''
<pre class="playonlinux code">
POL_SetupWindow_menu_num "What's your favorite color?" "$TITLE" "Red~Green~Blue" "~"
</pre>

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

=== POL_SetupWindow_menu_list ===

'''Arguments:'''

# Message.
# Title (often $TITLE).
# Available choices.
# Separator character (often ~ or -).
# 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:'''
<pre class="playonlinux code">
POL_SetupWindow_menu_list "What's your favorite color?" "$TITLE" "Red~Green~Blue" "~"
</pre>

=== POL_SetupWindow_checkbox_list ===

'''Arguments:'''

# Message.
# Title (often $TITLE).
# Available choices.
# 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:'''
<pre class="playonlinux code">
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
</pre>

=== 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:'''
<pre class="playonlinux code">
POL_SetupWindow_cdrom
</pre>

=== POL_SetupWindow_check_cdrom ===

'''Arguments:'''

# 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:'''
<pre class="playonlinux code">
POL_SetupWindow_check_cdrom "Data/32_icon.ico"
</pre>

=== POL_SetupWindow_InstallMethod ===

'''Arguments:'''

# 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:'''
<pre class="playonlinux code">
POL_SetupWindow_InstallMethod "LOCAL,CD,STEAM"
</pre>

== POL_RequiredVersion (4.0.15+) ==

'''Arguments:'''

# 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, it itself only appeared in PlayOnLinux 4.0.15, and PlayOnLinux 4.0.14 is still the default in some distributions; 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_AdvisedVersion (4.0.15+) ==

'''Arguments:'''

# 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:'''
VERSION=4.0.18
POL_AdvisedVersion $VERSION || POL_Debug_Message "$TITLE works better with $APPLICATION_TITLE $VERSION\nPlease update"

== POL_Shortcut ==

'''Arguments:'''

# Executable filename.
# Launcher name (often $TITLE).
# Optional name of the icon to download from PlayOnLinux website.
# Optional executable arguments.
# 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 [http://linux.die.net/man/7/glob 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 [http://standards.freedesktop.org/menu-spec/latest/apa.html main] and [http://standards.freedesktop.org/menu-spec/latest/apas02.html 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:'''
<pre class="playonlinux code">
POL_Shortcut "firefox.exe" "$TITLE"
</pre>

== POL_Shortcut_InsertBeforeWine ==

'''Arguments:'''

# Launcher name (often $TITLE).
# Command to add.

'''Description:'''

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

'''Example:'''
<pre class="playonlinux code">
POL_Shortcut_InsertBeforeWine "Jedi Knight II" "export __GL_ExtensionStringVersion=17700"
</pre>

== POL_Shortcut_Document ==
'''Arguments:'''
# Launcher name (often $TITLE).
# 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:'''

# URL to open.

'''Description:'''

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

'''Example:'''
<pre class="playonlinux code">
POL_Browser "http://www.playonlinux.com"
</pre>

== POL_Download ==

'''Arguments:'''

# URL to download.
# (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 ==

'''Arguments:'''

# URL to download.
# Expected MD5 digest of the downloaded file
# (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 ==

'''Arguments:'''

# 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:'''
<pre class="playonlinux code">
POL_System_TmpCreate "$PREFIX"
</pre>

== POL_System_TmpDelete ==

'''Description:'''

Removes the script's temporary directory.

'''Example:'''
<pre class="playonlinux code">
POL_System_TmpDelete
</pre>

== POL_System_SetArch ==

'''Arguments:'''

# 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:'''
<pre class="playonlinux code">
POL_System_SetArch "auto"
</pre>

== POL_Call ==

'''Arguments:'''

# Function name.
# 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|Components and Functions]]).

'''Prerequisite:'''

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

'''Example:'''
<pre class="playonlinux code">
POL_Call POL_Install_vcrun6
</pre>

== Wine-related functions ==

=== POL_Wine_SelectPrefix ===

'''Arguments:'''

# 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:'''
<pre class="playonlinux code">
POL_Wine_SelectPrefix "$PREFIX"
</pre>

=== POL_Wine_PrefixExists ===

'''Arguments:'''

# 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:'''
<pre class="playonlinux code">
if [ "$(POL_Wine_PrefixExists "$PREFIX")" = "False" ]
then
# The préfixe doesn't exist
fi
</pre>

=== POL_Wine_PrefixCreate ===

'''Arguments:'''

# 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:'''
<pre class="playonlinux code">
POL_Wine_PrefixCreate "1.3.4"
</pre>

=== 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:'''

# 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:'''
<pre class="playonlinux code">
POL_SetupWindow_VMS "128"
</pre>

=== Set_OS ===

'''Arguments:'''

# Windows version to emulate.
# 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:'''
<pre class="playonlinux code">
Set_OS "win2k"
</pre>

=== Set_Managed ===

'''Arguments:'''

# 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:'''
<pre class="playonlinux code">
Set_Managed "Off"
</pre>

=== Set_SoundDriver ===

'''Arguments:'''

# alsa/oss/esd.

'''Description:'''

Set the audio driver Wine will use.

{{Info|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:'''
<pre class="playonlinux code">
Set_SoundDriver "alsa"
</pre>

=== POL_Wine_Direct3D ===

'''Arguments:'''

# Setting to create/modify.
# New setting value.

'''Description:'''

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

'''Allowed values:'''

See [http://wiki.winehq.org/UsefulRegistryKeys WineHQ's Wiki].

'''Prerequisite:'''

The commands POL_Wine_SelectPrefix and POL_Wine_PrefixCreate must have been used beforehand.

'''Example:'''
<pre class="playonlinux code">
POL_Wine_Direct3D "UseGLSL" "disabled"
</pre>

=== POL_Wine_X11Drv ===

'''Arguments:'''

# Setting to create/modify.
# New setting value.

'''Description:'''

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

'''Allowed values:'''

See [http://wiki.winehq.org/UsefulRegistryKeys WineHQ's Wiki].

'''Prerequisite:'''

The commands POL_Wine_SelectPrefix and POL_Wine_PrefixCreate must have been used beforehand.

'''Example:'''
<pre class="playonlinux code">
POL_Wine_X11Drv "DXGrab" "Y"
</pre>

=== POL_Wine_DirectSound ===

'''Arguments:'''

# Setting to create/modify.
# New setting value.

'''Description:'''

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

'''Allowed values:'''

See [http://wiki.winehq.org/UsefulRegistryKeys WineHQ's Wiki].

'''Prerequisite:'''

The commands POL_Wine_SelectPrefix and POL_Wine_PrefixCreate must have been used beforehand.

'''Example:'''
<pre class="playonlinux code">
POL_Wine_DirectSound "HardwareAcceleration" "Emulation"
</pre>

=== POL_Wine_DirectInput ===

'''Arguments:'''

# Setting to create/modify.
# New setting value.

'''Description:'''

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

'''Allowed values:'''

See [http://wiki.winehq.org/UsefulRegistryKeys WineHQ's Wiki].

'''Prerequisite:'''

The commands POL_Wine_SelectPrefix and POL_Wine_PrefixCreate must have been used beforehand.

'''Example:'''
<pre class="playonlinux code">
POL_Wine_DirectInput "MouseWarpOverride" "force"
</pre>

=== POL_Wine_GetRegValue ===

'''Arguments:'''

# 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:'''
<pre class="playonlinux code">
VALUE="$(POL_Wine_GetRegValue "MouseWarpOverride")"
</pre>

=== Set_Desktop ===

'''Arguments:'''

# On/Off.
# Virtual desktop width (if it is enabled).
# 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:'''
<pre class="playonlinux code">
Set_Desktop "On" "1024" "768"
</pre>

=== Set_WineWindowTitle ===

'''Arguments:'''

# 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:'''
<pre class="playonlinux code">
Set_WineWindowTitle "$TITLE"
</pre>

=== 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:'''
<pre class="playonlinux code">
POL_Wine_InstallFonts
</pre>

=== 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:'''
<pre class="playonlinux code">
POL_Wine_SetVideoDriver
</pre>

=== POL_Wine_OverrideDLL ===

'''Arguments:'''

# Mode of override.
# 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:'''
<pre class="playonlinux code">
POL_Wine_OverrideDLL "native" "msvcrt"
POL_Wine_OverrideDLL "" "msvcrt" # To disable the DLL
</pre>

=== POL_Wine_OverrideDLL_App ===

'''Arguments:'''

# Executable name.
# Mode of override.
# 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:'''
<pre class="playonlinux code">
POL_Wine_OverrideDLL_App "firefox.exe" "native" "msvcrt"
POL_Wine_OverrideDLL_App "firefox.exe" "" "msvcrt" # To disable the DLL
</pre>

=== POL_Wine_WaitBefore ===

'''Arguments:'''

# 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:'''

# 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:'''
<pre class="playonlinux code">
POL_Wine_WaitExit "$TITLE"
</pre>

=== POL_Wine_reboot ===

'''Description:'''

Emulate a Windows reboot.

'''Prerequisite:'''

The commands POL_Wine_SelectPrefix and POL_Wine_PrefixCreate must have been used beforehand.

'''Example:'''
<pre class="playonlinux code">
POL_Wine_reboot
</pre>

== Debugging commands ==

=== POL_Debug_Init ===

'''Description:'''

Start debugging system.

'''Example:'''
<pre class="playonlinux code">
POL_Debug_Init
</pre>

=== POL_Debug_Message ===

'''Arguments:'''

# 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:'''
<pre class="playonlinux code">
POL_Debug_Message "Modifying config.cfg file."
</pre>

=== POL_Debug_Warning ===

'''Arguments:'''

# 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:'''
<pre class="playonlinux code">
POL_Debug_Warning "File config.cfg did not exist, creating one."
</pre>

=== POL_Debug_Error ===

'''Arguments:'''

# 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:'''
<pre class="playonlinux code">
POL_Debug_Error "Error while modifying config.cfg file"
</pre>

=== POL_Debug_Fatal ===

'''Arguments:'''

# Message.

'''Description:'''

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

'''Prerequisite:'''

The command POL_Debug_Init must have been used beforehand.

'''Example:'''
<pre class="playonlinux code">
POL_Debug_Fatal "Error while modifying config.cfg file"
</pre>

'''Previous:''' [[Scripting - Chapter 10: Script Translation|Chapter 10: Script Translation]]

[[Category:Scripting]]

Scripting - Chapter 11: List of Functions

2015-03-29T10:32:31Z

Petch: /* POL_RequiredVersion (4.0.15+) */ Document POL_AdvisedVersion

== 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:'''

# URL of top image.
# URL of left image.
# 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:'''
<pre class="playonlinux code">
POL_GetSetupImages "http://files.playonlinux.com/resources/setups/AC2/top.jpg" "http://files.playonlinux.com/resources/setups/AC2/left.jpg" "$TITLE"
</pre>

=== POL_SetupWindow_Init ===

'''Description:'''

Opens the installation wizard window.

'''Example:'''
<pre class="playonlinux code">
POL_SetupWindow_Init
</pre>

=== POL_SetupWindow_Close ===

'''Description:'''

Closes the installation wizard window.

'''Example:'''
<pre class="playonlinux code">
POL_SetupWindow_Close
</pre>

== PlayOnLinux graphical interface ==

{{Warning|All the functions below need the command POL_SetupWindow_Init to be executed beforehand.}}

=== POL_SetupWindow_presentation ===

'''Arguments:'''

# Software name (often $TITLE).
# Software publisher.
# Site of the publisher.
# Script author.
# Prefix name (usually $PREFIX).

'''Description:'''

Present the software.

'''Example:'''
<pre class="playonlinux code">
POL_SetupWindow_presentation "$TITLE" "Mozilla" "http://www.mozilla.com" "SuperPlumus and NSLW" "$PREFIX"
</pre>

=== POL_SetupWindow_free_presentation ===

'''Arguments:'''

# Software name (often $TITLE).
# Message.

'''Description:'''

Present the software with more freedom than POL_SetupWindow_presentation.

'''Example:'''
<pre class="playonlinux code">
POL_SetupWindow_free_presentation "$TITLE" "Welcome to Mozilla Firefox installation wizard."
</pre>

=== POL_SetupWindow_message ===

'''Arguments:'''

# Message.
# Title (often $TITLE).

'''Description:'''

Display a message.

'''Example:'''
<pre class="playonlinux code">
POL_SetupWindow_message "Hello world!" "$TITLE"
</pre>

=== check_one - POL_SetupWindow_missing ===

'''Arguments for check_one:'''

# Program that must be present.
# 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:'''
<pre class="playonlinux code">
check_one "p7zip" "p7zip"
POL_SetupWindow_missing
</pre>

=== POL_SetupWindow_file ===

'''Arguments:'''

# Message.
# Title (often $TITLE).
# File to display.

'''Description:'''

Display the content of a file.

'''Example:'''
<pre class="playonlinux code">
POL_SetupWindow_file "Changelog" "$TITLE" "$POL_System_TmpDir/changelog.txt"
</pre>

=== POL_SetupWindow_licence ===

'''Arguments:'''

# Message.
# Title (often $TITLE).
# File to display.

'''Description:'''

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

Useful for displaying licenses.

'''Example:'''
<pre class="playonlinux code">
POL_SetupWindow_licence "Licence:" "$TITLE" "$POL_System_TmpDir/licence.txt"
</pre>

=== POL_SetupWindow_pulsebar - POL_SetupWindow_pulse - POL_SetupWindow_set_text ===

'''Arguments for POL_SetupWindow_pulsebar:'''

# Message.
# Title (often $TITLE).

'''Arguments for POL_SetupWindow_pulse:'''

# Percentage.

'''Arguments for POL_SetupWindow_set_text:'''

# 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:'''
<pre class="playonlinux code">
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"
</pre>

=== POL_SetupWindow_wait ===

'''Arguments:'''

# Message.
# Title (often $TITLE).

'''Description:'''

Display an indeterminate progress bar.

'''Example:'''
<pre class="playonlinux code">
POL_SetupWindow_wait "Please wait" "$TITLE"
</pre>

=== POL_SetupWindow_textbox ===

'''Arguments:'''

# Message.
# Title (often $TITLE).
# 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:'''
<pre class="playonlinux code">
POL_SetupWindow_textbox "Votre pseudo :" "$TITLE"
</pre>

=== POL_SetupWindow_textbox_multiline ===

'''Arguments:'''

# Message.
# Title (often $TITLE).
# 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:'''
<pre class="playonlinux code">
POL_SetupWindow_textbox_multiline "Enter a description for the program" "$TITLE"
</pre>

=== POL_SetupWindow_browse ===

'''Arguments:'''

# Message.
# Title (often $TITLE).
# 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:'''
<pre class="playonlinux code">
POL_SetupWindow_browse "Please select the program." "$TITLE"
</pre>

=== POL_SetupWindow_question ===

'''Arguments:'''

# Message.
# 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:'''
<pre class="playonlinux code">
POL_SetupWindow_question "Message" "Title"
</pre>

=== POL_SetupWindow_menu ===

'''Arguments:'''

# Message.
# Title (often $TITLE).
# Available choices.
# 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:'''
<pre class="playonlinux code">
POL_SetupWindow_menu "What's your favorite color?" "$TITLE" "Red~Green~Blue" "~"
</pre>

=== POL_SetupWindow_menu_num ===

'''Arguments:'''

# Message.
# Title (often $TITLE).
# Available choices.
# 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:'''
<pre class="playonlinux code">
POL_SetupWindow_menu_num "What's your favorite color?" "$TITLE" "Red~Green~Blue" "~"
</pre>

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

=== POL_SetupWindow_menu_list ===

'''Arguments:'''

# Message.
# Title (often $TITLE).
# Available choices.
# Separator character (often ~ or -).
# 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:'''
<pre class="playonlinux code">
POL_SetupWindow_menu_list "What's your favorite color?" "$TITLE" "Red~Green~Blue" "~"
</pre>

=== POL_SetupWindow_checkbox_list ===

'''Arguments:'''

# Message.
# Title (often $TITLE).
# Available choices.
# 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:'''
<pre class="playonlinux code">
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
</pre>

=== 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:'''
<pre class="playonlinux code">
POL_SetupWindow_cdrom
</pre>

=== POL_SetupWindow_check_cdrom ===

'''Arguments:'''

# 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:'''
<pre class="playonlinux code">
POL_SetupWindow_check_cdrom "Data/32_icon.ico"
</pre>

=== POL_SetupWindow_InstallMethod ===

'''Arguments:'''

# 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:'''
<pre class="playonlinux code">
POL_SetupWindow_InstallMethod "LOCAL,CD,STEAM"
</pre>

== POL_RequiredVersion (4.0.15+) ==

'''Arguments:'''

# 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, it itself only appeared in PlayOnLinux 4.0.15, and PlayOnLinux 4.0.14 is still the default in some distributions; 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:'''
VERSION=4.0.18
POL_RequiredVersion $VERSION || POL_Debug_Fatal "$TITLE won't work with $APPLICATION_TITLE $VERSION\nPlease update"

== POL_AdvisedVersion (4.0.15+) ==

'''Arguments:'''

# 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:'''
VERSION=4.0.18
POL_AdvisedVersion $VERSION || POL_Debug_Message "$TITLE works better with $APPLICATION_TITLE $VERSION\nPlease update"

== POL_Shortcut ==

'''Arguments:'''

# Executable filename.
# Launcher name (often $TITLE).
# Optional name of the icon to download from PlayOnLinux website.
# Optional executable arguments.
# 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 [http://linux.die.net/man/7/glob 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 [http://standards.freedesktop.org/menu-spec/latest/apa.html main] and [http://standards.freedesktop.org/menu-spec/latest/apas02.html 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:'''
<pre class="playonlinux code">
POL_Shortcut "firefox.exe" "$TITLE"
</pre>

== POL_Shortcut_InsertBeforeWine ==

'''Arguments:'''

# Launcher name (often $TITLE).
# Command to add.

'''Description:'''

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

'''Example:'''
<pre class="playonlinux code">
POL_Shortcut_InsertBeforeWine "Jedi Knight II" "export __GL_ExtensionStringVersion=17700"
</pre>

== POL_Shortcut_Document ==
'''Arguments:'''
# Launcher name (often $TITLE).
# 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:'''

# URL to open.

'''Description:'''

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

'''Example:'''
<pre class="playonlinux code">
POL_Browser "http://www.playonlinux.com"
</pre>

== POL_Download ==

'''Arguments:'''

# URL to download.
# (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 ==

'''Arguments:'''

# URL to download.
# Expected MD5 digest of the downloaded file
# (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 ==

'''Arguments:'''

# 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:'''
<pre class="playonlinux code">
POL_System_TmpCreate "$PREFIX"
</pre>

== POL_System_TmpDelete ==

'''Description:'''

Removes the script's temporary directory.

'''Example:'''
<pre class="playonlinux code">
POL_System_TmpDelete
</pre>

== POL_System_SetArch ==

'''Arguments:'''

# 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:'''
<pre class="playonlinux code">
POL_System_SetArch "auto"
</pre>

== POL_Call ==

'''Arguments:'''

# Function name.
# 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|Components and Functions]]).

'''Prerequisite:'''

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

'''Example:'''
<pre class="playonlinux code">
POL_Call POL_Install_vcrun6
</pre>

== Wine-related functions ==

=== POL_Wine_SelectPrefix ===

'''Arguments:'''

# 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:'''
<pre class="playonlinux code">
POL_Wine_SelectPrefix "$PREFIX"
</pre>

=== POL_Wine_PrefixExists ===

'''Arguments:'''

# 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:'''
<pre class="playonlinux code">
if [ "$(POL_Wine_PrefixExists "$PREFIX")" = "False" ]
then
# The préfixe doesn't exist
fi
</pre>

=== POL_Wine_PrefixCreate ===

'''Arguments:'''

# 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:'''
<pre class="playonlinux code">
POL_Wine_PrefixCreate "1.3.4"
</pre>

=== 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:'''

# 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:'''
<pre class="playonlinux code">
POL_SetupWindow_VMS "128"
</pre>

=== Set_OS ===

'''Arguments:'''

# Windows version to emulate.
# 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:'''
<pre class="playonlinux code">
Set_OS "win2k"
</pre>

=== Set_Managed ===

'''Arguments:'''

# 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:'''
<pre class="playonlinux code">
Set_Managed "Off"
</pre>

=== Set_SoundDriver ===

'''Arguments:'''

# alsa/oss/esd.

'''Description:'''

Set the audio driver Wine will use.

{{Info|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:'''
<pre class="playonlinux code">
Set_SoundDriver "alsa"
</pre>

=== POL_Wine_Direct3D ===

'''Arguments:'''

# Setting to create/modify.
# New setting value.

'''Description:'''

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

'''Allowed values:'''

See [http://wiki.winehq.org/UsefulRegistryKeys WineHQ's Wiki].

'''Prerequisite:'''

The commands POL_Wine_SelectPrefix and POL_Wine_PrefixCreate must have been used beforehand.

'''Example:'''
<pre class="playonlinux code">
POL_Wine_Direct3D "UseGLSL" "disabled"
</pre>

=== POL_Wine_X11Drv ===

'''Arguments:'''

# Setting to create/modify.
# New setting value.

'''Description:'''

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

'''Allowed values:'''

See [http://wiki.winehq.org/UsefulRegistryKeys WineHQ's Wiki].

'''Prerequisite:'''

The commands POL_Wine_SelectPrefix and POL_Wine_PrefixCreate must have been used beforehand.

'''Example:'''
<pre class="playonlinux code">
POL_Wine_X11Drv "DXGrab" "Y"
</pre>

=== POL_Wine_DirectSound ===

'''Arguments:'''

# Setting to create/modify.
# New setting value.

'''Description:'''

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

'''Allowed values:'''

See [http://wiki.winehq.org/UsefulRegistryKeys WineHQ's Wiki].

'''Prerequisite:'''

The commands POL_Wine_SelectPrefix and POL_Wine_PrefixCreate must have been used beforehand.

'''Example:'''
<pre class="playonlinux code">
POL_Wine_DirectSound "HardwareAcceleration" "Emulation"
</pre>

=== POL_Wine_DirectInput ===

'''Arguments:'''

# Setting to create/modify.
# New setting value.

'''Description:'''

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

'''Allowed values:'''

See [http://wiki.winehq.org/UsefulRegistryKeys WineHQ's Wiki].

'''Prerequisite:'''

The commands POL_Wine_SelectPrefix and POL_Wine_PrefixCreate must have been used beforehand.

'''Example:'''
<pre class="playonlinux code">
POL_Wine_DirectInput "MouseWarpOverride" "force"
</pre>

=== POL_Wine_GetRegValue ===

'''Arguments:'''

# 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:'''
<pre class="playonlinux code">
VALUE="$(POL_Wine_GetRegValue "MouseWarpOverride")"
</pre>

=== Set_Desktop ===

'''Arguments:'''

# On/Off.
# Virtual desktop width (if it is enabled).
# 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:'''
<pre class="playonlinux code">
Set_Desktop "On" "1024" "768"
</pre>

=== Set_WineWindowTitle ===

'''Arguments:'''

# 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:'''
<pre class="playonlinux code">
Set_WineWindowTitle "$TITLE"
</pre>

=== 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:'''
<pre class="playonlinux code">
POL_Wine_InstallFonts
</pre>

=== 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:'''
<pre class="playonlinux code">
POL_Wine_SetVideoDriver
</pre>

=== POL_Wine_OverrideDLL ===

'''Arguments:'''

# Mode of override.
# 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:'''
<pre class="playonlinux code">
POL_Wine_OverrideDLL "native" "msvcrt"
POL_Wine_OverrideDLL "" "msvcrt" # To disable the DLL
</pre>

=== POL_Wine_OverrideDLL_App ===

'''Arguments:'''

# Executable name.
# Mode of override.
# 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:'''
<pre class="playonlinux code">
POL_Wine_OverrideDLL_App "firefox.exe" "native" "msvcrt"
POL_Wine_OverrideDLL_App "firefox.exe" "" "msvcrt" # To disable the DLL
</pre>

=== POL_Wine_WaitBefore ===

'''Arguments:'''

# 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:'''

# 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:'''
<pre class="playonlinux code">
POL_Wine_WaitExit "$TITLE"
</pre>

=== POL_Wine_reboot ===

'''Description:'''

Emulate a Windows reboot.

'''Prerequisite:'''

The commands POL_Wine_SelectPrefix and POL_Wine_PrefixCreate must have been used beforehand.

'''Example:'''
<pre class="playonlinux code">
POL_Wine_reboot
</pre>

== Debugging commands ==

=== POL_Debug_Init ===

'''Description:'''

Start debugging system.

'''Example:'''
<pre class="playonlinux code">
POL_Debug_Init
</pre>

=== POL_Debug_Message ===

'''Arguments:'''

# 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:'''
<pre class="playonlinux code">
POL_Debug_Message "Modifying config.cfg file."
</pre>

=== POL_Debug_Warning ===

'''Arguments:'''

# 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:'''
<pre class="playonlinux code">
POL_Debug_Warning "File config.cfg did not exist, creating one."
</pre>

=== POL_Debug_Error ===

'''Arguments:'''

# 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:'''
<pre class="playonlinux code">
POL_Debug_Error "Error while modifying config.cfg file"
</pre>

=== POL_Debug_Fatal ===

'''Arguments:'''

# Message.

'''Description:'''

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

'''Prerequisite:'''

The command POL_Debug_Init must have been used beforehand.

'''Example:'''
<pre class="playonlinux code">
POL_Debug_Fatal "Error while modifying config.cfg file"
</pre>

'''Previous:''' [[Scripting - Chapter 10: Script Translation|Chapter 10: Script Translation]]

[[Category:Scripting]]

Scripting - Chapter 11: List of Functions

2015-03-29T10:25:41Z

Petch: /* POL_Shortcut */ Add POL_RequiredVersion. For each statement the PoL version they appeared in should now be documented...

== 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:'''

# URL of top image.
# URL of left image.
# 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:'''
<pre class="playonlinux code">
POL_GetSetupImages "http://files.playonlinux.com/resources/setups/AC2/top.jpg" "http://files.playonlinux.com/resources/setups/AC2/left.jpg" "$TITLE"
</pre>

=== POL_SetupWindow_Init ===

'''Description:'''

Opens the installation wizard window.

'''Example:'''
<pre class="playonlinux code">
POL_SetupWindow_Init
</pre>

=== POL_SetupWindow_Close ===

'''Description:'''

Closes the installation wizard window.

'''Example:'''
<pre class="playonlinux code">
POL_SetupWindow_Close
</pre>

== PlayOnLinux graphical interface ==

{{Warning|All the functions below need the command POL_SetupWindow_Init to be executed beforehand.}}

=== POL_SetupWindow_presentation ===

'''Arguments:'''

# Software name (often $TITLE).
# Software publisher.
# Site of the publisher.
# Script author.
# Prefix name (usually $PREFIX).

'''Description:'''

Present the software.

'''Example:'''
<pre class="playonlinux code">
POL_SetupWindow_presentation "$TITLE" "Mozilla" "http://www.mozilla.com" "SuperPlumus and NSLW" "$PREFIX"
</pre>

=== POL_SetupWindow_free_presentation ===

'''Arguments:'''

# Software name (often $TITLE).
# Message.

'''Description:'''

Present the software with more freedom than POL_SetupWindow_presentation.

'''Example:'''
<pre class="playonlinux code">
POL_SetupWindow_free_presentation "$TITLE" "Welcome to Mozilla Firefox installation wizard."
</pre>

=== POL_SetupWindow_message ===

'''Arguments:'''

# Message.
# Title (often $TITLE).

'''Description:'''

Display a message.

'''Example:'''
<pre class="playonlinux code">
POL_SetupWindow_message "Hello world!" "$TITLE"
</pre>

=== check_one - POL_SetupWindow_missing ===

'''Arguments for check_one:'''

# Program that must be present.
# 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:'''
<pre class="playonlinux code">
check_one "p7zip" "p7zip"
POL_SetupWindow_missing
</pre>

=== POL_SetupWindow_file ===

'''Arguments:'''

# Message.
# Title (often $TITLE).
# File to display.

'''Description:'''

Display the content of a file.

'''Example:'''
<pre class="playonlinux code">
POL_SetupWindow_file "Changelog" "$TITLE" "$POL_System_TmpDir/changelog.txt"
</pre>

=== POL_SetupWindow_licence ===

'''Arguments:'''

# Message.
# Title (often $TITLE).
# File to display.

'''Description:'''

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

Useful for displaying licenses.

'''Example:'''
<pre class="playonlinux code">
POL_SetupWindow_licence "Licence:" "$TITLE" "$POL_System_TmpDir/licence.txt"
</pre>

=== POL_SetupWindow_pulsebar - POL_SetupWindow_pulse - POL_SetupWindow_set_text ===

'''Arguments for POL_SetupWindow_pulsebar:'''

# Message.
# Title (often $TITLE).

'''Arguments for POL_SetupWindow_pulse:'''

# Percentage.

'''Arguments for POL_SetupWindow_set_text:'''

# 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:'''
<pre class="playonlinux code">
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"
</pre>

=== POL_SetupWindow_wait ===

'''Arguments:'''

# Message.
# Title (often $TITLE).

'''Description:'''

Display an indeterminate progress bar.

'''Example:'''
<pre class="playonlinux code">
POL_SetupWindow_wait "Please wait" "$TITLE"
</pre>

=== POL_SetupWindow_textbox ===

'''Arguments:'''

# Message.
# Title (often $TITLE).
# 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:'''
<pre class="playonlinux code">
POL_SetupWindow_textbox "Votre pseudo :" "$TITLE"
</pre>

=== POL_SetupWindow_textbox_multiline ===

'''Arguments:'''

# Message.
# Title (often $TITLE).
# 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:'''
<pre class="playonlinux code">
POL_SetupWindow_textbox_multiline "Enter a description for the program" "$TITLE"
</pre>

=== POL_SetupWindow_browse ===

'''Arguments:'''

# Message.
# Title (often $TITLE).
# 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:'''
<pre class="playonlinux code">
POL_SetupWindow_browse "Please select the program." "$TITLE"
</pre>

=== POL_SetupWindow_question ===

'''Arguments:'''

# Message.
# 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:'''
<pre class="playonlinux code">
POL_SetupWindow_question "Message" "Title"
</pre>

=== POL_SetupWindow_menu ===

'''Arguments:'''

# Message.
# Title (often $TITLE).
# Available choices.
# 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:'''
<pre class="playonlinux code">
POL_SetupWindow_menu "What's your favorite color?" "$TITLE" "Red~Green~Blue" "~"
</pre>

=== POL_SetupWindow_menu_num ===

'''Arguments:'''

# Message.
# Title (often $TITLE).
# Available choices.
# 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:'''
<pre class="playonlinux code">
POL_SetupWindow_menu_num "What's your favorite color?" "$TITLE" "Red~Green~Blue" "~"
</pre>

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

=== POL_SetupWindow_menu_list ===

'''Arguments:'''

# Message.
# Title (often $TITLE).
# Available choices.
# Separator character (often ~ or -).
# 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:'''
<pre class="playonlinux code">
POL_SetupWindow_menu_list "What's your favorite color?" "$TITLE" "Red~Green~Blue" "~"
</pre>

=== POL_SetupWindow_checkbox_list ===

'''Arguments:'''

# Message.
# Title (often $TITLE).
# Available choices.
# 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:'''
<pre class="playonlinux code">
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
</pre>

=== 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:'''
<pre class="playonlinux code">
POL_SetupWindow_cdrom
</pre>

=== POL_SetupWindow_check_cdrom ===

'''Arguments:'''

# 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:'''
<pre class="playonlinux code">
POL_SetupWindow_check_cdrom "Data/32_icon.ico"
</pre>

=== POL_SetupWindow_InstallMethod ===

'''Arguments:'''

# 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:'''
<pre class="playonlinux code">
POL_SetupWindow_InstallMethod "LOCAL,CD,STEAM"
</pre>

== POL_RequiredVersion (4.0.15+) ==

'''Arguments:'''

# 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, it itself only appeared in PlayOnLinux 4.0.15, and PlayOnLinux 4.0.14 is still the default in some distributions; 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_Shortcut ==

'''Arguments:'''

# Executable filename.
# Launcher name (often $TITLE).
# Optional name of the icon to download from PlayOnLinux website.
# Optional executable arguments.
# 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 [http://linux.die.net/man/7/glob 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 [http://standards.freedesktop.org/menu-spec/latest/apa.html main] and [http://standards.freedesktop.org/menu-spec/latest/apas02.html 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:'''
<pre class="playonlinux code">
POL_Shortcut "firefox.exe" "$TITLE"
</pre>

== POL_Shortcut_InsertBeforeWine ==

'''Arguments:'''

# Launcher name (often $TITLE).
# Command to add.

'''Description:'''

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

'''Example:'''
<pre class="playonlinux code">
POL_Shortcut_InsertBeforeWine "Jedi Knight II" "export __GL_ExtensionStringVersion=17700"
</pre>

== POL_Shortcut_Document ==
'''Arguments:'''
# Launcher name (often $TITLE).
# 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:'''

# URL to open.

'''Description:'''

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

'''Example:'''
<pre class="playonlinux code">
POL_Browser "http://www.playonlinux.com"
</pre>

== POL_Download ==

'''Arguments:'''

# URL to download.
# (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 ==

'''Arguments:'''

# URL to download.
# Expected MD5 digest of the downloaded file
# (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 ==

'''Arguments:'''

# 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:'''
<pre class="playonlinux code">
POL_System_TmpCreate "$PREFIX"
</pre>

== POL_System_TmpDelete ==

'''Description:'''

Removes the script's temporary directory.

'''Example:'''
<pre class="playonlinux code">
POL_System_TmpDelete
</pre>

== POL_System_SetArch ==

'''Arguments:'''

# 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:'''
<pre class="playonlinux code">
POL_System_SetArch "auto"
</pre>

== POL_Call ==

'''Arguments:'''

# Function name.
# 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|Components and Functions]]).

'''Prerequisite:'''

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

'''Example:'''
<pre class="playonlinux code">
POL_Call POL_Install_vcrun6
</pre>

== Wine-related functions ==

=== POL_Wine_SelectPrefix ===

'''Arguments:'''

# 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:'''
<pre class="playonlinux code">
POL_Wine_SelectPrefix "$PREFIX"
</pre>

=== POL_Wine_PrefixExists ===

'''Arguments:'''

# 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:'''
<pre class="playonlinux code">
if [ "$(POL_Wine_PrefixExists "$PREFIX")" = "False" ]
then
# The préfixe doesn't exist
fi
</pre>

=== POL_Wine_PrefixCreate ===

'''Arguments:'''

# 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:'''
<pre class="playonlinux code">
POL_Wine_PrefixCreate "1.3.4"
</pre>

=== 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:'''

# 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:'''
<pre class="playonlinux code">
POL_SetupWindow_VMS "128"
</pre>

=== Set_OS ===

'''Arguments:'''

# Windows version to emulate.
# 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:'''
<pre class="playonlinux code">
Set_OS "win2k"
</pre>

=== Set_Managed ===

'''Arguments:'''

# 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:'''
<pre class="playonlinux code">
Set_Managed "Off"
</pre>

=== Set_SoundDriver ===

'''Arguments:'''

# alsa/oss/esd.

'''Description:'''

Set the audio driver Wine will use.

{{Info|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:'''
<pre class="playonlinux code">
Set_SoundDriver "alsa"
</pre>

=== POL_Wine_Direct3D ===

'''Arguments:'''

# Setting to create/modify.
# New setting value.

'''Description:'''

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

'''Allowed values:'''

See [http://wiki.winehq.org/UsefulRegistryKeys WineHQ's Wiki].

'''Prerequisite:'''

The commands POL_Wine_SelectPrefix and POL_Wine_PrefixCreate must have been used beforehand.

'''Example:'''
<pre class="playonlinux code">
POL_Wine_Direct3D "UseGLSL" "disabled"
</pre>

=== POL_Wine_X11Drv ===

'''Arguments:'''

# Setting to create/modify.
# New setting value.

'''Description:'''

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

'''Allowed values:'''

See [http://wiki.winehq.org/UsefulRegistryKeys WineHQ's Wiki].

'''Prerequisite:'''

The commands POL_Wine_SelectPrefix and POL_Wine_PrefixCreate must have been used beforehand.

'''Example:'''
<pre class="playonlinux code">
POL_Wine_X11Drv "DXGrab" "Y"
</pre>

=== POL_Wine_DirectSound ===

'''Arguments:'''

# Setting to create/modify.
# New setting value.

'''Description:'''

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

'''Allowed values:'''

See [http://wiki.winehq.org/UsefulRegistryKeys WineHQ's Wiki].

'''Prerequisite:'''

The commands POL_Wine_SelectPrefix and POL_Wine_PrefixCreate must have been used beforehand.

'''Example:'''
<pre class="playonlinux code">
POL_Wine_DirectSound "HardwareAcceleration" "Emulation"
</pre>

=== POL_Wine_DirectInput ===

'''Arguments:'''

# Setting to create/modify.
# New setting value.

'''Description:'''

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

'''Allowed values:'''

See [http://wiki.winehq.org/UsefulRegistryKeys WineHQ's Wiki].

'''Prerequisite:'''

The commands POL_Wine_SelectPrefix and POL_Wine_PrefixCreate must have been used beforehand.

'''Example:'''
<pre class="playonlinux code">
POL_Wine_DirectInput "MouseWarpOverride" "force"
</pre>

=== POL_Wine_GetRegValue ===

'''Arguments:'''

# 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:'''
<pre class="playonlinux code">
VALUE="$(POL_Wine_GetRegValue "MouseWarpOverride")"
</pre>

=== Set_Desktop ===

'''Arguments:'''

# On/Off.
# Virtual desktop width (if it is enabled).
# 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:'''
<pre class="playonlinux code">
Set_Desktop "On" "1024" "768"
</pre>

=== Set_WineWindowTitle ===

'''Arguments:'''

# 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:'''
<pre class="playonlinux code">
Set_WineWindowTitle "$TITLE"
</pre>

=== 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:'''
<pre class="playonlinux code">
POL_Wine_InstallFonts
</pre>

=== 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:'''
<pre class="playonlinux code">
POL_Wine_SetVideoDriver
</pre>

=== POL_Wine_OverrideDLL ===

'''Arguments:'''

# Mode of override.
# 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:'''
<pre class="playonlinux code">
POL_Wine_OverrideDLL "native" "msvcrt"
POL_Wine_OverrideDLL "" "msvcrt" # To disable the DLL
</pre>

=== POL_Wine_OverrideDLL_App ===

'''Arguments:'''

# Executable name.
# Mode of override.
# 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:'''
<pre class="playonlinux code">
POL_Wine_OverrideDLL_App "firefox.exe" "native" "msvcrt"
POL_Wine_OverrideDLL_App "firefox.exe" "" "msvcrt" # To disable the DLL
</pre>

=== POL_Wine_WaitBefore ===

'''Arguments:'''

# 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:'''

# 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:'''
<pre class="playonlinux code">
POL_Wine_WaitExit "$TITLE"
</pre>

=== POL_Wine_reboot ===

'''Description:'''

Emulate a Windows reboot.

'''Prerequisite:'''

The commands POL_Wine_SelectPrefix and POL_Wine_PrefixCreate must have been used beforehand.

'''Example:'''
<pre class="playonlinux code">
POL_Wine_reboot
</pre>

== Debugging commands ==

=== POL_Debug_Init ===

'''Description:'''

Start debugging system.

'''Example:'''
<pre class="playonlinux code">
POL_Debug_Init
</pre>

=== POL_Debug_Message ===

'''Arguments:'''

# 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:'''
<pre class="playonlinux code">
POL_Debug_Message "Modifying config.cfg file."
</pre>

=== POL_Debug_Warning ===

'''Arguments:'''

# 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:'''
<pre class="playonlinux code">
POL_Debug_Warning "File config.cfg did not exist, creating one."
</pre>

=== POL_Debug_Error ===

'''Arguments:'''

# 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:'''
<pre class="playonlinux code">
POL_Debug_Error "Error while modifying config.cfg file"
</pre>

=== POL_Debug_Fatal ===

'''Arguments:'''

# Message.

'''Description:'''

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

'''Prerequisite:'''

The command POL_Debug_Init must have been used beforehand.

'''Example:'''
<pre class="playonlinux code">
POL_Debug_Fatal "Error while modifying config.cfg file"
</pre>

'''Previous:''' [[Scripting - Chapter 10: Script Translation|Chapter 10: Script Translation]]

[[Category:Scripting]]

Scripting - Chapter 11: List of Functions

2015-03-29T10:07:47Z

Petch: /* POL_Download */ Document POL_Download_Resource

== 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:'''

# URL of top image.
# URL of left image.
# 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:'''
<pre class="playonlinux code">
POL_GetSetupImages "http://files.playonlinux.com/resources/setups/AC2/top.jpg" "http://files.playonlinux.com/resources/setups/AC2/left.jpg" "$TITLE"
</pre>

=== POL_SetupWindow_Init ===

'''Description:'''

Opens the installation wizard window.

'''Example:'''
<pre class="playonlinux code">
POL_SetupWindow_Init
</pre>

=== POL_SetupWindow_Close ===

'''Description:'''

Closes the installation wizard window.

'''Example:'''
<pre class="playonlinux code">
POL_SetupWindow_Close
</pre>

== PlayOnLinux graphical interface ==

{{Warning|All the functions below need the command POL_SetupWindow_Init to be executed beforehand.}}

=== POL_SetupWindow_presentation ===

'''Arguments:'''

# Software name (often $TITLE).
# Software publisher.
# Site of the publisher.
# Script author.
# Prefix name (usually $PREFIX).

'''Description:'''

Present the software.

'''Example:'''
<pre class="playonlinux code">
POL_SetupWindow_presentation "$TITLE" "Mozilla" "http://www.mozilla.com" "SuperPlumus and NSLW" "$PREFIX"
</pre>

=== POL_SetupWindow_free_presentation ===

'''Arguments:'''

# Software name (often $TITLE).
# Message.

'''Description:'''

Present the software with more freedom than POL_SetupWindow_presentation.

'''Example:'''
<pre class="playonlinux code">
POL_SetupWindow_free_presentation "$TITLE" "Welcome to Mozilla Firefox installation wizard."
</pre>

=== POL_SetupWindow_message ===

'''Arguments:'''

# Message.
# Title (often $TITLE).

'''Description:'''

Display a message.

'''Example:'''
<pre class="playonlinux code">
POL_SetupWindow_message "Hello world!" "$TITLE"
</pre>

=== check_one - POL_SetupWindow_missing ===

'''Arguments for check_one:'''

# Program that must be present.
# 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:'''
<pre class="playonlinux code">
check_one "p7zip" "p7zip"
POL_SetupWindow_missing
</pre>

=== POL_SetupWindow_file ===

'''Arguments:'''

# Message.
# Title (often $TITLE).
# File to display.

'''Description:'''

Display the content of a file.

'''Example:'''
<pre class="playonlinux code">
POL_SetupWindow_file "Changelog" "$TITLE" "$POL_System_TmpDir/changelog.txt"
</pre>

=== POL_SetupWindow_licence ===

'''Arguments:'''

# Message.
# Title (often $TITLE).
# File to display.

'''Description:'''

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

Useful for displaying licenses.

'''Example:'''
<pre class="playonlinux code">
POL_SetupWindow_licence "Licence:" "$TITLE" "$POL_System_TmpDir/licence.txt"
</pre>

=== POL_SetupWindow_pulsebar - POL_SetupWindow_pulse - POL_SetupWindow_set_text ===

'''Arguments for POL_SetupWindow_pulsebar:'''

# Message.
# Title (often $TITLE).

'''Arguments for POL_SetupWindow_pulse:'''

# Percentage.

'''Arguments for POL_SetupWindow_set_text:'''

# 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:'''
<pre class="playonlinux code">
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"
</pre>

=== POL_SetupWindow_wait ===

'''Arguments:'''

# Message.
# Title (often $TITLE).

'''Description:'''

Display an indeterminate progress bar.

'''Example:'''
<pre class="playonlinux code">
POL_SetupWindow_wait "Please wait" "$TITLE"
</pre>

=== POL_SetupWindow_textbox ===

'''Arguments:'''

# Message.
# Title (often $TITLE).
# 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:'''
<pre class="playonlinux code">
POL_SetupWindow_textbox "Votre pseudo :" "$TITLE"
</pre>

=== POL_SetupWindow_textbox_multiline ===

'''Arguments:'''

# Message.
# Title (often $TITLE).
# 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:'''
<pre class="playonlinux code">
POL_SetupWindow_textbox_multiline "Enter a description for the program" "$TITLE"
</pre>

=== POL_SetupWindow_browse ===

'''Arguments:'''

# Message.
# Title (often $TITLE).
# 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:'''
<pre class="playonlinux code">
POL_SetupWindow_browse "Please select the program." "$TITLE"
</pre>

=== POL_SetupWindow_question ===

'''Arguments:'''

# Message.
# 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:'''
<pre class="playonlinux code">
POL_SetupWindow_question "Message" "Title"
</pre>

=== POL_SetupWindow_menu ===

'''Arguments:'''

# Message.
# Title (often $TITLE).
# Available choices.
# 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:'''
<pre class="playonlinux code">
POL_SetupWindow_menu "What's your favorite color?" "$TITLE" "Red~Green~Blue" "~"
</pre>

=== POL_SetupWindow_menu_num ===

'''Arguments:'''

# Message.
# Title (often $TITLE).
# Available choices.
# 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:'''
<pre class="playonlinux code">
POL_SetupWindow_menu_num "What's your favorite color?" "$TITLE" "Red~Green~Blue" "~"
</pre>

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

=== POL_SetupWindow_menu_list ===

'''Arguments:'''

# Message.
# Title (often $TITLE).
# Available choices.
# Separator character (often ~ or -).
# 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:'''
<pre class="playonlinux code">
POL_SetupWindow_menu_list "What's your favorite color?" "$TITLE" "Red~Green~Blue" "~"
</pre>

=== POL_SetupWindow_checkbox_list ===

'''Arguments:'''

# Message.
# Title (often $TITLE).
# Available choices.
# 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:'''
<pre class="playonlinux code">
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
</pre>

=== 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:'''
<pre class="playonlinux code">
POL_SetupWindow_cdrom
</pre>

=== POL_SetupWindow_check_cdrom ===

'''Arguments:'''

# 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:'''
<pre class="playonlinux code">
POL_SetupWindow_check_cdrom "Data/32_icon.ico"
</pre>

=== POL_SetupWindow_InstallMethod ===

'''Arguments:'''

# 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:'''
<pre class="playonlinux code">
POL_SetupWindow_InstallMethod "LOCAL,CD,STEAM"
</pre>

== POL_Shortcut ==

'''Arguments:'''

# Executable filename.
# Launcher name (often $TITLE).
# Optional name of the icon to download from PlayOnLinux website.
# Optional executable arguments.
# 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 [http://linux.die.net/man/7/glob 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 [http://standards.freedesktop.org/menu-spec/latest/apa.html main] and [http://standards.freedesktop.org/menu-spec/latest/apas02.html 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:'''
<pre class="playonlinux code">
POL_Shortcut "firefox.exe" "$TITLE"
</pre>

== POL_Shortcut_InsertBeforeWine ==

'''Arguments:'''

# Launcher name (often $TITLE).
# Command to add.

'''Description:'''

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

'''Example:'''
<pre class="playonlinux code">
POL_Shortcut_InsertBeforeWine "Jedi Knight II" "export __GL_ExtensionStringVersion=17700"
</pre>

== POL_Shortcut_Document ==
'''Arguments:'''
# Launcher name (often $TITLE).
# 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:'''

# URL to open.

'''Description:'''

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

'''Example:'''
<pre class="playonlinux code">
POL_Browser "http://www.playonlinux.com"
</pre>

== POL_Download ==

'''Arguments:'''

# URL to download.
# (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 ==

'''Arguments:'''

# URL to download.
# Expected MD5 digest of the downloaded file
# (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 ==

'''Arguments:'''

# 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:'''
<pre class="playonlinux code">
POL_System_TmpCreate "$PREFIX"
</pre>

== POL_System_TmpDelete ==

'''Description:'''

Removes the script's temporary directory.

'''Example:'''
<pre class="playonlinux code">
POL_System_TmpDelete
</pre>

== POL_System_SetArch ==

'''Arguments:'''

# 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:'''
<pre class="playonlinux code">
POL_System_SetArch "auto"
</pre>

== POL_Call ==

'''Arguments:'''

# Function name.
# 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|Components and Functions]]).

'''Prerequisite:'''

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

'''Example:'''
<pre class="playonlinux code">
POL_Call POL_Install_vcrun6
</pre>

== Wine-related functions ==

=== POL_Wine_SelectPrefix ===

'''Arguments:'''

# 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:'''
<pre class="playonlinux code">
POL_Wine_SelectPrefix "$PREFIX"
</pre>

=== POL_Wine_PrefixExists ===

'''Arguments:'''

# 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:'''
<pre class="playonlinux code">
if [ "$(POL_Wine_PrefixExists "$PREFIX")" = "False" ]
then
# The préfixe doesn't exist
fi
</pre>

=== POL_Wine_PrefixCreate ===

'''Arguments:'''

# 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:'''
<pre class="playonlinux code">
POL_Wine_PrefixCreate "1.3.4"
</pre>

=== 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:'''

# 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:'''
<pre class="playonlinux code">
POL_SetupWindow_VMS "128"
</pre>

=== Set_OS ===

'''Arguments:'''

# Windows version to emulate.
# 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:'''
<pre class="playonlinux code">
Set_OS "win2k"
</pre>

=== Set_Managed ===

'''Arguments:'''

# 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:'''
<pre class="playonlinux code">
Set_Managed "Off"
</pre>

=== Set_SoundDriver ===

'''Arguments:'''

# alsa/oss/esd.

'''Description:'''

Set the audio driver Wine will use.

{{Info|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:'''
<pre class="playonlinux code">
Set_SoundDriver "alsa"
</pre>

=== POL_Wine_Direct3D ===

'''Arguments:'''

# Setting to create/modify.
# New setting value.

'''Description:'''

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

'''Allowed values:'''

See [http://wiki.winehq.org/UsefulRegistryKeys WineHQ's Wiki].

'''Prerequisite:'''

The commands POL_Wine_SelectPrefix and POL_Wine_PrefixCreate must have been used beforehand.

'''Example:'''
<pre class="playonlinux code">
POL_Wine_Direct3D "UseGLSL" "disabled"
</pre>

=== POL_Wine_X11Drv ===

'''Arguments:'''

# Setting to create/modify.
# New setting value.

'''Description:'''

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

'''Allowed values:'''

See [http://wiki.winehq.org/UsefulRegistryKeys WineHQ's Wiki].

'''Prerequisite:'''

The commands POL_Wine_SelectPrefix and POL_Wine_PrefixCreate must have been used beforehand.

'''Example:'''
<pre class="playonlinux code">
POL_Wine_X11Drv "DXGrab" "Y"
</pre>

=== POL_Wine_DirectSound ===

'''Arguments:'''

# Setting to create/modify.
# New setting value.

'''Description:'''

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

'''Allowed values:'''

See [http://wiki.winehq.org/UsefulRegistryKeys WineHQ's Wiki].

'''Prerequisite:'''

The commands POL_Wine_SelectPrefix and POL_Wine_PrefixCreate must have been used beforehand.

'''Example:'''
<pre class="playonlinux code">
POL_Wine_DirectSound "HardwareAcceleration" "Emulation"
</pre>

=== POL_Wine_DirectInput ===

'''Arguments:'''

# Setting to create/modify.
# New setting value.

'''Description:'''

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

'''Allowed values:'''

See [http://wiki.winehq.org/UsefulRegistryKeys WineHQ's Wiki].

'''Prerequisite:'''

The commands POL_Wine_SelectPrefix and POL_Wine_PrefixCreate must have been used beforehand.

'''Example:'''
<pre class="playonlinux code">
POL_Wine_DirectInput "MouseWarpOverride" "force"
</pre>

=== POL_Wine_GetRegValue ===

'''Arguments:'''

# 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:'''
<pre class="playonlinux code">
VALUE="$(POL_Wine_GetRegValue "MouseWarpOverride")"
</pre>

=== Set_Desktop ===

'''Arguments:'''

# On/Off.
# Virtual desktop width (if it is enabled).
# 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:'''
<pre class="playonlinux code">
Set_Desktop "On" "1024" "768"
</pre>

=== Set_WineWindowTitle ===

'''Arguments:'''

# 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:'''
<pre class="playonlinux code">
Set_WineWindowTitle "$TITLE"
</pre>

=== 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:'''
<pre class="playonlinux code">
POL_Wine_InstallFonts
</pre>

=== 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:'''
<pre class="playonlinux code">
POL_Wine_SetVideoDriver
</pre>

=== POL_Wine_OverrideDLL ===

'''Arguments:'''

# Mode of override.
# 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:'''
<pre class="playonlinux code">
POL_Wine_OverrideDLL "native" "msvcrt"
POL_Wine_OverrideDLL "" "msvcrt" # To disable the DLL
</pre>

=== POL_Wine_OverrideDLL_App ===

'''Arguments:'''

# Executable name.
# Mode of override.
# 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:'''
<pre class="playonlinux code">
POL_Wine_OverrideDLL_App "firefox.exe" "native" "msvcrt"
POL_Wine_OverrideDLL_App "firefox.exe" "" "msvcrt" # To disable the DLL
</pre>

=== POL_Wine_WaitBefore ===

'''Arguments:'''

# 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:'''

# 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:'''
<pre class="playonlinux code">
POL_Wine_WaitExit "$TITLE"
</pre>

=== POL_Wine_reboot ===

'''Description:'''

Emulate a Windows reboot.

'''Prerequisite:'''

The commands POL_Wine_SelectPrefix and POL_Wine_PrefixCreate must have been used beforehand.

'''Example:'''
<pre class="playonlinux code">
POL_Wine_reboot
</pre>

== Debugging commands ==

=== POL_Debug_Init ===

'''Description:'''

Start debugging system.

'''Example:'''
<pre class="playonlinux code">
POL_Debug_Init
</pre>

=== POL_Debug_Message ===

'''Arguments:'''

# 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:'''
<pre class="playonlinux code">
POL_Debug_Message "Modifying config.cfg file."
</pre>

=== POL_Debug_Warning ===

'''Arguments:'''

# 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:'''
<pre class="playonlinux code">
POL_Debug_Warning "File config.cfg did not exist, creating one."
</pre>

=== POL_Debug_Error ===

'''Arguments:'''

# 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:'''
<pre class="playonlinux code">
POL_Debug_Error "Error while modifying config.cfg file"
</pre>

=== POL_Debug_Fatal ===

'''Arguments:'''

# Message.

'''Description:'''

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

'''Prerequisite:'''

The command POL_Debug_Init must have been used beforehand.

'''Example:'''
<pre class="playonlinux code">
POL_Debug_Fatal "Error while modifying config.cfg file"
</pre>

'''Previous:''' [[Scripting - Chapter 10: Script Translation|Chapter 10: Script Translation]]

[[Category:Scripting]]

Scripting - Chapter 11: List of Functions

2015-03-29T09:55:12Z

Petch: /* POL_Browser */ Document POL_Download (I think it was used in the tutorial but was missing from the 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:'''

# URL of top image.
# URL of left image.
# 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:'''
<pre class="playonlinux code">
POL_GetSetupImages "http://files.playonlinux.com/resources/setups/AC2/top.jpg" "http://files.playonlinux.com/resources/setups/AC2/left.jpg" "$TITLE"
</pre>

=== POL_SetupWindow_Init ===

'''Description:'''

Opens the installation wizard window.

'''Example:'''
<pre class="playonlinux code">
POL_SetupWindow_Init
</pre>

=== POL_SetupWindow_Close ===

'''Description:'''

Closes the installation wizard window.

'''Example:'''
<pre class="playonlinux code">
POL_SetupWindow_Close
</pre>

== PlayOnLinux graphical interface ==

{{Warning|All the functions below need the command POL_SetupWindow_Init to be executed beforehand.}}

=== POL_SetupWindow_presentation ===

'''Arguments:'''

# Software name (often $TITLE).
# Software publisher.
# Site of the publisher.
# Script author.
# Prefix name (usually $PREFIX).

'''Description:'''

Present the software.

'''Example:'''
<pre class="playonlinux code">
POL_SetupWindow_presentation "$TITLE" "Mozilla" "http://www.mozilla.com" "SuperPlumus and NSLW" "$PREFIX"
</pre>

=== POL_SetupWindow_free_presentation ===

'''Arguments:'''

# Software name (often $TITLE).
# Message.

'''Description:'''

Present the software with more freedom than POL_SetupWindow_presentation.

'''Example:'''
<pre class="playonlinux code">
POL_SetupWindow_free_presentation "$TITLE" "Welcome to Mozilla Firefox installation wizard."
</pre>

=== POL_SetupWindow_message ===

'''Arguments:'''

# Message.
# Title (often $TITLE).

'''Description:'''

Display a message.

'''Example:'''
<pre class="playonlinux code">
POL_SetupWindow_message "Hello world!" "$TITLE"
</pre>

=== check_one - POL_SetupWindow_missing ===

'''Arguments for check_one:'''

# Program that must be present.
# 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:'''
<pre class="playonlinux code">
check_one "p7zip" "p7zip"
POL_SetupWindow_missing
</pre>

=== POL_SetupWindow_file ===

'''Arguments:'''

# Message.
# Title (often $TITLE).
# File to display.

'''Description:'''

Display the content of a file.

'''Example:'''
<pre class="playonlinux code">
POL_SetupWindow_file "Changelog" "$TITLE" "$POL_System_TmpDir/changelog.txt"
</pre>

=== POL_SetupWindow_licence ===

'''Arguments:'''

# Message.
# Title (often $TITLE).
# File to display.

'''Description:'''

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

Useful for displaying licenses.

'''Example:'''
<pre class="playonlinux code">
POL_SetupWindow_licence "Licence:" "$TITLE" "$POL_System_TmpDir/licence.txt"
</pre>

=== POL_SetupWindow_pulsebar - POL_SetupWindow_pulse - POL_SetupWindow_set_text ===

'''Arguments for POL_SetupWindow_pulsebar:'''

# Message.
# Title (often $TITLE).

'''Arguments for POL_SetupWindow_pulse:'''

# Percentage.

'''Arguments for POL_SetupWindow_set_text:'''

# 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:'''
<pre class="playonlinux code">
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"
</pre>

=== POL_SetupWindow_wait ===

'''Arguments:'''

# Message.
# Title (often $TITLE).

'''Description:'''

Display an indeterminate progress bar.

'''Example:'''
<pre class="playonlinux code">
POL_SetupWindow_wait "Please wait" "$TITLE"
</pre>

=== POL_SetupWindow_textbox ===

'''Arguments:'''

# Message.
# Title (often $TITLE).
# 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:'''
<pre class="playonlinux code">
POL_SetupWindow_textbox "Votre pseudo :" "$TITLE"
</pre>

=== POL_SetupWindow_textbox_multiline ===

'''Arguments:'''

# Message.
# Title (often $TITLE).
# 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:'''
<pre class="playonlinux code">
POL_SetupWindow_textbox_multiline "Enter a description for the program" "$TITLE"
</pre>

=== POL_SetupWindow_browse ===

'''Arguments:'''

# Message.
# Title (often $TITLE).
# 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:'''
<pre class="playonlinux code">
POL_SetupWindow_browse "Please select the program." "$TITLE"
</pre>

=== POL_SetupWindow_question ===

'''Arguments:'''

# Message.
# 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:'''
<pre class="playonlinux code">
POL_SetupWindow_question "Message" "Title"
</pre>

=== POL_SetupWindow_menu ===

'''Arguments:'''

# Message.
# Title (often $TITLE).
# Available choices.
# 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:'''
<pre class="playonlinux code">
POL_SetupWindow_menu "What's your favorite color?" "$TITLE" "Red~Green~Blue" "~"
</pre>

=== POL_SetupWindow_menu_num ===

'''Arguments:'''

# Message.
# Title (often $TITLE).
# Available choices.
# 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:'''
<pre class="playonlinux code">
POL_SetupWindow_menu_num "What's your favorite color?" "$TITLE" "Red~Green~Blue" "~"
</pre>

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

=== POL_SetupWindow_menu_list ===

'''Arguments:'''

# Message.
# Title (often $TITLE).
# Available choices.
# Separator character (often ~ or -).
# 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:'''
<pre class="playonlinux code">
POL_SetupWindow_menu_list "What's your favorite color?" "$TITLE" "Red~Green~Blue" "~"
</pre>

=== POL_SetupWindow_checkbox_list ===

'''Arguments:'''

# Message.
# Title (often $TITLE).
# Available choices.
# 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:'''
<pre class="playonlinux code">
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
</pre>

=== 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:'''
<pre class="playonlinux code">
POL_SetupWindow_cdrom
</pre>

=== POL_SetupWindow_check_cdrom ===

'''Arguments:'''

# 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:'''
<pre class="playonlinux code">
POL_SetupWindow_check_cdrom "Data/32_icon.ico"
</pre>

=== POL_SetupWindow_InstallMethod ===

'''Arguments:'''

# 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:'''
<pre class="playonlinux code">
POL_SetupWindow_InstallMethod "LOCAL,CD,STEAM"
</pre>

== POL_Shortcut ==

'''Arguments:'''

# Executable filename.
# Launcher name (often $TITLE).
# Optional name of the icon to download from PlayOnLinux website.
# Optional executable arguments.
# 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 [http://linux.die.net/man/7/glob 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 [http://standards.freedesktop.org/menu-spec/latest/apa.html main] and [http://standards.freedesktop.org/menu-spec/latest/apas02.html 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:'''
<pre class="playonlinux code">
POL_Shortcut "firefox.exe" "$TITLE"
</pre>

== POL_Shortcut_InsertBeforeWine ==

'''Arguments:'''

# Launcher name (often $TITLE).
# Command to add.

'''Description:'''

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

'''Example:'''
<pre class="playonlinux code">
POL_Shortcut_InsertBeforeWine "Jedi Knight II" "export __GL_ExtensionStringVersion=17700"
</pre>

== POL_Shortcut_Document ==
'''Arguments:'''
# Launcher name (often $TITLE).
# 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:'''

# URL to open.

'''Description:'''

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

'''Example:'''
<pre class="playonlinux code">
POL_Browser "http://www.playonlinux.com"
</pre>

== POL_Download ==

'''Arguments:'''

# URL to download.
# (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_System_TmpCreate ==

'''Arguments:'''

# 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:'''
<pre class="playonlinux code">
POL_System_TmpCreate "$PREFIX"
</pre>

== POL_System_TmpDelete ==

'''Description:'''

Removes the script's temporary directory.

'''Example:'''
<pre class="playonlinux code">
POL_System_TmpDelete
</pre>

== POL_System_SetArch ==

'''Arguments:'''

# 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:'''
<pre class="playonlinux code">
POL_System_SetArch "auto"
</pre>

== POL_Call ==

'''Arguments:'''

# Function name.
# 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|Components and Functions]]).

'''Prerequisite:'''

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

'''Example:'''
<pre class="playonlinux code">
POL_Call POL_Install_vcrun6
</pre>

== Wine-related functions ==

=== POL_Wine_SelectPrefix ===

'''Arguments:'''

# 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:'''
<pre class="playonlinux code">
POL_Wine_SelectPrefix "$PREFIX"
</pre>

=== POL_Wine_PrefixExists ===

'''Arguments:'''

# 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:'''
<pre class="playonlinux code">
if [ "$(POL_Wine_PrefixExists "$PREFIX")" = "False" ]
then
# The préfixe doesn't exist
fi
</pre>

=== POL_Wine_PrefixCreate ===

'''Arguments:'''

# 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:'''
<pre class="playonlinux code">
POL_Wine_PrefixCreate "1.3.4"
</pre>

=== 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:'''

# 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:'''
<pre class="playonlinux code">
POL_SetupWindow_VMS "128"
</pre>

=== Set_OS ===

'''Arguments:'''

# Windows version to emulate.
# 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:'''
<pre class="playonlinux code">
Set_OS "win2k"
</pre>

=== Set_Managed ===

'''Arguments:'''

# 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:'''
<pre class="playonlinux code">
Set_Managed "Off"
</pre>

=== Set_SoundDriver ===

'''Arguments:'''

# alsa/oss/esd.

'''Description:'''

Set the audio driver Wine will use.

{{Info|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:'''
<pre class="playonlinux code">
Set_SoundDriver "alsa"
</pre>

=== POL_Wine_Direct3D ===

'''Arguments:'''

# Setting to create/modify.
# New setting value.

'''Description:'''

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

'''Allowed values:'''

See [http://wiki.winehq.org/UsefulRegistryKeys WineHQ's Wiki].

'''Prerequisite:'''

The commands POL_Wine_SelectPrefix and POL_Wine_PrefixCreate must have been used beforehand.

'''Example:'''
<pre class="playonlinux code">
POL_Wine_Direct3D "UseGLSL" "disabled"
</pre>

=== POL_Wine_X11Drv ===

'''Arguments:'''

# Setting to create/modify.
# New setting value.

'''Description:'''

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

'''Allowed values:'''

See [http://wiki.winehq.org/UsefulRegistryKeys WineHQ's Wiki].

'''Prerequisite:'''

The commands POL_Wine_SelectPrefix and POL_Wine_PrefixCreate must have been used beforehand.

'''Example:'''
<pre class="playonlinux code">
POL_Wine_X11Drv "DXGrab" "Y"
</pre>

=== POL_Wine_DirectSound ===

'''Arguments:'''

# Setting to create/modify.
# New setting value.

'''Description:'''

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

'''Allowed values:'''

See [http://wiki.winehq.org/UsefulRegistryKeys WineHQ's Wiki].

'''Prerequisite:'''

The commands POL_Wine_SelectPrefix and POL_Wine_PrefixCreate must have been used beforehand.

'''Example:'''
<pre class="playonlinux code">
POL_Wine_DirectSound "HardwareAcceleration" "Emulation"
</pre>

=== POL_Wine_DirectInput ===

'''Arguments:'''

# Setting to create/modify.
# New setting value.

'''Description:'''

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

'''Allowed values:'''

See [http://wiki.winehq.org/UsefulRegistryKeys WineHQ's Wiki].

'''Prerequisite:'''

The commands POL_Wine_SelectPrefix and POL_Wine_PrefixCreate must have been used beforehand.

'''Example:'''
<pre class="playonlinux code">
POL_Wine_DirectInput "MouseWarpOverride" "force"
</pre>

=== POL_Wine_GetRegValue ===

'''Arguments:'''

# 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:'''
<pre class="playonlinux code">
VALUE="$(POL_Wine_GetRegValue "MouseWarpOverride")"
</pre>

=== Set_Desktop ===

'''Arguments:'''

# On/Off.
# Virtual desktop width (if it is enabled).
# 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:'''
<pre class="playonlinux code">
Set_Desktop "On" "1024" "768"
</pre>

=== Set_WineWindowTitle ===

'''Arguments:'''

# 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:'''
<pre class="playonlinux code">
Set_WineWindowTitle "$TITLE"
</pre>

=== 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:'''
<pre class="playonlinux code">
POL_Wine_InstallFonts
</pre>

=== 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:'''
<pre class="playonlinux code">
POL_Wine_SetVideoDriver
</pre>

=== POL_Wine_OverrideDLL ===

'''Arguments:'''

# Mode of override.
# 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:'''
<pre class="playonlinux code">
POL_Wine_OverrideDLL "native" "msvcrt"
POL_Wine_OverrideDLL "" "msvcrt" # To disable the DLL
</pre>

=== POL_Wine_OverrideDLL_App ===

'''Arguments:'''

# Executable name.
# Mode of override.
# 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:'''
<pre class="playonlinux code">
POL_Wine_OverrideDLL_App "firefox.exe" "native" "msvcrt"
POL_Wine_OverrideDLL_App "firefox.exe" "" "msvcrt" # To disable the DLL
</pre>

=== POL_Wine_WaitBefore ===

'''Arguments:'''

# 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:'''

# 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:'''
<pre class="playonlinux code">
POL_Wine_WaitExit "$TITLE"
</pre>

=== POL_Wine_reboot ===

'''Description:'''

Emulate a Windows reboot.

'''Prerequisite:'''

The commands POL_Wine_SelectPrefix and POL_Wine_PrefixCreate must have been used beforehand.

'''Example:'''
<pre class="playonlinux code">
POL_Wine_reboot
</pre>

== Debugging commands ==

=== POL_Debug_Init ===

'''Description:'''

Start debugging system.

'''Example:'''
<pre class="playonlinux code">
POL_Debug_Init
</pre>

=== POL_Debug_Message ===

'''Arguments:'''

# 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:'''
<pre class="playonlinux code">
POL_Debug_Message "Modifying config.cfg file."
</pre>

=== POL_Debug_Warning ===

'''Arguments:'''

# 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:'''
<pre class="playonlinux code">
POL_Debug_Warning "File config.cfg did not exist, creating one."
</pre>

=== POL_Debug_Error ===

'''Arguments:'''

# 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:'''
<pre class="playonlinux code">
POL_Debug_Error "Error while modifying config.cfg file"
</pre>

=== POL_Debug_Fatal ===

'''Arguments:'''

# Message.

'''Description:'''

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

'''Prerequisite:'''

The command POL_Debug_Init must have been used beforehand.

'''Example:'''
<pre class="playonlinux code">
POL_Debug_Fatal "Error while modifying config.cfg file"
</pre>

'''Previous:''' [[Scripting - Chapter 10: Script Translation|Chapter 10: Script Translation]]

[[Category:Scripting]]

Scripting - Chapter 11: List of Functions

2015-03-27T17:47:16Z

Petch: /* POL_SetupWindow_check_cdrom */ Document $CDROM_SETUP, as it's used in several scripts

== 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:'''

# URL of top image.
# URL of left image.
# 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:'''
<pre class="playonlinux code">
POL_GetSetupImages "http://files.playonlinux.com/resources/setups/AC2/top.jpg" "http://files.playonlinux.com/resources/setups/AC2/left.jpg" "$TITLE"
</pre>

=== POL_SetupWindow_Init ===

'''Description:'''

Opens the installation wizard window.

'''Example:'''
<pre class="playonlinux code">
POL_SetupWindow_Init
</pre>

=== POL_SetupWindow_Close ===

'''Description:'''

Closes the installation wizard window.

'''Example:'''
<pre class="playonlinux code">
POL_SetupWindow_Close
</pre>

== PlayOnLinux graphical interface ==

{{Warning|All the functions below need the command POL_SetupWindow_Init to be executed beforehand.}}

=== POL_SetupWindow_presentation ===

'''Arguments:'''

# Software name (often $TITLE).
# Software publisher.
# Site of the publisher.
# Script author.
# Prefix name (usually $PREFIX).

'''Description:'''

Present the software.

'''Example:'''
<pre class="playonlinux code">
POL_SetupWindow_presentation "$TITLE" "Mozilla" "http://www.mozilla.com" "SuperPlumus and NSLW" "$PREFIX"
</pre>

=== POL_SetupWindow_free_presentation ===

'''Arguments:'''

# Software name (often $TITLE).
# Message.

'''Description:'''

Present the software with more freedom than POL_SetupWindow_presentation.

'''Example:'''
<pre class="playonlinux code">
POL_SetupWindow_free_presentation "$TITLE" "Welcome to Mozilla Firefox installation wizard."
</pre>

=== POL_SetupWindow_message ===

'''Arguments:'''

# Message.
# Title (often $TITLE).

'''Description:'''

Display a message.

'''Example:'''
<pre class="playonlinux code">
POL_SetupWindow_message "Hello world!" "$TITLE"
</pre>

=== check_one - POL_SetupWindow_missing ===

'''Arguments for check_one:'''

# Program that must be present.
# 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:'''
<pre class="playonlinux code">
check_one "p7zip" "p7zip"
POL_SetupWindow_missing
</pre>

=== POL_SetupWindow_file ===

'''Arguments:'''

# Message.
# Title (often $TITLE).
# File to display.

'''Description:'''

Display the content of a file.

'''Example:'''
<pre class="playonlinux code">
POL_SetupWindow_file "Changelog" "$TITLE" "$POL_System_TmpDir/changelog.txt"
</pre>

=== POL_SetupWindow_licence ===

'''Arguments:'''

# Message.
# Title (often $TITLE).
# File to display.

'''Description:'''

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

Useful for displaying licenses.

'''Example:'''
<pre class="playonlinux code">
POL_SetupWindow_licence "Licence:" "$TITLE" "$POL_System_TmpDir/licence.txt"
</pre>

=== POL_SetupWindow_pulsebar - POL_SetupWindow_pulse - POL_SetupWindow_set_text ===

'''Arguments for POL_SetupWindow_pulsebar:'''

# Message.
# Title (often $TITLE).

'''Arguments for POL_SetupWindow_pulse:'''

# Percentage.

'''Arguments for POL_SetupWindow_set_text:'''

# 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:'''
<pre class="playonlinux code">
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"
</pre>

=== POL_SetupWindow_wait ===

'''Arguments:'''

# Message.
# Title (often $TITLE).

'''Description:'''

Display an indeterminate progress bar.

'''Example:'''
<pre class="playonlinux code">
POL_SetupWindow_wait "Please wait" "$TITLE"
</pre>

=== POL_SetupWindow_textbox ===

'''Arguments:'''

# Message.
# Title (often $TITLE).
# 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:'''
<pre class="playonlinux code">
POL_SetupWindow_textbox "Votre pseudo :" "$TITLE"
</pre>

=== POL_SetupWindow_textbox_multiline ===

'''Arguments:'''

# Message.
# Title (often $TITLE).
# 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:'''
<pre class="playonlinux code">
POL_SetupWindow_textbox_multiline "Enter a description for the program" "$TITLE"
</pre>

=== POL_SetupWindow_browse ===

'''Arguments:'''

# Message.
# Title (often $TITLE).
# 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:'''
<pre class="playonlinux code">
POL_SetupWindow_browse "Please select the program." "$TITLE"
</pre>

=== POL_SetupWindow_question ===

'''Arguments:'''

# Message.
# 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:'''
<pre class="playonlinux code">
POL_SetupWindow_question "Message" "Title"
</pre>

=== POL_SetupWindow_menu ===

'''Arguments:'''

# Message.
# Title (often $TITLE).
# Available choices.
# 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:'''
<pre class="playonlinux code">
POL_SetupWindow_menu "What's your favorite color?" "$TITLE" "Red~Green~Blue" "~"
</pre>

=== POL_SetupWindow_menu_num ===

'''Arguments:'''

# Message.
# Title (often $TITLE).
# Available choices.
# 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:'''
<pre class="playonlinux code">
POL_SetupWindow_menu_num "What's your favorite color?" "$TITLE" "Red~Green~Blue" "~"
</pre>

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

=== POL_SetupWindow_menu_list ===

'''Arguments:'''

# Message.
# Title (often $TITLE).
# Available choices.
# Separator character (often ~ or -).
# 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:'''
<pre class="playonlinux code">
POL_SetupWindow_menu_list "What's your favorite color?" "$TITLE" "Red~Green~Blue" "~"
</pre>

=== POL_SetupWindow_checkbox_list ===

'''Arguments:'''

# Message.
# Title (often $TITLE).
# Available choices.
# 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:'''
<pre class="playonlinux code">
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
</pre>

=== 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:'''
<pre class="playonlinux code">
POL_SetupWindow_cdrom
</pre>

=== POL_SetupWindow_check_cdrom ===

'''Arguments:'''

# 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:'''
<pre class="playonlinux code">
POL_SetupWindow_check_cdrom "Data/32_icon.ico"
</pre>

=== POL_SetupWindow_InstallMethod ===

'''Arguments:'''

# 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:'''
<pre class="playonlinux code">
POL_SetupWindow_InstallMethod "LOCAL,CD,STEAM"
</pre>

== POL_Shortcut ==

'''Arguments:'''

# Executable filename.
# Launcher name (often $TITLE).
# Optional name of the icon to download from PlayOnLinux website.
# Optional executable arguments.
# 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 [http://linux.die.net/man/7/glob 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 [http://standards.freedesktop.org/menu-spec/latest/apa.html main] and [http://standards.freedesktop.org/menu-spec/latest/apas02.html 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:'''
<pre class="playonlinux code">
POL_Shortcut "firefox.exe" "$TITLE"
</pre>

== POL_Shortcut_InsertBeforeWine ==

'''Arguments:'''

# Launcher name (often $TITLE).
# Command to add.

'''Description:'''

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

'''Example:'''
<pre class="playonlinux code">
POL_Shortcut_InsertBeforeWine "Jedi Knight II" "export __GL_ExtensionStringVersion=17700"
</pre>

== POL_Shortcut_Document ==
'''Arguments:'''
# Launcher name (often $TITLE).
# 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:'''

# URL to open.

'''Description:'''

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

'''Example:'''
<pre class="playonlinux code">
POL_Browser "http://www.playonlinux.com"
</pre>

== POL_System_TmpCreate ==

'''Arguments:'''

# 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:'''
<pre class="playonlinux code">
POL_System_TmpCreate "$PREFIX"
</pre>

== POL_System_TmpDelete ==

'''Description:'''

Removes the script's temporary directory.

'''Example:'''
<pre class="playonlinux code">
POL_System_TmpDelete
</pre>

== POL_System_SetArch ==

'''Arguments:'''

# 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:'''
<pre class="playonlinux code">
POL_System_SetArch "auto"
</pre>

== POL_Call ==

'''Arguments:'''

# Function name.
# 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|Components and Functions]]).

'''Prerequisite:'''

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

'''Example:'''
<pre class="playonlinux code">
POL_Call POL_Install_vcrun6
</pre>

== Wine-related functions ==

=== POL_Wine_SelectPrefix ===

'''Arguments:'''

# 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:'''
<pre class="playonlinux code">
POL_Wine_SelectPrefix "$PREFIX"
</pre>

=== POL_Wine_PrefixExists ===

'''Arguments:'''

# 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:'''
<pre class="playonlinux code">
if [ "$(POL_Wine_PrefixExists "$PREFIX")" = "False" ]
then
# The préfixe doesn't exist
fi
</pre>

=== POL_Wine_PrefixCreate ===

'''Arguments:'''

# 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:'''
<pre class="playonlinux code">
POL_Wine_PrefixCreate "1.3.4"
</pre>

=== 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:'''

# 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:'''
<pre class="playonlinux code">
POL_SetupWindow_VMS "128"
</pre>

=== Set_OS ===

'''Arguments:'''

# Windows version to emulate.
# 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:'''
<pre class="playonlinux code">
Set_OS "win2k"
</pre>

=== Set_Managed ===

'''Arguments:'''

# 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:'''
<pre class="playonlinux code">
Set_Managed "Off"
</pre>

=== Set_SoundDriver ===

'''Arguments:'''

# alsa/oss/esd.

'''Description:'''

Set the audio driver Wine will use.

{{Info|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:'''
<pre class="playonlinux code">
Set_SoundDriver "alsa"
</pre>

=== POL_Wine_Direct3D ===

'''Arguments:'''

# Setting to create/modify.
# New setting value.

'''Description:'''

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

'''Allowed values:'''

See [http://wiki.winehq.org/UsefulRegistryKeys WineHQ's Wiki].

'''Prerequisite:'''

The commands POL_Wine_SelectPrefix and POL_Wine_PrefixCreate must have been used beforehand.

'''Example:'''
<pre class="playonlinux code">
POL_Wine_Direct3D "UseGLSL" "disabled"
</pre>

=== POL_Wine_X11Drv ===

'''Arguments:'''

# Setting to create/modify.
# New setting value.

'''Description:'''

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

'''Allowed values:'''

See [http://wiki.winehq.org/UsefulRegistryKeys WineHQ's Wiki].

'''Prerequisite:'''

The commands POL_Wine_SelectPrefix and POL_Wine_PrefixCreate must have been used beforehand.

'''Example:'''
<pre class="playonlinux code">
POL_Wine_X11Drv "DXGrab" "Y"
</pre>

=== POL_Wine_DirectSound ===

'''Arguments:'''

# Setting to create/modify.
# New setting value.

'''Description:'''

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

'''Allowed values:'''

See [http://wiki.winehq.org/UsefulRegistryKeys WineHQ's Wiki].

'''Prerequisite:'''

The commands POL_Wine_SelectPrefix and POL_Wine_PrefixCreate must have been used beforehand.

'''Example:'''
<pre class="playonlinux code">
POL_Wine_DirectSound "HardwareAcceleration" "Emulation"
</pre>

=== POL_Wine_DirectInput ===

'''Arguments:'''

# Setting to create/modify.
# New setting value.

'''Description:'''

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

'''Allowed values:'''

See [http://wiki.winehq.org/UsefulRegistryKeys WineHQ's Wiki].

'''Prerequisite:'''

The commands POL_Wine_SelectPrefix and POL_Wine_PrefixCreate must have been used beforehand.

'''Example:'''
<pre class="playonlinux code">
POL_Wine_DirectInput "MouseWarpOverride" "force"
</pre>

=== POL_Wine_GetRegValue ===

'''Arguments:'''

# 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:'''
<pre class="playonlinux code">
VALUE="$(POL_Wine_GetRegValue "MouseWarpOverride")"
</pre>

=== Set_Desktop ===

'''Arguments:'''

# On/Off.
# Virtual desktop width (if it is enabled).
# 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:'''
<pre class="playonlinux code">
Set_Desktop "On" "1024" "768"
</pre>

=== Set_WineWindowTitle ===

'''Arguments:'''

# 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:'''
<pre class="playonlinux code">
Set_WineWindowTitle "$TITLE"
</pre>

=== 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:'''
<pre class="playonlinux code">
POL_Wine_InstallFonts
</pre>

=== 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:'''
<pre class="playonlinux code">
POL_Wine_SetVideoDriver
</pre>

=== POL_Wine_OverrideDLL ===

'''Arguments:'''

# Mode of override.
# 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:'''
<pre class="playonlinux code">
POL_Wine_OverrideDLL "native" "msvcrt"
POL_Wine_OverrideDLL "" "msvcrt" # To disable the DLL
</pre>

=== POL_Wine_OverrideDLL_App ===

'''Arguments:'''

# Executable name.
# Mode of override.
# 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:'''
<pre class="playonlinux code">
POL_Wine_OverrideDLL_App "firefox.exe" "native" "msvcrt"
POL_Wine_OverrideDLL_App "firefox.exe" "" "msvcrt" # To disable the DLL
</pre>

=== POL_Wine_WaitBefore ===

'''Arguments:'''

# 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:'''

# 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:'''
<pre class="playonlinux code">
POL_Wine_WaitExit "$TITLE"
</pre>

=== POL_Wine_reboot ===

'''Description:'''

Emulate a Windows reboot.

'''Prerequisite:'''

The commands POL_Wine_SelectPrefix and POL_Wine_PrefixCreate must have been used beforehand.

'''Example:'''
<pre class="playonlinux code">
POL_Wine_reboot
</pre>

== Debugging commands ==

=== POL_Debug_Init ===

'''Description:'''

Start debugging system.

'''Example:'''
<pre class="playonlinux code">
POL_Debug_Init
</pre>

=== POL_Debug_Message ===

'''Arguments:'''

# 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:'''
<pre class="playonlinux code">
POL_Debug_Message "Modifying config.cfg file."
</pre>

=== POL_Debug_Warning ===

'''Arguments:'''

# 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:'''
<pre class="playonlinux code">
POL_Debug_Warning "File config.cfg did not exist, creating one."
</pre>

=== POL_Debug_Error ===

'''Arguments:'''

# 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:'''
<pre class="playonlinux code">
POL_Debug_Error "Error while modifying config.cfg file"
</pre>

=== POL_Debug_Fatal ===

'''Arguments:'''

# Message.

'''Description:'''

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

'''Prerequisite:'''

The command POL_Debug_Init must have been used beforehand.

'''Example:'''
<pre class="playonlinux code">
POL_Debug_Fatal "Error while modifying config.cfg file"
</pre>

'''Previous:''' [[Scripting - Chapter 10: Script Translation|Chapter 10: Script Translation]]

[[Category:Scripting]]

Scripting - Chapter 11: List of Functions

2015-03-22T17:37:35Z

Petch: /* POL_Shortcut */ Fix typo

== 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:'''

# URL of top image.
# URL of left image.
# 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:'''
<pre class="playonlinux code">
POL_GetSetupImages "http://files.playonlinux.com/resources/setups/AC2/top.jpg" "http://files.playonlinux.com/resources/setups/AC2/left.jpg" "$TITLE"
</pre>

=== POL_SetupWindow_Init ===

'''Description:'''

Opens the installation wizard window.

'''Example:'''
<pre class="playonlinux code">
POL_SetupWindow_Init
</pre>

=== POL_SetupWindow_Close ===

'''Description:'''

Closes the installation wizard window.

'''Example:'''
<pre class="playonlinux code">
POL_SetupWindow_Close
</pre>

== PlayOnLinux graphical interface ==

{{Warning|All the functions below need the command POL_SetupWindow_Init to be executed beforehand.}}

=== POL_SetupWindow_presentation ===

'''Arguments:'''

# Software name (often $TITLE).
# Software publisher.
# Site of the publisher.
# Script author.
# Prefix name (usually $PREFIX).

'''Description:'''

Present the software.

'''Example:'''
<pre class="playonlinux code">
POL_SetupWindow_presentation "$TITLE" "Mozilla" "http://www.mozilla.com" "SuperPlumus and NSLW" "$PREFIX"
</pre>

=== POL_SetupWindow_free_presentation ===

'''Arguments:'''

# Software name (often $TITLE).
# Message.

'''Description:'''

Present the software with more freedom than POL_SetupWindow_presentation.

'''Example:'''
<pre class="playonlinux code">
POL_SetupWindow_free_presentation "$TITLE" "Welcome to Mozilla Firefox installation wizard."
</pre>

=== POL_SetupWindow_message ===

'''Arguments:'''

# Message.
# Title (often $TITLE).

'''Description:'''

Display a message.

'''Example:'''
<pre class="playonlinux code">
POL_SetupWindow_message "Hello world!" "$TITLE"
</pre>

=== check_one - POL_SetupWindow_missing ===

'''Arguments for check_one:'''

# Program that must be present.
# 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:'''
<pre class="playonlinux code">
check_one "p7zip" "p7zip"
POL_SetupWindow_missing
</pre>

=== POL_SetupWindow_file ===

'''Arguments:'''

# Message.
# Title (often $TITLE).
# File to display.

'''Description:'''

Display the content of a file.

'''Example:'''
<pre class="playonlinux code">
POL_SetupWindow_file "Changelog" "$TITLE" "$POL_System_TmpDir/changelog.txt"
</pre>

=== POL_SetupWindow_licence ===

'''Arguments:'''

# Message.
# Title (often $TITLE).
# File to display.

'''Description:'''

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

Useful for displaying licenses.

'''Example:'''
<pre class="playonlinux code">
POL_SetupWindow_licence "Licence:" "$TITLE" "$POL_System_TmpDir/licence.txt"
</pre>

=== POL_SetupWindow_pulsebar - POL_SetupWindow_pulse - POL_SetupWindow_set_text ===

'''Arguments for POL_SetupWindow_pulsebar:'''

# Message.
# Title (often $TITLE).

'''Arguments for POL_SetupWindow_pulse:'''

# Percentage.

'''Arguments for POL_SetupWindow_set_text:'''

# 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:'''
<pre class="playonlinux code">
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"
</pre>

=== POL_SetupWindow_wait ===

'''Arguments:'''

# Message.
# Title (often $TITLE).

'''Description:'''

Display an indeterminate progress bar.

'''Example:'''
<pre class="playonlinux code">
POL_SetupWindow_wait "Please wait" "$TITLE"
</pre>

=== POL_SetupWindow_textbox ===

'''Arguments:'''

# Message.
# Title (often $TITLE).
# 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:'''
<pre class="playonlinux code">
POL_SetupWindow_textbox "Votre pseudo :" "$TITLE"
</pre>

=== POL_SetupWindow_textbox_multiline ===

'''Arguments:'''

# Message.
# Title (often $TITLE).
# 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:'''
<pre class="playonlinux code">
POL_SetupWindow_textbox_multiline "Enter a description for the program" "$TITLE"
</pre>

=== POL_SetupWindow_browse ===

'''Arguments:'''

# Message.
# Title (often $TITLE).
# 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:'''
<pre class="playonlinux code">
POL_SetupWindow_browse "Please select the program." "$TITLE"
</pre>

=== POL_SetupWindow_question ===

'''Arguments:'''

# Message.
# 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:'''
<pre class="playonlinux code">
POL_SetupWindow_question "Message" "Title"
</pre>

=== POL_SetupWindow_menu ===

'''Arguments:'''

# Message.
# Title (often $TITLE).
# Available choices.
# 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:'''
<pre class="playonlinux code">
POL_SetupWindow_menu "What's your favorite color?" "$TITLE" "Red~Green~Blue" "~"
</pre>

=== POL_SetupWindow_menu_num ===

'''Arguments:'''

# Message.
# Title (often $TITLE).
# Available choices.
# 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:'''
<pre class="playonlinux code">
POL_SetupWindow_menu_num "What's your favorite color?" "$TITLE" "Red~Green~Blue" "~"
</pre>

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

=== POL_SetupWindow_menu_list ===

'''Arguments:'''

# Message.
# Title (often $TITLE).
# Available choices.
# Separator character (often ~ or -).
# 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:'''
<pre class="playonlinux code">
POL_SetupWindow_menu_list "What's your favorite color?" "$TITLE" "Red~Green~Blue" "~"
</pre>

=== POL_SetupWindow_checkbox_list ===

'''Arguments:'''

# Message.
# Title (often $TITLE).
# Available choices.
# 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:'''
<pre class="playonlinux code">
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
</pre>

=== 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:'''
<pre class="playonlinux code">
POL_SetupWindow_cdrom
</pre>

=== POL_SetupWindow_check_cdrom ===

'''Arguments:'''

# 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:'''
<pre class="playonlinux code">
POL_SetupWindow_check_cdrom "Data/32_icon.ico"
</pre>

=== POL_SetupWindow_InstallMethod ===

'''Arguments:'''

# 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:'''
<pre class="playonlinux code">
POL_SetupWindow_InstallMethod "LOCAL,CD,STEAM"
</pre>

== POL_Shortcut ==

'''Arguments:'''

# Executable filename.
# Launcher name (often $TITLE).
# Optional name of the icon to download from PlayOnLinux website.
# Optional executable arguments.
# 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 [http://linux.die.net/man/7/glob 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 [http://standards.freedesktop.org/menu-spec/latest/apa.html main] and [http://standards.freedesktop.org/menu-spec/latest/apas02.html 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:'''
<pre class="playonlinux code">
POL_Shortcut "firefox.exe" "$TITLE"
</pre>

== POL_Shortcut_InsertBeforeWine ==

'''Arguments:'''

# Launcher name (often $TITLE).
# Command to add.

'''Description:'''

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

'''Example:'''
<pre class="playonlinux code">
POL_Shortcut_InsertBeforeWine "Jedi Knight II" "export __GL_ExtensionStringVersion=17700"
</pre>

== POL_Shortcut_Document ==
'''Arguments:'''
# Launcher name (often $TITLE).
# 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:'''

# URL to open.

'''Description:'''

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

'''Example:'''
<pre class="playonlinux code">
POL_Browser "http://www.playonlinux.com"
</pre>

== POL_System_TmpCreate ==

'''Arguments:'''

# 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:'''
<pre class="playonlinux code">
POL_System_TmpCreate "$PREFIX"
</pre>

== POL_System_TmpDelete ==

'''Description:'''

Removes the script's temporary directory.

'''Example:'''
<pre class="playonlinux code">
POL_System_TmpDelete
</pre>

== POL_System_SetArch ==

'''Arguments:'''

# 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:'''
<pre class="playonlinux code">
POL_System_SetArch "auto"
</pre>

== POL_Call ==

'''Arguments:'''

# Function name.
# 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|Components and Functions]]).

'''Prerequisite:'''

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

'''Example:'''
<pre class="playonlinux code">
POL_Call POL_Install_vcrun6
</pre>

== Wine-related functions ==

=== POL_Wine_SelectPrefix ===

'''Arguments:'''

# 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:'''
<pre class="playonlinux code">
POL_Wine_SelectPrefix "$PREFIX"
</pre>

=== POL_Wine_PrefixExists ===

'''Arguments:'''

# 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:'''
<pre class="playonlinux code">
if [ "$(POL_Wine_PrefixExists "$PREFIX")" = "False" ]
then
# The préfixe doesn't exist
fi
</pre>

=== POL_Wine_PrefixCreate ===

'''Arguments:'''

# 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:'''
<pre class="playonlinux code">
POL_Wine_PrefixCreate "1.3.4"
</pre>

=== 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:'''

# 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:'''
<pre class="playonlinux code">
POL_SetupWindow_VMS "128"
</pre>

=== Set_OS ===

'''Arguments:'''

# Windows version to emulate.
# 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:'''
<pre class="playonlinux code">
Set_OS "win2k"
</pre>

=== Set_Managed ===

'''Arguments:'''

# 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:'''
<pre class="playonlinux code">
Set_Managed "Off"
</pre>

=== Set_SoundDriver ===

'''Arguments:'''

# alsa/oss/esd.

'''Description:'''

Set the audio driver Wine will use.

{{Info|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:'''
<pre class="playonlinux code">
Set_SoundDriver "alsa"
</pre>

=== POL_Wine_Direct3D ===

'''Arguments:'''

# Setting to create/modify.
# New setting value.

'''Description:'''

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

'''Allowed values:'''

See [http://wiki.winehq.org/UsefulRegistryKeys WineHQ's Wiki].

'''Prerequisite:'''

The commands POL_Wine_SelectPrefix and POL_Wine_PrefixCreate must have been used beforehand.

'''Example:'''
<pre class="playonlinux code">
POL_Wine_Direct3D "UseGLSL" "disabled"
</pre>

=== POL_Wine_X11Drv ===

'''Arguments:'''

# Setting to create/modify.
# New setting value.

'''Description:'''

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

'''Allowed values:'''

See [http://wiki.winehq.org/UsefulRegistryKeys WineHQ's Wiki].

'''Prerequisite:'''

The commands POL_Wine_SelectPrefix and POL_Wine_PrefixCreate must have been used beforehand.

'''Example:'''
<pre class="playonlinux code">
POL_Wine_X11Drv "DXGrab" "Y"
</pre>

=== POL_Wine_DirectSound ===

'''Arguments:'''

# Setting to create/modify.
# New setting value.

'''Description:'''

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

'''Allowed values:'''

See [http://wiki.winehq.org/UsefulRegistryKeys WineHQ's Wiki].

'''Prerequisite:'''

The commands POL_Wine_SelectPrefix and POL_Wine_PrefixCreate must have been used beforehand.

'''Example:'''
<pre class="playonlinux code">
POL_Wine_DirectSound "HardwareAcceleration" "Emulation"
</pre>

=== POL_Wine_DirectInput ===

'''Arguments:'''

# Setting to create/modify.
# New setting value.

'''Description:'''

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

'''Allowed values:'''

See [http://wiki.winehq.org/UsefulRegistryKeys WineHQ's Wiki].

'''Prerequisite:'''

The commands POL_Wine_SelectPrefix and POL_Wine_PrefixCreate must have been used beforehand.

'''Example:'''
<pre class="playonlinux code">
POL_Wine_DirectInput "MouseWarpOverride" "force"
</pre>

=== POL_Wine_GetRegValue ===

'''Arguments:'''

# 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:'''
<pre class="playonlinux code">
VALUE="$(POL_Wine_GetRegValue "MouseWarpOverride")"
</pre>

=== Set_Desktop ===

'''Arguments:'''

# On/Off.
# Virtual desktop width (if it is enabled).
# 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:'''
<pre class="playonlinux code">
Set_Desktop "On" "1024" "768"
</pre>

=== Set_WineWindowTitle ===

'''Arguments:'''

# 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:'''
<pre class="playonlinux code">
Set_WineWindowTitle "$TITLE"
</pre>

=== 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:'''
<pre class="playonlinux code">
POL_Wine_InstallFonts
</pre>

=== 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:'''
<pre class="playonlinux code">
POL_Wine_SetVideoDriver
</pre>

=== POL_Wine_OverrideDLL ===

'''Arguments:'''

# Mode of override.
# 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:'''
<pre class="playonlinux code">
POL_Wine_OverrideDLL "native" "msvcrt"
POL_Wine_OverrideDLL "" "msvcrt" # To disable the DLL
</pre>

=== POL_Wine_OverrideDLL_App ===

'''Arguments:'''

# Executable name.
# Mode of override.
# 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:'''
<pre class="playonlinux code">
POL_Wine_OverrideDLL_App "firefox.exe" "native" "msvcrt"
POL_Wine_OverrideDLL_App "firefox.exe" "" "msvcrt" # To disable the DLL
</pre>

=== POL_Wine_WaitBefore ===

'''Arguments:'''

# 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:'''

# 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:'''
<pre class="playonlinux code">
POL_Wine_WaitExit "$TITLE"
</pre>

=== POL_Wine_reboot ===

'''Description:'''

Emulate a Windows reboot.

'''Prerequisite:'''

The commands POL_Wine_SelectPrefix and POL_Wine_PrefixCreate must have been used beforehand.

'''Example:'''
<pre class="playonlinux code">
POL_Wine_reboot
</pre>

== Debugging commands ==

=== POL_Debug_Init ===

'''Description:'''

Start debugging system.

'''Example:'''
<pre class="playonlinux code">
POL_Debug_Init
</pre>

=== POL_Debug_Message ===

'''Arguments:'''

# 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:'''
<pre class="playonlinux code">
POL_Debug_Message "Modifying config.cfg file."
</pre>

=== POL_Debug_Warning ===

'''Arguments:'''

# 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:'''
<pre class="playonlinux code">
POL_Debug_Warning "File config.cfg did not exist, creating one."
</pre>

=== POL_Debug_Error ===

'''Arguments:'''

# 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:'''
<pre class="playonlinux code">
POL_Debug_Error "Error while modifying config.cfg file"
</pre>

=== POL_Debug_Fatal ===

'''Arguments:'''

# Message.

'''Description:'''

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

'''Prerequisite:'''

The command POL_Debug_Init must have been used beforehand.

'''Example:'''
<pre class="playonlinux code">
POL_Debug_Fatal "Error while modifying config.cfg file"
</pre>

'''Previous:''' [[Scripting - Chapter 10: Script Translation|Chapter 10: Script Translation]]

[[Category:Scripting]]

Scripting - Chapter 11: List of Functions

2015-03-22T17:36:49Z

Petch: /* POL_Shortcut */ Document behavior when a path is specified

== 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:'''

# URL of top image.
# URL of left image.
# 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:'''
<pre class="playonlinux code">
POL_GetSetupImages "http://files.playonlinux.com/resources/setups/AC2/top.jpg" "http://files.playonlinux.com/resources/setups/AC2/left.jpg" "$TITLE"
</pre>

=== POL_SetupWindow_Init ===

'''Description:'''

Opens the installation wizard window.

'''Example:'''
<pre class="playonlinux code">
POL_SetupWindow_Init
</pre>

=== POL_SetupWindow_Close ===

'''Description:'''

Closes the installation wizard window.

'''Example:'''
<pre class="playonlinux code">
POL_SetupWindow_Close
</pre>

== PlayOnLinux graphical interface ==

{{Warning|All the functions below need the command POL_SetupWindow_Init to be executed beforehand.}}

=== POL_SetupWindow_presentation ===

'''Arguments:'''

# Software name (often $TITLE).
# Software publisher.
# Site of the publisher.
# Script author.
# Prefix name (usually $PREFIX).

'''Description:'''

Present the software.

'''Example:'''
<pre class="playonlinux code">
POL_SetupWindow_presentation "$TITLE" "Mozilla" "http://www.mozilla.com" "SuperPlumus and NSLW" "$PREFIX"
</pre>

=== POL_SetupWindow_free_presentation ===

'''Arguments:'''

# Software name (often $TITLE).
# Message.

'''Description:'''

Present the software with more freedom than POL_SetupWindow_presentation.

'''Example:'''
<pre class="playonlinux code">
POL_SetupWindow_free_presentation "$TITLE" "Welcome to Mozilla Firefox installation wizard."
</pre>

=== POL_SetupWindow_message ===

'''Arguments:'''

# Message.
# Title (often $TITLE).

'''Description:'''

Display a message.

'''Example:'''
<pre class="playonlinux code">
POL_SetupWindow_message "Hello world!" "$TITLE"
</pre>

=== check_one - POL_SetupWindow_missing ===

'''Arguments for check_one:'''

# Program that must be present.
# 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:'''
<pre class="playonlinux code">
check_one "p7zip" "p7zip"
POL_SetupWindow_missing
</pre>

=== POL_SetupWindow_file ===

'''Arguments:'''

# Message.
# Title (often $TITLE).
# File to display.

'''Description:'''

Display the content of a file.

'''Example:'''
<pre class="playonlinux code">
POL_SetupWindow_file "Changelog" "$TITLE" "$POL_System_TmpDir/changelog.txt"
</pre>

=== POL_SetupWindow_licence ===

'''Arguments:'''

# Message.
# Title (often $TITLE).
# File to display.

'''Description:'''

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

Useful for displaying licenses.

'''Example:'''
<pre class="playonlinux code">
POL_SetupWindow_licence "Licence:" "$TITLE" "$POL_System_TmpDir/licence.txt"
</pre>

=== POL_SetupWindow_pulsebar - POL_SetupWindow_pulse - POL_SetupWindow_set_text ===

'''Arguments for POL_SetupWindow_pulsebar:'''

# Message.
# Title (often $TITLE).

'''Arguments for POL_SetupWindow_pulse:'''

# Percentage.

'''Arguments for POL_SetupWindow_set_text:'''

# 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:'''
<pre class="playonlinux code">
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"
</pre>

=== POL_SetupWindow_wait ===

'''Arguments:'''

# Message.
# Title (often $TITLE).

'''Description:'''

Display an indeterminate progress bar.

'''Example:'''
<pre class="playonlinux code">
POL_SetupWindow_wait "Please wait" "$TITLE"
</pre>

=== POL_SetupWindow_textbox ===

'''Arguments:'''

# Message.
# Title (often $TITLE).
# 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:'''
<pre class="playonlinux code">
POL_SetupWindow_textbox "Votre pseudo :" "$TITLE"
</pre>

=== POL_SetupWindow_textbox_multiline ===

'''Arguments:'''

# Message.
# Title (often $TITLE).
# 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:'''
<pre class="playonlinux code">
POL_SetupWindow_textbox_multiline "Enter a description for the program" "$TITLE"
</pre>

=== POL_SetupWindow_browse ===

'''Arguments:'''

# Message.
# Title (often $TITLE).
# 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:'''
<pre class="playonlinux code">
POL_SetupWindow_browse "Please select the program." "$TITLE"
</pre>

=== POL_SetupWindow_question ===

'''Arguments:'''

# Message.
# 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:'''
<pre class="playonlinux code">
POL_SetupWindow_question "Message" "Title"
</pre>

=== POL_SetupWindow_menu ===

'''Arguments:'''

# Message.
# Title (often $TITLE).
# Available choices.
# 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:'''
<pre class="playonlinux code">
POL_SetupWindow_menu "What's your favorite color?" "$TITLE" "Red~Green~Blue" "~"
</pre>

=== POL_SetupWindow_menu_num ===

'''Arguments:'''

# Message.
# Title (often $TITLE).
# Available choices.
# 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:'''
<pre class="playonlinux code">
POL_SetupWindow_menu_num "What's your favorite color?" "$TITLE" "Red~Green~Blue" "~"
</pre>

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

=== POL_SetupWindow_menu_list ===

'''Arguments:'''

# Message.
# Title (often $TITLE).
# Available choices.
# Separator character (often ~ or -).
# 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:'''
<pre class="playonlinux code">
POL_SetupWindow_menu_list "What's your favorite color?" "$TITLE" "Red~Green~Blue" "~"
</pre>

=== POL_SetupWindow_checkbox_list ===

'''Arguments:'''

# Message.
# Title (often $TITLE).
# Available choices.
# 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:'''
<pre class="playonlinux code">
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
</pre>

=== 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:'''
<pre class="playonlinux code">
POL_SetupWindow_cdrom
</pre>

=== POL_SetupWindow_check_cdrom ===

'''Arguments:'''

# 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:'''
<pre class="playonlinux code">
POL_SetupWindow_check_cdrom "Data/32_icon.ico"
</pre>

=== POL_SetupWindow_InstallMethod ===

'''Arguments:'''

# 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:'''
<pre class="playonlinux code">
POL_SetupWindow_InstallMethod "LOCAL,CD,STEAM"
</pre>

== POL_Shortcut ==

'''Arguments:'''

# Executable filename.
# Launcher name (often $TITLE).
# Optional name of the icon to download from PlayOnLinux website.
# Optional executable arguments.
# 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, translated the name of the "Program Files" directory according to the user locale, so you should always use the special variable $PROGRAMFILES instead of the name in your own locale.

If no path is specified (recommended), the executable filename is looked up using a case insensitive [http://linux.die.net/man/7/glob 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 [http://standards.freedesktop.org/menu-spec/latest/apa.html main] and [http://standards.freedesktop.org/menu-spec/latest/apas02.html 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:'''
<pre class="playonlinux code">
POL_Shortcut "firefox.exe" "$TITLE"
</pre>

== POL_Shortcut_InsertBeforeWine ==

'''Arguments:'''

# Launcher name (often $TITLE).
# Command to add.

'''Description:'''

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

'''Example:'''
<pre class="playonlinux code">
POL_Shortcut_InsertBeforeWine "Jedi Knight II" "export __GL_ExtensionStringVersion=17700"
</pre>

== POL_Shortcut_Document ==
'''Arguments:'''
# Launcher name (often $TITLE).
# 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:'''

# URL to open.

'''Description:'''

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

'''Example:'''
<pre class="playonlinux code">
POL_Browser "http://www.playonlinux.com"
</pre>

== POL_System_TmpCreate ==

'''Arguments:'''

# 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:'''
<pre class="playonlinux code">
POL_System_TmpCreate "$PREFIX"
</pre>

== POL_System_TmpDelete ==

'''Description:'''

Removes the script's temporary directory.

'''Example:'''
<pre class="playonlinux code">
POL_System_TmpDelete
</pre>

== POL_System_SetArch ==

'''Arguments:'''

# 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:'''
<pre class="playonlinux code">
POL_System_SetArch "auto"
</pre>

== POL_Call ==

'''Arguments:'''

# Function name.
# 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|Components and Functions]]).

'''Prerequisite:'''

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

'''Example:'''
<pre class="playonlinux code">
POL_Call POL_Install_vcrun6
</pre>

== Wine-related functions ==

=== POL_Wine_SelectPrefix ===

'''Arguments:'''

# 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:'''
<pre class="playonlinux code">
POL_Wine_SelectPrefix "$PREFIX"
</pre>

=== POL_Wine_PrefixExists ===

'''Arguments:'''

# 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:'''
<pre class="playonlinux code">
if [ "$(POL_Wine_PrefixExists "$PREFIX")" = "False" ]
then
# The préfixe doesn't exist
fi
</pre>

=== POL_Wine_PrefixCreate ===

'''Arguments:'''

# 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:'''
<pre class="playonlinux code">
POL_Wine_PrefixCreate "1.3.4"
</pre>

=== 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:'''

# 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:'''
<pre class="playonlinux code">
POL_SetupWindow_VMS "128"
</pre>

=== Set_OS ===

'''Arguments:'''

# Windows version to emulate.
# 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:'''
<pre class="playonlinux code">
Set_OS "win2k"
</pre>

=== Set_Managed ===

'''Arguments:'''

# 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:'''
<pre class="playonlinux code">
Set_Managed "Off"
</pre>

=== Set_SoundDriver ===

'''Arguments:'''

# alsa/oss/esd.

'''Description:'''

Set the audio driver Wine will use.

{{Info|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:'''
<pre class="playonlinux code">
Set_SoundDriver "alsa"
</pre>

=== POL_Wine_Direct3D ===

'''Arguments:'''

# Setting to create/modify.
# New setting value.

'''Description:'''

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

'''Allowed values:'''

See [http://wiki.winehq.org/UsefulRegistryKeys WineHQ's Wiki].

'''Prerequisite:'''

The commands POL_Wine_SelectPrefix and POL_Wine_PrefixCreate must have been used beforehand.

'''Example:'''
<pre class="playonlinux code">
POL_Wine_Direct3D "UseGLSL" "disabled"
</pre>

=== POL_Wine_X11Drv ===

'''Arguments:'''

# Setting to create/modify.
# New setting value.

'''Description:'''

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

'''Allowed values:'''

See [http://wiki.winehq.org/UsefulRegistryKeys WineHQ's Wiki].

'''Prerequisite:'''

The commands POL_Wine_SelectPrefix and POL_Wine_PrefixCreate must have been used beforehand.

'''Example:'''
<pre class="playonlinux code">
POL_Wine_X11Drv "DXGrab" "Y"
</pre>

=== POL_Wine_DirectSound ===

'''Arguments:'''

# Setting to create/modify.
# New setting value.

'''Description:'''

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

'''Allowed values:'''

See [http://wiki.winehq.org/UsefulRegistryKeys WineHQ's Wiki].

'''Prerequisite:'''

The commands POL_Wine_SelectPrefix and POL_Wine_PrefixCreate must have been used beforehand.

'''Example:'''
<pre class="playonlinux code">
POL_Wine_DirectSound "HardwareAcceleration" "Emulation"
</pre>

=== POL_Wine_DirectInput ===

'''Arguments:'''

# Setting to create/modify.
# New setting value.

'''Description:'''

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

'''Allowed values:'''

See [http://wiki.winehq.org/UsefulRegistryKeys WineHQ's Wiki].

'''Prerequisite:'''

The commands POL_Wine_SelectPrefix and POL_Wine_PrefixCreate must have been used beforehand.

'''Example:'''
<pre class="playonlinux code">
POL_Wine_DirectInput "MouseWarpOverride" "force"
</pre>

=== POL_Wine_GetRegValue ===

'''Arguments:'''

# 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:'''
<pre class="playonlinux code">
VALUE="$(POL_Wine_GetRegValue "MouseWarpOverride")"
</pre>

=== Set_Desktop ===

'''Arguments:'''

# On/Off.
# Virtual desktop width (if it is enabled).
# 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:'''
<pre class="playonlinux code">
Set_Desktop "On" "1024" "768"
</pre>

=== Set_WineWindowTitle ===

'''Arguments:'''

# 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:'''
<pre class="playonlinux code">
Set_WineWindowTitle "$TITLE"
</pre>

=== 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:'''
<pre class="playonlinux code">
POL_Wine_InstallFonts
</pre>

=== 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:'''
<pre class="playonlinux code">
POL_Wine_SetVideoDriver
</pre>

=== POL_Wine_OverrideDLL ===

'''Arguments:'''

# Mode of override.
# 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:'''
<pre class="playonlinux code">
POL_Wine_OverrideDLL "native" "msvcrt"
POL_Wine_OverrideDLL "" "msvcrt" # To disable the DLL
</pre>

=== POL_Wine_OverrideDLL_App ===

'''Arguments:'''

# Executable name.
# Mode of override.
# 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:'''
<pre class="playonlinux code">
POL_Wine_OverrideDLL_App "firefox.exe" "native" "msvcrt"
POL_Wine_OverrideDLL_App "firefox.exe" "" "msvcrt" # To disable the DLL
</pre>

=== POL_Wine_WaitBefore ===

'''Arguments:'''

# 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:'''

# 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:'''
<pre class="playonlinux code">
POL_Wine_WaitExit "$TITLE"
</pre>

=== POL_Wine_reboot ===

'''Description:'''

Emulate a Windows reboot.

'''Prerequisite:'''

The commands POL_Wine_SelectPrefix and POL_Wine_PrefixCreate must have been used beforehand.

'''Example:'''
<pre class="playonlinux code">
POL_Wine_reboot
</pre>

== Debugging commands ==

=== POL_Debug_Init ===

'''Description:'''

Start debugging system.

'''Example:'''
<pre class="playonlinux code">
POL_Debug_Init
</pre>

=== POL_Debug_Message ===

'''Arguments:'''

# 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:'''
<pre class="playonlinux code">
POL_Debug_Message "Modifying config.cfg file."
</pre>

=== POL_Debug_Warning ===

'''Arguments:'''

# 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:'''
<pre class="playonlinux code">
POL_Debug_Warning "File config.cfg did not exist, creating one."
</pre>

=== POL_Debug_Error ===

'''Arguments:'''

# 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:'''
<pre class="playonlinux code">
POL_Debug_Error "Error while modifying config.cfg file"
</pre>

=== POL_Debug_Fatal ===

'''Arguments:'''

# Message.

'''Description:'''

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

'''Prerequisite:'''

The command POL_Debug_Init must have been used beforehand.

'''Example:'''
<pre class="playonlinux code">
POL_Debug_Fatal "Error while modifying config.cfg file"
</pre>

'''Previous:''' [[Scripting - Chapter 10: Script Translation|Chapter 10: Script Translation]]

[[Category:Scripting]]

Scripting - Chapter 11: List of Functions

2015-03-22T17:23:18Z

Petch: /* POL_Shortcut_InsertBeforeWine */ Add POL_Shortcut_Document

== 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:'''

# URL of top image.
# URL of left image.
# 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:'''
<pre class="playonlinux code">
POL_GetSetupImages "http://files.playonlinux.com/resources/setups/AC2/top.jpg" "http://files.playonlinux.com/resources/setups/AC2/left.jpg" "$TITLE"
</pre>

=== POL_SetupWindow_Init ===

'''Description:'''

Opens the installation wizard window.

'''Example:'''
<pre class="playonlinux code">
POL_SetupWindow_Init
</pre>

=== POL_SetupWindow_Close ===

'''Description:'''

Closes the installation wizard window.

'''Example:'''
<pre class="playonlinux code">
POL_SetupWindow_Close
</pre>

== PlayOnLinux graphical interface ==

{{Warning|All the functions below need the command POL_SetupWindow_Init to be executed beforehand.}}

=== POL_SetupWindow_presentation ===

'''Arguments:'''

# Software name (often $TITLE).
# Software publisher.
# Site of the publisher.
# Script author.
# Prefix name (usually $PREFIX).

'''Description:'''

Present the software.

'''Example:'''
<pre class="playonlinux code">
POL_SetupWindow_presentation "$TITLE" "Mozilla" "http://www.mozilla.com" "SuperPlumus and NSLW" "$PREFIX"
</pre>

=== POL_SetupWindow_free_presentation ===

'''Arguments:'''

# Software name (often $TITLE).
# Message.

'''Description:'''

Present the software with more freedom than POL_SetupWindow_presentation.

'''Example:'''
<pre class="playonlinux code">
POL_SetupWindow_free_presentation "$TITLE" "Welcome to Mozilla Firefox installation wizard."
</pre>

=== POL_SetupWindow_message ===

'''Arguments:'''

# Message.
# Title (often $TITLE).

'''Description:'''

Display a message.

'''Example:'''
<pre class="playonlinux code">
POL_SetupWindow_message "Hello world!" "$TITLE"
</pre>

=== check_one - POL_SetupWindow_missing ===

'''Arguments for check_one:'''

# Program that must be present.
# 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:'''
<pre class="playonlinux code">
check_one "p7zip" "p7zip"
POL_SetupWindow_missing
</pre>

=== POL_SetupWindow_file ===

'''Arguments:'''

# Message.
# Title (often $TITLE).
# File to display.

'''Description:'''

Display the content of a file.

'''Example:'''
<pre class="playonlinux code">
POL_SetupWindow_file "Changelog" "$TITLE" "$POL_System_TmpDir/changelog.txt"
</pre>

=== POL_SetupWindow_licence ===

'''Arguments:'''

# Message.
# Title (often $TITLE).
# File to display.

'''Description:'''

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

Useful for displaying licenses.

'''Example:'''
<pre class="playonlinux code">
POL_SetupWindow_licence "Licence:" "$TITLE" "$POL_System_TmpDir/licence.txt"
</pre>

=== POL_SetupWindow_pulsebar - POL_SetupWindow_pulse - POL_SetupWindow_set_text ===

'''Arguments for POL_SetupWindow_pulsebar:'''

# Message.
# Title (often $TITLE).

'''Arguments for POL_SetupWindow_pulse:'''

# Percentage.

'''Arguments for POL_SetupWindow_set_text:'''

# 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:'''
<pre class="playonlinux code">
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"
</pre>

=== POL_SetupWindow_wait ===

'''Arguments:'''

# Message.
# Title (often $TITLE).

'''Description:'''

Display an indeterminate progress bar.

'''Example:'''
<pre class="playonlinux code">
POL_SetupWindow_wait "Please wait" "$TITLE"
</pre>

=== POL_SetupWindow_textbox ===

'''Arguments:'''

# Message.
# Title (often $TITLE).
# 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:'''
<pre class="playonlinux code">
POL_SetupWindow_textbox "Votre pseudo :" "$TITLE"
</pre>

=== POL_SetupWindow_textbox_multiline ===

'''Arguments:'''

# Message.
# Title (often $TITLE).
# 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:'''
<pre class="playonlinux code">
POL_SetupWindow_textbox_multiline "Enter a description for the program" "$TITLE"
</pre>

=== POL_SetupWindow_browse ===

'''Arguments:'''

# Message.
# Title (often $TITLE).
# 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:'''
<pre class="playonlinux code">
POL_SetupWindow_browse "Please select the program." "$TITLE"
</pre>

=== POL_SetupWindow_question ===

'''Arguments:'''

# Message.
# 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:'''
<pre class="playonlinux code">
POL_SetupWindow_question "Message" "Title"
</pre>

=== POL_SetupWindow_menu ===

'''Arguments:'''

# Message.
# Title (often $TITLE).
# Available choices.
# 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:'''
<pre class="playonlinux code">
POL_SetupWindow_menu "What's your favorite color?" "$TITLE" "Red~Green~Blue" "~"
</pre>

=== POL_SetupWindow_menu_num ===

'''Arguments:'''

# Message.
# Title (often $TITLE).
# Available choices.
# 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:'''
<pre class="playonlinux code">
POL_SetupWindow_menu_num "What's your favorite color?" "$TITLE" "Red~Green~Blue" "~"
</pre>

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

=== POL_SetupWindow_menu_list ===

'''Arguments:'''

# Message.
# Title (often $TITLE).
# Available choices.
# Separator character (often ~ or -).
# 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:'''
<pre class="playonlinux code">
POL_SetupWindow_menu_list "What's your favorite color?" "$TITLE" "Red~Green~Blue" "~"
</pre>

=== POL_SetupWindow_checkbox_list ===

'''Arguments:'''

# Message.
# Title (often $TITLE).
# Available choices.
# 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:'''
<pre class="playonlinux code">
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
</pre>

=== 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:'''
<pre class="playonlinux code">
POL_SetupWindow_cdrom
</pre>

=== POL_SetupWindow_check_cdrom ===

'''Arguments:'''

# 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:'''
<pre class="playonlinux code">
POL_SetupWindow_check_cdrom "Data/32_icon.ico"
</pre>

=== POL_SetupWindow_InstallMethod ===

'''Arguments:'''

# 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:'''
<pre class="playonlinux code">
POL_SetupWindow_InstallMethod "LOCAL,CD,STEAM"
</pre>

== POL_Shortcut ==

'''Arguments:'''

# Executable filename.
# Launcher name (often $TITLE).
# Optional name of the icon to download from PlayOnLinux website.
# Optional executable arguments.
# Optional list of categories the program belongs to

'''Description:'''

Create a launcher in PlayOnLinux. The executable filename is looked up using a case insensitive [http://linux.die.net/man/7/glob 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 [http://standards.freedesktop.org/menu-spec/latest/apa.html main] and [http://standards.freedesktop.org/menu-spec/latest/apas02.html 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:'''
<pre class="playonlinux code">
POL_Shortcut "firefox.exe" "$TITLE"
</pre>

== POL_Shortcut_InsertBeforeWine ==

'''Arguments:'''

# Launcher name (often $TITLE).
# Command to add.

'''Description:'''

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

'''Example:'''
<pre class="playonlinux code">
POL_Shortcut_InsertBeforeWine "Jedi Knight II" "export __GL_ExtensionStringVersion=17700"
</pre>

== POL_Shortcut_Document ==
'''Arguments:'''
# Launcher name (often $TITLE).
# 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:'''

# URL to open.

'''Description:'''

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

'''Example:'''
<pre class="playonlinux code">
POL_Browser "http://www.playonlinux.com"
</pre>

== POL_System_TmpCreate ==

'''Arguments:'''

# 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:'''
<pre class="playonlinux code">
POL_System_TmpCreate "$PREFIX"
</pre>

== POL_System_TmpDelete ==

'''Description:'''

Removes the script's temporary directory.

'''Example:'''
<pre class="playonlinux code">
POL_System_TmpDelete
</pre>

== POL_System_SetArch ==

'''Arguments:'''

# 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:'''
<pre class="playonlinux code">
POL_System_SetArch "auto"
</pre>

== POL_Call ==

'''Arguments:'''

# Function name.
# 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|Components and Functions]]).

'''Prerequisite:'''

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

'''Example:'''
<pre class="playonlinux code">
POL_Call POL_Install_vcrun6
</pre>

== Wine-related functions ==

=== POL_Wine_SelectPrefix ===

'''Arguments:'''

# 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:'''
<pre class="playonlinux code">
POL_Wine_SelectPrefix "$PREFIX"
</pre>

=== POL_Wine_PrefixExists ===

'''Arguments:'''

# 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:'''
<pre class="playonlinux code">
if [ "$(POL_Wine_PrefixExists "$PREFIX")" = "False" ]
then
# The préfixe doesn't exist
fi
</pre>

=== POL_Wine_PrefixCreate ===

'''Arguments:'''

# 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:'''
<pre class="playonlinux code">
POL_Wine_PrefixCreate "1.3.4"
</pre>

=== 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:'''

# 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:'''
<pre class="playonlinux code">
POL_SetupWindow_VMS "128"
</pre>

=== Set_OS ===

'''Arguments:'''

# Windows version to emulate.
# 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:'''
<pre class="playonlinux code">
Set_OS "win2k"
</pre>

=== Set_Managed ===

'''Arguments:'''

# 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:'''
<pre class="playonlinux code">
Set_Managed "Off"
</pre>

=== Set_SoundDriver ===

'''Arguments:'''

# alsa/oss/esd.

'''Description:'''

Set the audio driver Wine will use.

{{Info|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:'''
<pre class="playonlinux code">
Set_SoundDriver "alsa"
</pre>

=== POL_Wine_Direct3D ===

'''Arguments:'''

# Setting to create/modify.
# New setting value.

'''Description:'''

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

'''Allowed values:'''

See [http://wiki.winehq.org/UsefulRegistryKeys WineHQ's Wiki].

'''Prerequisite:'''

The commands POL_Wine_SelectPrefix and POL_Wine_PrefixCreate must have been used beforehand.

'''Example:'''
<pre class="playonlinux code">
POL_Wine_Direct3D "UseGLSL" "disabled"
</pre>

=== POL_Wine_X11Drv ===

'''Arguments:'''

# Setting to create/modify.
# New setting value.

'''Description:'''

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

'''Allowed values:'''

See [http://wiki.winehq.org/UsefulRegistryKeys WineHQ's Wiki].

'''Prerequisite:'''

The commands POL_Wine_SelectPrefix and POL_Wine_PrefixCreate must have been used beforehand.

'''Example:'''
<pre class="playonlinux code">
POL_Wine_X11Drv "DXGrab" "Y"
</pre>

=== POL_Wine_DirectSound ===

'''Arguments:'''

# Setting to create/modify.
# New setting value.

'''Description:'''

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

'''Allowed values:'''

See [http://wiki.winehq.org/UsefulRegistryKeys WineHQ's Wiki].

'''Prerequisite:'''

The commands POL_Wine_SelectPrefix and POL_Wine_PrefixCreate must have been used beforehand.

'''Example:'''
<pre class="playonlinux code">
POL_Wine_DirectSound "HardwareAcceleration" "Emulation"
</pre>

=== POL_Wine_DirectInput ===

'''Arguments:'''

# Setting to create/modify.
# New setting value.

'''Description:'''

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

'''Allowed values:'''

See [http://wiki.winehq.org/UsefulRegistryKeys WineHQ's Wiki].

'''Prerequisite:'''

The commands POL_Wine_SelectPrefix and POL_Wine_PrefixCreate must have been used beforehand.

'''Example:'''
<pre class="playonlinux code">
POL_Wine_DirectInput "MouseWarpOverride" "force"
</pre>

=== POL_Wine_GetRegValue ===

'''Arguments:'''

# 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:'''
<pre class="playonlinux code">
VALUE="$(POL_Wine_GetRegValue "MouseWarpOverride")"
</pre>

=== Set_Desktop ===

'''Arguments:'''

# On/Off.
# Virtual desktop width (if it is enabled).
# 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:'''
<pre class="playonlinux code">
Set_Desktop "On" "1024" "768"
</pre>

=== Set_WineWindowTitle ===

'''Arguments:'''

# 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:'''
<pre class="playonlinux code">
Set_WineWindowTitle "$TITLE"
</pre>

=== 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:'''
<pre class="playonlinux code">
POL_Wine_InstallFonts
</pre>

=== 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:'''
<pre class="playonlinux code">
POL_Wine_SetVideoDriver
</pre>

=== POL_Wine_OverrideDLL ===

'''Arguments:'''

# Mode of override.
# 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:'''
<pre class="playonlinux code">
POL_Wine_OverrideDLL "native" "msvcrt"
POL_Wine_OverrideDLL "" "msvcrt" # To disable the DLL
</pre>

=== POL_Wine_OverrideDLL_App ===

'''Arguments:'''

# Executable name.
# Mode of override.
# 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:'''
<pre class="playonlinux code">
POL_Wine_OverrideDLL_App "firefox.exe" "native" "msvcrt"
POL_Wine_OverrideDLL_App "firefox.exe" "" "msvcrt" # To disable the DLL
</pre>

=== POL_Wine_WaitBefore ===

'''Arguments:'''

# 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:'''

# 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:'''
<pre class="playonlinux code">
POL_Wine_WaitExit "$TITLE"
</pre>

=== POL_Wine_reboot ===

'''Description:'''

Emulate a Windows reboot.

'''Prerequisite:'''

The commands POL_Wine_SelectPrefix and POL_Wine_PrefixCreate must have been used beforehand.

'''Example:'''
<pre class="playonlinux code">
POL_Wine_reboot
</pre>

== Debugging commands ==

=== POL_Debug_Init ===

'''Description:'''

Start debugging system.

'''Example:'''
<pre class="playonlinux code">
POL_Debug_Init
</pre>

=== POL_Debug_Message ===

'''Arguments:'''

# 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:'''
<pre class="playonlinux code">
POL_Debug_Message "Modifying config.cfg file."
</pre>

=== POL_Debug_Warning ===

'''Arguments:'''

# 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:'''
<pre class="playonlinux code">
POL_Debug_Warning "File config.cfg did not exist, creating one."
</pre>

=== POL_Debug_Error ===

'''Arguments:'''

# 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:'''
<pre class="playonlinux code">
POL_Debug_Error "Error while modifying config.cfg file"
</pre>

=== POL_Debug_Fatal ===

'''Arguments:'''

# Message.

'''Description:'''

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

'''Prerequisite:'''

The command POL_Debug_Init must have been used beforehand.

'''Example:'''
<pre class="playonlinux code">
POL_Debug_Fatal "Error while modifying config.cfg file"
</pre>

'''Previous:''' [[Scripting - Chapter 10: Script Translation|Chapter 10: Script Translation]]

[[Category:Scripting]]

Scripting - Chapter 11: List of Functions

2015-03-22T17:14:39Z

Petch: /* POL_Shortcut */ Detail POL_Shortcut behavior, document new 5th argument (categories)

== 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:'''

# URL of top image.
# URL of left image.
# 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:'''
<pre class="playonlinux code">
POL_GetSetupImages "http://files.playonlinux.com/resources/setups/AC2/top.jpg" "http://files.playonlinux.com/resources/setups/AC2/left.jpg" "$TITLE"
</pre>

=== POL_SetupWindow_Init ===

'''Description:'''

Opens the installation wizard window.

'''Example:'''
<pre class="playonlinux code">
POL_SetupWindow_Init
</pre>

=== POL_SetupWindow_Close ===

'''Description:'''

Closes the installation wizard window.

'''Example:'''
<pre class="playonlinux code">
POL_SetupWindow_Close
</pre>

== PlayOnLinux graphical interface ==

{{Warning|All the functions below need the command POL_SetupWindow_Init to be executed beforehand.}}

=== POL_SetupWindow_presentation ===

'''Arguments:'''

# Software name (often $TITLE).
# Software publisher.
# Site of the publisher.
# Script author.
# Prefix name (usually $PREFIX).

'''Description:'''

Present the software.

'''Example:'''
<pre class="playonlinux code">
POL_SetupWindow_presentation "$TITLE" "Mozilla" "http://www.mozilla.com" "SuperPlumus and NSLW" "$PREFIX"
</pre>

=== POL_SetupWindow_free_presentation ===

'''Arguments:'''

# Software name (often $TITLE).
# Message.

'''Description:'''

Present the software with more freedom than POL_SetupWindow_presentation.

'''Example:'''
<pre class="playonlinux code">
POL_SetupWindow_free_presentation "$TITLE" "Welcome to Mozilla Firefox installation wizard."
</pre>

=== POL_SetupWindow_message ===

'''Arguments:'''

# Message.
# Title (often $TITLE).

'''Description:'''

Display a message.

'''Example:'''
<pre class="playonlinux code">
POL_SetupWindow_message "Hello world!" "$TITLE"
</pre>

=== check_one - POL_SetupWindow_missing ===

'''Arguments for check_one:'''

# Program that must be present.
# 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:'''
<pre class="playonlinux code">
check_one "p7zip" "p7zip"
POL_SetupWindow_missing
</pre>

=== POL_SetupWindow_file ===

'''Arguments:'''

# Message.
# Title (often $TITLE).
# File to display.

'''Description:'''

Display the content of a file.

'''Example:'''
<pre class="playonlinux code">
POL_SetupWindow_file "Changelog" "$TITLE" "$POL_System_TmpDir/changelog.txt"
</pre>

=== POL_SetupWindow_licence ===

'''Arguments:'''

# Message.
# Title (often $TITLE).
# File to display.

'''Description:'''

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

Useful for displaying licenses.

'''Example:'''
<pre class="playonlinux code">
POL_SetupWindow_licence "Licence:" "$TITLE" "$POL_System_TmpDir/licence.txt"
</pre>

=== POL_SetupWindow_pulsebar - POL_SetupWindow_pulse - POL_SetupWindow_set_text ===

'''Arguments for POL_SetupWindow_pulsebar:'''

# Message.
# Title (often $TITLE).

'''Arguments for POL_SetupWindow_pulse:'''

# Percentage.

'''Arguments for POL_SetupWindow_set_text:'''

# 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:'''
<pre class="playonlinux code">
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"
</pre>

=== POL_SetupWindow_wait ===

'''Arguments:'''

# Message.
# Title (often $TITLE).

'''Description:'''

Display an indeterminate progress bar.

'''Example:'''
<pre class="playonlinux code">
POL_SetupWindow_wait "Please wait" "$TITLE"
</pre>

=== POL_SetupWindow_textbox ===

'''Arguments:'''

# Message.
# Title (often $TITLE).
# 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:'''
<pre class="playonlinux code">
POL_SetupWindow_textbox "Votre pseudo :" "$TITLE"
</pre>

=== POL_SetupWindow_textbox_multiline ===

'''Arguments:'''

# Message.
# Title (often $TITLE).
# 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:'''
<pre class="playonlinux code">
POL_SetupWindow_textbox_multiline "Enter a description for the program" "$TITLE"
</pre>

=== POL_SetupWindow_browse ===

'''Arguments:'''

# Message.
# Title (often $TITLE).
# 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:'''
<pre class="playonlinux code">
POL_SetupWindow_browse "Please select the program." "$TITLE"
</pre>

=== POL_SetupWindow_question ===

'''Arguments:'''

# Message.
# 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:'''
<pre class="playonlinux code">
POL_SetupWindow_question "Message" "Title"
</pre>

=== POL_SetupWindow_menu ===

'''Arguments:'''

# Message.
# Title (often $TITLE).
# Available choices.
# 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:'''
<pre class="playonlinux code">
POL_SetupWindow_menu "What's your favorite color?" "$TITLE" "Red~Green~Blue" "~"
</pre>

=== POL_SetupWindow_menu_num ===

'''Arguments:'''

# Message.
# Title (often $TITLE).
# Available choices.
# 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:'''
<pre class="playonlinux code">
POL_SetupWindow_menu_num "What's your favorite color?" "$TITLE" "Red~Green~Blue" "~"
</pre>

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

=== POL_SetupWindow_menu_list ===

'''Arguments:'''

# Message.
# Title (often $TITLE).
# Available choices.
# Separator character (often ~ or -).
# 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:'''
<pre class="playonlinux code">
POL_SetupWindow_menu_list "What's your favorite color?" "$TITLE" "Red~Green~Blue" "~"
</pre>

=== POL_SetupWindow_checkbox_list ===

'''Arguments:'''

# Message.
# Title (often $TITLE).
# Available choices.
# 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:'''
<pre class="playonlinux code">
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
</pre>

=== 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:'''
<pre class="playonlinux code">
POL_SetupWindow_cdrom
</pre>

=== POL_SetupWindow_check_cdrom ===

'''Arguments:'''

# 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:'''
<pre class="playonlinux code">
POL_SetupWindow_check_cdrom "Data/32_icon.ico"
</pre>

=== POL_SetupWindow_InstallMethod ===

'''Arguments:'''

# 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:'''
<pre class="playonlinux code">
POL_SetupWindow_InstallMethod "LOCAL,CD,STEAM"
</pre>

== POL_Shortcut ==

'''Arguments:'''

# Executable filename.
# Launcher name (often $TITLE).
# Optional name of the icon to download from PlayOnLinux website.
# Optional executable arguments.
# Optional list of categories the program belongs to

'''Description:'''

Create a launcher in PlayOnLinux. The executable filename is looked up using a case insensitive [http://linux.die.net/man/7/glob 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 [http://standards.freedesktop.org/menu-spec/latest/apa.html main] and [http://standards.freedesktop.org/menu-spec/latest/apas02.html 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:'''
<pre class="playonlinux code">
POL_Shortcut "firefox.exe" "$TITLE"
</pre>

== POL_Shortcut_InsertBeforeWine ==

'''Arguments:'''

# Launcher name (often $TITLE).
# Command to add.

'''Description:'''

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

'''Example:'''
<pre class="playonlinux code">
POL_Shortcut_InsertBeforeWine "Jedi Knight II" "export __GL_ExtensionStringVersion=17700"
</pre>

== POL_Browser ==

'''Arguments:'''

# URL to open.

'''Description:'''

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

'''Example:'''
<pre class="playonlinux code">
POL_Browser "http://www.playonlinux.com"
</pre>

== POL_System_TmpCreate ==

'''Arguments:'''

# 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:'''
<pre class="playonlinux code">
POL_System_TmpCreate "$PREFIX"
</pre>

== POL_System_TmpDelete ==

'''Description:'''

Removes the script's temporary directory.

'''Example:'''
<pre class="playonlinux code">
POL_System_TmpDelete
</pre>

== POL_System_SetArch ==

'''Arguments:'''

# 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:'''
<pre class="playonlinux code">
POL_System_SetArch "auto"
</pre>

== POL_Call ==

'''Arguments:'''

# Function name.
# 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|Components and Functions]]).

'''Prerequisite:'''

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

'''Example:'''
<pre class="playonlinux code">
POL_Call POL_Install_vcrun6
</pre>

== Wine-related functions ==

=== POL_Wine_SelectPrefix ===

'''Arguments:'''

# 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:'''
<pre class="playonlinux code">
POL_Wine_SelectPrefix "$PREFIX"
</pre>

=== POL_Wine_PrefixExists ===

'''Arguments:'''

# 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:'''
<pre class="playonlinux code">
if [ "$(POL_Wine_PrefixExists "$PREFIX")" = "False" ]
then
# The préfixe doesn't exist
fi
</pre>

=== POL_Wine_PrefixCreate ===

'''Arguments:'''

# 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:'''
<pre class="playonlinux code">
POL_Wine_PrefixCreate "1.3.4"
</pre>

=== 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:'''

# 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:'''
<pre class="playonlinux code">
POL_SetupWindow_VMS "128"
</pre>

=== Set_OS ===

'''Arguments:'''

# Windows version to emulate.
# 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:'''
<pre class="playonlinux code">
Set_OS "win2k"
</pre>

=== Set_Managed ===

'''Arguments:'''

# 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:'''
<pre class="playonlinux code">
Set_Managed "Off"
</pre>

=== Set_SoundDriver ===

'''Arguments:'''

# alsa/oss/esd.

'''Description:'''

Set the audio driver Wine will use.

{{Info|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:'''
<pre class="playonlinux code">
Set_SoundDriver "alsa"
</pre>

=== POL_Wine_Direct3D ===

'''Arguments:'''

# Setting to create/modify.
# New setting value.

'''Description:'''

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

'''Allowed values:'''

See [http://wiki.winehq.org/UsefulRegistryKeys WineHQ's Wiki].

'''Prerequisite:'''

The commands POL_Wine_SelectPrefix and POL_Wine_PrefixCreate must have been used beforehand.

'''Example:'''
<pre class="playonlinux code">
POL_Wine_Direct3D "UseGLSL" "disabled"
</pre>

=== POL_Wine_X11Drv ===

'''Arguments:'''

# Setting to create/modify.
# New setting value.

'''Description:'''

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

'''Allowed values:'''

See [http://wiki.winehq.org/UsefulRegistryKeys WineHQ's Wiki].

'''Prerequisite:'''

The commands POL_Wine_SelectPrefix and POL_Wine_PrefixCreate must have been used beforehand.

'''Example:'''
<pre class="playonlinux code">
POL_Wine_X11Drv "DXGrab" "Y"
</pre>

=== POL_Wine_DirectSound ===

'''Arguments:'''

# Setting to create/modify.
# New setting value.

'''Description:'''

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

'''Allowed values:'''

See [http://wiki.winehq.org/UsefulRegistryKeys WineHQ's Wiki].

'''Prerequisite:'''

The commands POL_Wine_SelectPrefix and POL_Wine_PrefixCreate must have been used beforehand.

'''Example:'''
<pre class="playonlinux code">
POL_Wine_DirectSound "HardwareAcceleration" "Emulation"
</pre>

=== POL_Wine_DirectInput ===

'''Arguments:'''

# Setting to create/modify.
# New setting value.

'''Description:'''

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

'''Allowed values:'''

See [http://wiki.winehq.org/UsefulRegistryKeys WineHQ's Wiki].

'''Prerequisite:'''

The commands POL_Wine_SelectPrefix and POL_Wine_PrefixCreate must have been used beforehand.

'''Example:'''
<pre class="playonlinux code">
POL_Wine_DirectInput "MouseWarpOverride" "force"
</pre>

=== POL_Wine_GetRegValue ===

'''Arguments:'''

# 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:'''
<pre class="playonlinux code">
VALUE="$(POL_Wine_GetRegValue "MouseWarpOverride")"
</pre>

=== Set_Desktop ===

'''Arguments:'''

# On/Off.
# Virtual desktop width (if it is enabled).
# 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:'''
<pre class="playonlinux code">
Set_Desktop "On" "1024" "768"
</pre>

=== Set_WineWindowTitle ===

'''Arguments:'''

# 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:'''
<pre class="playonlinux code">
Set_WineWindowTitle "$TITLE"
</pre>

=== 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:'''
<pre class="playonlinux code">
POL_Wine_InstallFonts
</pre>

=== 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:'''
<pre class="playonlinux code">
POL_Wine_SetVideoDriver
</pre>

=== POL_Wine_OverrideDLL ===

'''Arguments:'''

# Mode of override.
# 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:'''
<pre class="playonlinux code">
POL_Wine_OverrideDLL "native" "msvcrt"
POL_Wine_OverrideDLL "" "msvcrt" # To disable the DLL
</pre>

=== POL_Wine_OverrideDLL_App ===

'''Arguments:'''

# Executable name.
# Mode of override.
# 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:'''
<pre class="playonlinux code">
POL_Wine_OverrideDLL_App "firefox.exe" "native" "msvcrt"
POL_Wine_OverrideDLL_App "firefox.exe" "" "msvcrt" # To disable the DLL
</pre>

=== POL_Wine_WaitBefore ===

'''Arguments:'''

# 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:'''

# 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:'''
<pre class="playonlinux code">
POL_Wine_WaitExit "$TITLE"
</pre>

=== POL_Wine_reboot ===

'''Description:'''

Emulate a Windows reboot.

'''Prerequisite:'''

The commands POL_Wine_SelectPrefix and POL_Wine_PrefixCreate must have been used beforehand.

'''Example:'''
<pre class="playonlinux code">
POL_Wine_reboot
</pre>

== Debugging commands ==

=== POL_Debug_Init ===

'''Description:'''

Start debugging system.

'''Example:'''
<pre class="playonlinux code">
POL_Debug_Init
</pre>

=== POL_Debug_Message ===

'''Arguments:'''

# 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:'''
<pre class="playonlinux code">
POL_Debug_Message "Modifying config.cfg file."
</pre>

=== POL_Debug_Warning ===

'''Arguments:'''

# 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:'''
<pre class="playonlinux code">
POL_Debug_Warning "File config.cfg did not exist, creating one."
</pre>

=== POL_Debug_Error ===

'''Arguments:'''

# 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:'''
<pre class="playonlinux code">
POL_Debug_Error "Error while modifying config.cfg file"
</pre>

=== POL_Debug_Fatal ===

'''Arguments:'''

# Message.

'''Description:'''

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

'''Prerequisite:'''

The command POL_Debug_Init must have been used beforehand.

'''Example:'''
<pre class="playonlinux code">
POL_Debug_Fatal "Error while modifying config.cfg file"
</pre>

'''Previous:''' [[Scripting - Chapter 10: Script Translation|Chapter 10: Script Translation]]

[[Category:Scripting]]

Scripting - Chapter 8: My First Real Script

2015-03-22T15:17:27Z

Petch: Remove POL_Debug_Init from example script, it is secondary to the example and only introduced in next chapter

Do you feel ready to write your first complete script? Yes? Let's go! Your goal is to try to write this script by yourself.

== Instructions: ==

For this exercise, we will work on '''Mozilla Firefox''' (Windows version). It is freely available for download.

=== Installation methods ===

Two methods of installation should be supported: '''LOCAL''' and '''DOWNLOAD'''

Since Mozilla Firefox must be downloaded from mirror servers, I'll give you the address of the mirror server you should use:

http://ftp.mozilla.org/pub/mozilla.org/firefox/releases/36.0/win32/en-US/Firefox%20Setup%2036.0.exe

''This link will download Firefox version 36.0.''

=== Name of the executable ===

The executable to pass to the '''POL_Shortcut''' command is: '''firefox.exe'''.

=== List of useful commands ===

To make your task easier, here are the commands that you'll need (in usage order):

<pre class="playonlinux code">
#!/usr/bin/env playonlinux-bash
[ "$PLAYONLINUX" = "" ] && exit 0
source "$PLAYONLINUX/lib/sources"
POL_SetupWindow_Init

POL_SetupWindow_presentation
POL_System_TmpCreate
POL_SetupWindow_InstallMethod
if [ "$INSTALL_METHOD" = "LOCAL" ]
then
POL_SetupWindow_browse
elif [ "$INSTALL_METHOD" = "DOWNLOAD" ]
then
cd
POL_Download
fi
POL_Wine_SelectPrefix
POL_Wine_PrefixCreate
POL_SetupWindow_wait
POL_Wine
POL_System_TmpDelete
POL_Shortcut

POL_SetupWindow_Close
exit
</pre>

== It's your turn now! ==

Additional arguments may be required, check the previous chapters. You should now have all the necessary information to achieve this task. Try to complete the script as much as possible by yourself. Once you're done, you can check the solution below.

== Correction ==

Here's a working script:

<pre class="playonlinux code">
#!/usr/bin/env playonlinux-bash
[ "$PLAYONLINUX" = "" ] && exit 0
source "$PLAYONLINUX/lib/sources"

POL_SetupWindow_Init

POL_SetupWindow_presentation "Mozilla Firefox" "Mozilla" "http://www.mozilla.com" "YourNickname" "MozillaFirefox"

POL_System_TmpCreate "MozillaFirefox"

POL_SetupWindow_InstallMethod "LOCAL,DOWNLOAD"

if [ "$INSTALL_METHOD" = "LOCAL" ]
then
POL_SetupWindow_browse "Please select the installation file to run." "Mozilla Firefox installation"
INSTALLER="$APP_ANSWER"
elif [ "$INSTALL_METHOD" = "DOWNLOAD" ]
then
cd "$POL_System_TmpDir"
POL_Download "http://ftp.mozilla.org/pub/mozilla.org/firefox/releases/36.0/win32/en-US/Firefox%20Setup%2036.0.exe"
INSTALLER="$POL_System_TmpDir/Firefox Setup 36.0.exe"
fi

POL_Wine_SelectPrefix "MozillaFirefox"
POL_Wine_PrefixCreate

POL_SetupWindow_wait "Installation in progress." "Mozilla Firefox installation"
POL_Wine "$INSTALLER"

POL_System_TmpDelete

POL_Shortcut "firefox.exe" "Mozilla Firefox"

POL_SetupWindow_Close
exit
</pre>

The tighter the resemblance of your script with this one, the better your understanding of scripting. The exact messages used are not important, what matters is that you used all the functions in your own script.

You can try to adapt this code to the installation of other programs, but keep in mind that some programs do not work with the default settings of Wine, and that additional functions may be required. Wine technology is not perfect, so some programs may not work no matter how hard you will try.

The test reports available from [https://appdb.winehq.org/ appdb.wineHQ.org] may prove useful to you.

== Ok, I'm done, can I write PlayOnLinux scripts now? ==

Sadly not yet, you've learned to write "basic" scripts, but additional requirements need to be taken care of, like allowing for localization or debugging. We'll see that in the next chapters.

'''Previous:''' [[Scripting - Chapter 7: Installation Media|Chapter 7: Installation Media]]

'''Next:''' [[Scripting - Chapter 9: Standardization|Chapter 9: Standardization]]

[[Category:Scripting]]

Scripting - Chapter 9: Standardization

2015-03-22T15:16:09Z

Petch: Modify hash-bang lines in accordance to playonlinux-bash tip

== Standardization, what is this thing? ==

To improve script readability, maintainability, debugging, and translation, scripts are standardized. This means that things need to be added or modified so that scripts will look and behave in a similar fashion.

Let us go over the details...

== Make your script available under Mac OS X using PlayOnMac ==

It may be useful to clarify (for those who would not know) that PlayOnLinux and PlayOnMac are really the same software, sharing the same code. Only the name changes depending on the operating system. So, making your script available to PlayOnMac users can be very easy. You just have to check that your script runs fine under Mac OS X. Even if you don't have any Mac OS X at hand, for small and simple software one can expect that, if it works correctly under GNU/Linux, there's a 99% probability that it will also work under Mac OS X.

To make your script available under Mac OS X, check the box "PlayOnMac compatible" of the new script submission form of the PlayOnLinux website. Read more here:

* [[How to Contribute a Script|How to Contribute a Script]]

== Standardization; let's begin ==

First, we shall be introduced to several items regarding standardization in scripts.

=== The $TITLE variable ===

You should assign the variable '''$TITLE''' with the name of the script, and use it every time the name of the script is required.

'''Example:'''
<pre class="playonlinux code">
#!/usr/bin/env playonlinux-bash
[ "$PLAYONLINUX" = "" ] && exit 0
source "$PLAYONLINUX/lib/sources"

TITLE="Mozilla Firefox" # Should be present in all your scripts

POL_SetupWindow_Init
...
POL_SetupWindow_presentation "$TITLE" "Mozilla" "http://www.mozilla.com" "YourNickname" "MozillaFirefox"
...
POL_Shortcut "firefox.exe" "$TITLE"
...
</pre>

Obviously, adapt it to the name of your script (that usually matches the name of the software it installs).
The variable '''$TITLE''' is notably required for the use of PlayOnLinux's debugging system.

=== Use the $TITLE variable for window titles ===

To avoid confusing the user with disparate window titles, it is recommended to use the variable '''$TITLE''' as window title.

'''Example:'''
<pre class="playonlinux code">
POL_SetupWindow_message "Message" "$TITLE"
POL_SetupWindow_browse "Message" "$TITLE"
POL_SetupWindow_wait "Message" "$TITLE"
</pre>

=== The $PREFIX variable ===

'''Example:'''
<pre class="playonlinux code">
#!/usr/bin/env playonlinux-bash
[ "$PLAYONLINUX" = "" ] && exit 0
source "$PLAYONLINUX/lib/sources"

TITLE="Mozilla Firefox"
PREFIX="MozillaFirefox"

POL_SetupWindow_Init
...
POL_SetupWindow_presentation "$TITLE" "Mozilla" "http://www.mozilla.com" "YourNickname" "$PREFIX"
...
POL_Wine_SelectPrefix "$PREFIX"
...
POL_System_TmpCreate "$PREFIX"
...
</pre>

=== Some informations about the script ===

It is recommended to provide some information near the beginning of the script, right after the #!/bin/bash line. Headers like this are standard practice in any script or source code, and should be applied as such.

'''Syntax:'''
<pre class="playonlinux code">
#!/usr/bin/env playonlinux-bash
# Date : (Year-month-day hour-min)
# Last revision : (Year-month-day hour-min)
# Wine version used :
# Distribution used to test : Distribution
# Author : Your nickname
</pre>

'''Example:'''
<pre class="playonlinux code">
#!/usr/bin/env playonlinux-bash
# Date : (2011-11-19 06-39)
# Last revision : (2011-11-19 06-39)
# Wine version used : 1.3.4
# Distribution used to test : Ubuntu 10.04 LTS
# Author : Your nickname
</pre>

=== Enable debugging ===

PlayOnLinux has a script debugging mode that must be enabled through a command. It is mandatory to enable it, even if you have no use for it; if some user experiences a problem with your script, it will allow him to sent a bug report to the PlayOnLinux website.

'''Syntax:'''
<pre class="playonlinux code">
POL_Debug_Init
</pre>

This command should be put right after the command '''POL_SetupWindow_Init'''.

== Some more information ==

Random information that does not fit into previous chapters.

=== It is forbidden to use sudo ===

Commands '''sudo''', '''su''', '''gksudo''', '''kdesu''' and similar are '''forbidden''' for the sake of security. However, if you really need '''sudo''' (for example to display hidden files from hybrid PC/MAC DVDs, using mount command), you can use the following command:

'''Syntax:'''
<pre class="playonlinux code">
POL_Call POL_Function_RootCommand "command using sudo; exit"
</pre>

=== Winetricks forbidden in scripts ===

Winetricks, or a similar script, is forbidden in PlayOnLinux scripts. Instead, you can use the very similar command '''POL_Call'''.

'''Syntax:'''
<pre class="playonlinux code">
POL_Call Script
</pre>

'''Example:'''
<pre class="playonlinux code">
POL_Call POL_Install_vcrun6
</pre>

The list of all the available scripts can be seen on [https://www.playonlinux.com/repository/?cat=100 this page].

== Scripts translation ==

We're almost done with scripts standardization. The only item left is script translations. This will be the topic of the next chapter.

'''Previous:''' [[Scripting - Chapter 8: My First Real Script|Chapter 8: My First Real Script]]

'''Next:''' [[Scripting - Chapter 10: Script Translation|Chapter 10: Script Translation]]

[[Category:Scripting]]

Scripting - Chapter 8: My First Real Script

2015-03-22T15:14:16Z

Petch: Modify hash-bang lines in accordance with playonlinux-bash tip

Do you feel ready to write your first complete script? Yes? Let's go! Your goal is to try to write this script by yourself.

== Instructions: ==

For this exercise, we will work on '''Mozilla Firefox''' (Windows version). It is freely available for download.

=== Installation methods ===

Two methods of installation should be supported: '''LOCAL''' and '''DOWNLOAD'''

Since Mozilla Firefox must be downloaded from mirror servers, I'll give you the address of the mirror server you should use:

http://ftp.mozilla.org/pub/mozilla.org/firefox/releases/36.0/win32/en-US/Firefox%20Setup%2036.0.exe

''This link will download Firefox version 36.0.''

=== Name of the executable ===

The executable to pass to the '''POL_Shortcut''' command is: '''firefox.exe'''.

=== List of useful commands ===

To make your task easier, here are the commands that you'll need (in usage order):

<pre class="playonlinux code">
#!/usr/bin/env playonlinux-bash
[ "$PLAYONLINUX" = "" ] && exit 0
source "$PLAYONLINUX/lib/sources"
POL_SetupWindow_Init
POL_Debug_Init

POL_SetupWindow_presentation
POL_System_TmpCreate
POL_SetupWindow_InstallMethod
if [ "$INSTALL_METHOD" = "LOCAL" ]
then
POL_SetupWindow_browse
elif [ "$INSTALL_METHOD" = "DOWNLOAD" ]
then
cd
POL_Download
fi
POL_Wine_SelectPrefix
POL_Wine_PrefixCreate
POL_SetupWindow_wait
POL_Wine
POL_System_TmpDelete
POL_Shortcut

POL_SetupWindow_Close
exit
</pre>

== It's your turn now! ==

Additional arguments may be required, check the previous chapters. You should now have all the necessary information to achieve this task. Try to complete the script as much as possible by yourself. Once you're done, you can check the solution below.

== Correction ==

Here's a working script:

<pre class="playonlinux code">
#!/usr/bin/env playonlinux-bash
[ "$PLAYONLINUX" = "" ] && exit 0
source "$PLAYONLINUX/lib/sources"

POL_SetupWindow_Init
POL_Debug_Init

POL_SetupWindow_presentation "Mozilla Firefox" "Mozilla" "http://www.mozilla.com" "YourNickname" "MozillaFirefox"

POL_System_TmpCreate "MozillaFirefox"

POL_SetupWindow_InstallMethod "LOCAL,DOWNLOAD"

if [ "$INSTALL_METHOD" = "LOCAL" ]
then
POL_SetupWindow_browse "Please select the installation file to run." "Mozilla Firefox installation"
INSTALLER="$APP_ANSWER"
elif [ "$INSTALL_METHOD" = "DOWNLOAD" ]
then
cd "$POL_System_TmpDir"
POL_Download "http://ftp.mozilla.org/pub/mozilla.org/firefox/releases/36.0/win32/en-US/Firefox%20Setup%2036.0.exe"
INSTALLER="$POL_System_TmpDir/Firefox Setup 36.0.exe"
fi

POL_Wine_SelectPrefix "MozillaFirefox"
POL_Wine_PrefixCreate

POL_SetupWindow_wait "Installation in progress." "Mozilla Firefox installation"
POL_Wine "$INSTALLER"

POL_System_TmpDelete

POL_Shortcut "firefox.exe" "Mozilla Firefox"

POL_SetupWindow_Close
exit
</pre>

The tighter the resemblance of your script with this one, the better your understanding of scripting. The exact messages used are not important, what matters is that you used all the functions in your own script.

You can try to adapt this code to the installation of other programs, but keep in mind that some programs do not work with the default settings of Wine, and that additional functions may be required. Wine technology is not perfect, so some programs may not work no matter how hard you will try.

The test reports available from [https://appdb.winehq.org/ appdb.wineHQ.org] may prove useful to you.

== Ok, I'm done, can I write PlayOnLinux scripts now? ==

Sadly not yet, you've learned to write "basic" scripts, but additional requirements need to be taken care of, like allowing for localization or debugging. We'll see that in the next chapters.

'''Previous:''' [[Scripting - Chapter 7: Installation Media|Chapter 7: Installation Media]]

'''Next:''' [[Scripting - Chapter 9: Standardization|Chapter 9: Standardization]]

[[Category:Scripting]]

Scripting - Chapter 6: The Filesystem

2015-03-22T15:12:41Z

Petch: Add some recommendations about testing resources before creating virtual drives, in accordance with #1027 (https://www.playonlinux.com/en/issue-1027.html)

There are a couple of good ways to manipulate your files and directories in Bash. We'll give you the most important commands for writing PlayOnLinux scripts.

== PlayOnLinux temporary directories ==

You can use a temporary directory for your script when it runs. To do that:

'''Syntax:'''
<pre class="playonlinux code">
POL_System_TmpCreate "NameOfTemporaryDirectory"
</pre>

'''Example:'''
<pre class="playonlinux code">
POL_System_TmpCreate "MozillaFirefox"
</pre>

It will create a variable '''$POL_System_TmpDir''' that will contain the path of the temporary directory. In this directory, you'll be free to store and modify all the files you want, for the whole script duration.

It is recommended for install scripts to first check (as far as possible) that all needed resources are available before prefix creation, and installation itself. POL_System_TmpCreate can become very useful to this end, because it doesn't require any prefix to already exist.

=== Delete the temporary directory ===

'''Syntax:'''
<pre class="playonlinux code">
POL_System_TmpDelete
</pre>

'''Example:'''
<pre class="playonlinux code">
POL_System_TmpDelete
</pre>

{{Info| it is futile to remove the files you created in the temporary directory before calling the POL_System_TmpDelete command.}}

== Other filesystem commands ==

=== Switching directory ===

'''Syntax:'''
<pre class="playonlinux code">
cd "path"
</pre>

'''Example:'''
<pre class="playonlinux code">
cd "/path/to/a/directory"
</pre>

<pre class="playonlinux code">
cd "$HOME" # Switch to user's personal directory
</pre>

<pre class="playonlinux code">
cd "$CDROM" # Switch to CD/DVD directory
</pre>

<pre class="playonlinux code">
cd "$POL_System_TmpDir" # Switch to temporary directory
</pre>

=== Removing a file or directory ===

{{WarningRed|This command is very dangerous. It could destroy all your files if you don't handle it properly. For example, if you decide to remove /home/user/.PlayOnLinux/tmp/ and that you inadvertently insert a blank between /home/user/ and .PlayOnLinux, you can say farewell to your documents. PlayOnLinux could not be held responsible for any mishandling on your part.''

'''SERIOUSLY; be diligent in your code quality.'''}}

'''Syntax:'''
<pre class="playonlinux code">
rm "filename"
</pre>

<pre class="playonlinux code">
rm -r "directory"
</pre>

'''Example:'''
<pre class="playonlinux code">
rm "$POL_System_TmpDir/file.txt"
</pre>

<pre class="playonlinux code">
rm -r "$POL_System_TmpDir/directory"
</pre>

If they are any remaining files and/or subdirectories in the directory you're removing, they'll also be removed for good.

=== Copying a file or a directory ===

'''Syntax:'''
<pre class="playonlinux code">
cp "SourceFile" "TargetFile"
</pre>

<pre class="playonlinux code">
cp -r "SourceDirectory" "TargetDirectory"
</pre>

'''Examples of file copy:'''
<pre class="playonlinux code">
cp "/home/user/file.txt" "/home/user/copy_of_file.txt"
</pre>

<pre class="playonlinux code">
cp "/home/user/file.txt" "/home/user/data/file.txt"
</pre>

<pre class="playonlinux code">
cp "$CDROM/file.txt" "$POL_System_TmpDir/file.txt"
</pre>

'''Example of directory copy:'''
<pre class="playonlinux code">
cp -r "/home/user/My Folder" "/home/user/Desktop/Test/"
</pre>

=== Moving or renaming a file or directory ===

'''Syntax:'''
<pre class="playonlinux code">
mv "/home/user/file.txt" "home/user/data.txt"
</pre>

<pre class="playonlinux code">
mv "/home/user/file.txt" "/home/user/Desktop/file.txt"
</pre>

<pre class="playonlinux code">
mv "/home/user/file.txt" "/home/user/Desktop/data.txt"
</pre>

1st command will rename the file file.txt to data.txt.

2nd command will move the file.

3rd command will move AND rename the file.

'''Previous:''' [[Scripting - Chapter 5: Wine|Chapter 5: Wine]]

'''Next:''' [[Scripting - Chapter 7: Installation Media|Chapter 7: Installation Media]]

[[Category:Scripting]]

Scripting - Chapter 1: Getting to know Bash

2015-03-22T14:58:55Z

Petch: Shorten sentences

== Introduction ==

You would like to create your own scripts for PlayOnLinux but you don't know squat about programming? This tutorial will explain the basics and you'll soon be a pro in ''playonlinuxian'' Bash.

== Bash? ==

Bash is a command interpretor (or "shell") in '''GNU/Linux''' and '''Mac OS X'''. It's the one appearing when you launch a terminal. It also allows you to make '''scripts'''. A '''script''' is a list of commands that your shell will execute one after the other.
PlayOnLinux has advanced functions in Bash to make the scripting process easier. Let's get acquainted with them.

== Requirements of every script ==

Every PlayOnLinux script must contain this boilerplate code:

<pre class="code playonlinux">
#!/usr/bin/env playonlinux-bash
[ "$PLAYONLINUX" = "" ] && exit 0
source "$PLAYONLINUX/lib/sources"

POL_SetupWindow_Init

POL_SetupWindow_Close
exit
</pre>

{{Warning|Do not copy the line numbers to the script. It is also highly recommended that you type it out by hand while learning, as opposed to copying and pasting, so as to become more familiar with the scripting language.}}

The above code may not make sense to you yet. We will explain what it does as we go.

During this tutorial, I will not repeat this code over and over in the examples, as you will need it in every script. Remember to always include it, otherwise your script won't work.

== Executing your script ==

Ask your favourite text editor to save your script, then use the function '''Run a local script''' from the '''Tools''' menu of PlayOnLinux.

== Script signing ==

PlayOnLinux uses digital signing (authentication) on scripts to certify that scripts have been validated by PlayOnLinux scripters. All the scripts available from the '''Install''' window of PlayOnLinux are validated.
Each time you will try to run a script that has not been validated by PlayOnLinux scripters, you will get a warning message telling you that the script has no valid signature (see screenshot below).

{{POL_SetupWindow_message|Run a local script|Warning!!

The signature of the script you are trying to run is NOT valid.

PlayOnLinux has not approved this script and will not be responsible for it. Please ensure you know what you are doing!
}}

You must click on '''Next''' button to get PlayOnLinux to show you the script source, then click on the '''I Agree''' checkbox, before you can (finally) run the script (see screenshot below).

{{POL_SetupWindow_licence|Run a local script|Here is the source code of the script. Check it carefully:
|<pre>#!/usr/bin/env playonlinux-bash
[ "$PLAYONLINUX" = "" ] && exit 0
source "$PLAYONLINUX/lib/sources"

POL_SetupWindow_Init

POL_SetupWindow_Close
exit</pre>
}}

{{Info|A real time saver for experienced script developers: If you're familiar with the command line interface, you may have guessed from the first line of the script above that PlayOnLinux scripts can also be run using the playonlinux-bash command.
Written as above, you can even set the executable bit on PlayOnLinux install scripts! }}

* [[Scripting - Chapter 2: Basic Functions|Chapter 2: Basic Functions]]

[[Category:Scripting]]