PlayOnLinux script functions reference

Legend of the arguments:
- red colour = mandatory argument
- orange colour = optional argument that becomes obligatory in specific cases. (an explanation is provided after the function's description)
- green colour = optional argument
- When an argument's description looks like this: "X/y/Z", it means the only possible values are X, y or Z (and the case must be respected).

Beginning & Ending

POL_SetupWindow_Init

Argument(s):
#1 = "Path to top.jpg"
#2 = "Path to left.jpg"
Description:
This is the function which creates the window seen by the user. The window is created blank so that you can display what you want in it with the POL_SetupWindow_* functions (except for POL_SetupWindow_Close which closes the window, of course).
This is why this function is almost necessary in every script (else you can't interact with the user). You only need one POL_SetupWindow_Init command per script because each new POL_SetupWindow_* command replaces the previous one's content in the window created by POL_SetupWindow_Init.
The first and second arguments are pictures to replace the default ones, for a nicer and more personalized script (of course, the replacement pictures must be related to the application installed by the script).
They have to be hosted on PlayOnLinux's website. In order to do so, send them by e-mail to Tinou. Their url will have the following structure: http://www.playonlinux.com/script_files/setups/your_script_name/*.jpg (which can be reduced to this in your script: $SITE/setups/your_script_name/*.jpg).
Requirements:
The left.jpg picture must be about 150x356px and the top.jpg picture must be about 60x60px. Moreover, the two arguments must be local paths so you have to retrieve the pictures locally before using them with POL_SetupWindow_Init.
Example:






POL_SetupWindow_Close

Argument:
none
Description:
It closes the setup window. To be used at the end of a script for instance.
Example:



POL_SetupWindow_Open [NOT RECOMMENDED]

Argument(s):
#1 = "Path to top.jpg"
#2 = "Path to left.jpg"
Description:
The same as POL_SetupWindow_Init. We recommend that you use POL_SetupWindow_Init instead (to remain coherent with the other scripts) as long as you don't have a good reason to use POL_SetupWindow_Open.
Example:



POL_SetupWindow_Quit [PAS RECOMMANDÉE]

Argument:
aucun
Description:
Cette fonction a le même effet que POL_SetupWindow_Close. Nous vous recommandons d'utiliser POL_SetupWindow_Close à la place (afin de rester cohérent avec les autres scripts) à moins que vous n'ayez une excellente raison d'utiliser POL_SetupWindow_Quit.
Exemple:

Informer l'utilisateur

POL_SetupWindow_presentation

Arguments:
#1 = "Nom de l'application"
#2 = "Nom du vendeur de l'application"
#3 = "Site web du vendeur"
#4 = "Nom du scripteur"
#5 = "répertoire du préfixe"
Description:
Cette fonction permet de faire la présentation de votre script d'installation. Il s'agît de la première fenêtre que verra l'utilisateur
Exemple:





POL_SetupWindow_free_presentation

Arguments:
#1 = "Titre de la fenêtre"
#2 = "Texte à afficher"
Description:
Cette fonction permet de présenter votre script de façon plus libre qu'avec POL_SetupWindow_presentation. Elle peut s'avérer utile si le modèle par défaut ne vous convient pas.
Exemple:





POL_SetupWindow_licence

Arguments:
#1 = "Text to be displayed"
#2 = "Title of the window"
#3 = "Path to the licence file"
Description:
POL_SetupWindow_licence displays a window with a frame containing third argument's content (typically, a licence file) and a checkbox to be ticked if you agree with the licence.
You can click on the "Next" button only when the checkbox is ticked thus the user has no choice but to agree with the licence if he wants the installation script to go on.
Example:





POL_SetupWindow_message

Arguments:
#1 = "Text to be displayed"
#2 = "Title of the window"
Description:
It simply displays a window with the given title and text. It is useful to inform the user about something (about what the installation script is going to do for example).
Example:





POL_SetupWindow_message_image

Arguments:
#1 = "Text to be displayed"
#2 = "Title of the window"
#3 = "Path to a picture"
Description:
It is the same as POL_SetupWindow_message with a picture (the one given as the third argument) on the left of the text to be displayed in addition.
The picture's format is not restricted, you can use a .png, .jpg, .gif, .ico, etc. You should keep the picture's dimensions under 250x250px.
The packages of POL contain a base set of pictures that you can use. They are in $PLAYONLINUX/themes/tango/ (the PLAYONLINUX variable designate the path to PlayOnLinux's installation directory, which usually is /usr/share/playonlinux/).
Example:

Asking the user something

POL_SetupWindow_browse

Arguments:
#1 = "Text to be displayed"
#2 = "Title of the window"
#3 = "Default file"
Description:
It allows you to ask the user where a given file is stored. For example, when the user already downloaded the installer of a program, you need to know the path to it. Just ask with POL_SetupWindow_browse then.
The absolute path to the file chosen by the user is stored in the $APP_ANSWER variable.
Examples:

Result:



Tip: When clicking on the browse button, the small file explorer will display the content of the current working directory of the script (i.e the content of $HOME/.PlayOnLinux by default, if you haven't changed the working directory previously in the script).
In order to change that, just add a command like the following one, before POL_SetupWindow_browse: cd /the/folder/you/want/to/be/displayed/



POL_SetupWindow_checkbox_list

Arguments:
#1 = "Text to be displayed"
#2 = "Title of the window"
#3 = "Elements of the list"
#4 = "Separation character"
Description:
It makes a list of elements with checkboxes so the user can choose several elements. The $APP_ANSWER variable contains the selected elements, separated with the separation character.
Example:
Result:



Tip:
In order to do different stuffs depending on what was checked by the user, you can use in your script a function similar to the following one:
Note: $1 is the variable which stores the first argument given when calling a function.

The use of the is_checked function is:
is_checked "an entry that was proposed in POL_SetupWindow_checkbox_list"
If we keep the previous example for POL_SetupWindow_checkbox_list,
is_checked "RPG" returns 1 (i.e "yes, RPG was checked")
and is_checked "Adventure" returns 0 (i.e "No, Adventure wasn't checked).
Then, you can easily do tests liketo do various things, depending on if the entry in $1 was checked or not.



POL_SetupWindow_games
Arguments:
#1 = "Text to be displayed"
#2 = "Title of the window"
Description:
This function displays a menu in which the entries are all the applications already installed in PlayOnLinux. The result stored in the $APP_ANSWER variable is the full name of the selected application.
Example:
Result:





POL_SetupWindow_menu

Arguments:
#1 = "Text to be displayed"
#2 = "Title of the window"
#3 = "Entries of the menu to be displayed, separated with the separation character"
#4 = "Separation character"
Description:
It displays a window with a menu in which the user can pick only one entry. The entry chosen by the user is stored in the $APP_ANSWER variable.
Example:
Result:





POL_SetupWindow_menu_list

Arguments:
#1 = "Text to be displayed"
#2 = "Title of the window"
#3 = "Entries of the menu to be displayed, separated with the separation character"
#4 = "Separation character"
#5 = "Entry selected by default"
Description:
This function is similar to POL_SetupWindow_menu except that the menu is displayed as a list of choices to be unfolded and that you can set an entry as the default choice.
Example:
Result:





POL_SetupWindow_menu_num

Arguments:
#1 = "Text to be displayed"
#2 = "Title of the window"
#3 = "Entries of the menu to be displayed, separated with the separation character"
#4 = "Separation character"
Description:
This function is similar to POL_SetupWindow_menu except that the $APP_ANSWER variable doesn't contain the name of the entry selected by the user but the number representing this entry.
0 is for the first entry, 1 is for the second entry, 2 is for the third entry, 3 is for the fourth entry, etc.
Example:
Result:





POL_SetupWindow_question

Arguments:
#1 = "Text to be displayed"
#2 = "Title of the window"
Description:
It allows you to ask the user a question for which the answer is yes or no. The user's answer ("TRUE" or "FALSE") is stored in the $APP_ANSWER variable.
Example:
Result:





POL_SetupWindow_textbox

Arguments:
#1 = "Text to be displayed"
#2 = "Title of the window"
#3 = "Default value to fill the text zone with"
Description:
This function displays a window with a text zone that the user can fill. For example, it allows you to ask the user a question for which the answer is NOT yes or no.
The content that the user entered in the text zone is stored in the $APP_ANSWER variable.
Example:

CD-ROM related

POL_SetupWindow_cdrom

Argument:
none
Description:
It asks where the CD is mounted. It proposes a list of choices made of the subdirectories of /media but the user can also specify any other directory. The result is stored in the $CDROM variable.
Example:





POL_SetupWindow_check_cdrom

Argument:
#1 = "File to be checked"
Prerequisite:
You must have run POL_SetupWindow_cdrom first.
Description:
It checks that the mount point given in POL_SetupWindow_cdrom contains the file you want. It's useful to check that the mount point selected by the user is the one that you actually expected.
The user will see the effect of this function only if the selected mount point doesn't contain the file given as argument (in this case, the effect is an error window).
Example:

Prefix related

select_prefix

Argument:
#1 = "Path to the prefix"
Description:
This function allows to select the prefix used by Wine or DOSBox.
Example:



POL_SetupWindow_prefixcreate

Argument:
none
Prerequisite:
The prefix of Wine to be created must have been defined first with the select_prefix function.
Description:
It creates a prefix of Wine by calling the POL_SetupWindow_normalprefixcreate function.
Example:





POL_SetupWindow_normalprefixcreate

Argument:
none
Prerequisite:
The prefix of Wine to be created must have been defined first with the select_prefix function.
Description:
It creates a prefix of Wine as would normally do Wine when run for the first time, i.e. it creates a prefix of Wine with the wineboot command.
We recommand to use POL_SetupWindow_prefixcreate instead (since it does exactly the same thing), to keep compatibility with POL < 3.4. Moreover, POL_SetupWindow_prefixcreate is shorter
Example:





POL_SetupWindow_specialprefixcreate

Argument:
none
Prerequisite:
The prefix of Wine to be created must have been defined first with the select_prefix function.
Description:
It creates a prefix of Wine as it used to be done with the older versions of Wine (with the wineprefixcreate command, like POL_SetupWindow_oldprefixcreate), plus it forces to set to their default value many registry keys concerning the user's directory in Wine and the Program Files directory.
It can be useful if you experience problems because of directories in the prefix being named in a different language than English.
However, you must be careful while using this function, it is dangerous (renames and moves several directories in the prefix) and may cause the installation to fail.
This is why you should always prefer to use POL_SetupWindow_prefixcreate, unless you encounter difficulties like directories of the prefix not named in English.
Example:





POL_SetupWindow_oldprefixcreate

Argument:
none
Prerequisite:
The prefix of Wine to be created must have been defined first with the select_prefix function.
Description:
It creates a prefix of Wine as it used to be done with the older versions of Wine, i.e. it creates a prefix of Wine with the wineprefixcreate command.
This is the POL_SetupWindow_prefixcreate function as it was before POL 3.4. It can be useful when the application that your script is installing will be used with an older version of Wine.
Example:





fonts_to_prefix

Argument:
none
Prerequisite:
The prefix of Wine must have been defined first with the select_prefix function.
Description:
This function copies the Microsoft fonts in the Wine directory.
Example:

Showing what's going on

POL_SetupWindow_wait [DEPRECATED]

Arguments:
#1 = "Text to be displayed"
#2 = "Title of the window"
#3 = "Command to be run"
Description:
This function is deprecated (it was used during the beta time of PlayOnLinux v3, before than POL_SetupWindow_wait_next_signal was implemented), use POL_SetupWindow_wait_next_signal instead.
It displays a window with a "waiting bar" while the command given as third argument is run. Once the command is finished, the installation script goes on.
Example:



POL_SetupWindow_wait_next_signal

Arguments:
#1 = "Text to be displayed"
#2 = "Title of the window"
Description:
It displays a "wait" window with a waiting bar while the command(s) placed between POL_SetupWindow_wait_next_signal and the following POL_SetupWindow_detect_exit command are run.
Once the command(s) is(are) finished, the installation script goes on.
Example:





POL_SetupWindow_detect_exit

Argument:
none
Prerequisite:
You must have run POL_SetupWindow_wait_next_signal first.
Description:
It detects when the command(s) or process(es) placed between POL_SetupWindow_wait_next_signal and this function is(are) finished. It's used typically when running the installer of a program.
Example:





POL_SetupWindow_pulsebar

Arguments:
#1 = "Text do be displayed"
#2 = "Title of the window"
Description:
This function creates a window containing a bar (called "pulsebar" because it evolves by pusles with the POL_SetupWindow_pulse function) to show the progress of what you want.
Once the pulsebar has been created, you can use the POL_SetupWindow_pulse function to make it evolve.
Examples:











POL_SetupWindow_pulse

Argument:
#1 = "Integer between 0 and 100"
Prerequisite:
A pulsebar must have been created first with the POL_SetupWindow_pulsebar function.
Description:
It sets the progress of the current pulsebar. The argument represents the absolute percentage of progress of the pulsebar.
It means that if your pulsebar is already filled at 40% and you want it to be filled and 50%, the argument must be "50" (and not "+10").
If you want to pass a relative percentage of progress as argument, it is possible by using variable.
In the same case than previously, the PULSE variable contains the progress of the puslebar so is equal to "40". Thus you can fill the pulsebar at 50% by calling POL_SetupWindow_pulse with "$(( PULSE + 10 ))" as argument.
Examples:











POL_SetupWindow_set_text

Argument:
#1 = "Text to be displayed"
Prerequisite:
A pulsebar must have been created first with the POL_SetupWindow_pulsebar function.
Description:
It displays additionnal text in the pulsebar window. It is usefull to inform the user about what is going on when the pulsebar progresses.
Examples:

Wine version related

POL_SetupWindow_install_wine

Argument:
#1 = "Wine version number"
Description:
It installs the Wine version given as the argument in $REPERTOIRE/WineVersions/ (like WineVersion would have done when asked to install the same version).
If this version is already installed in the user's system, it doesn't do anything (i.e it doesn't install it again).
Calling this function in a script allows you then to use Set_WineVersion_Assign or Use_WineVersion.
Example:





Set_WineVersion_Assign

Arguments:
#1 = "Wine version number"
#2 = "Application name"
Prerequisite:
The version of Wine given as first argument must have been installed first, using the POL_SetupWindow_install_wine command.
Description:
This function allows to set a specific version of Wine to be used to run the application given as second argument, instead of the default version used by PlayOnLinux (which can be defined in the "Environment" tab of the settings panel).
The application name given as second argument must be written exactly as the associated shortcut's name.
It means the application name must be the same as the content of the fifth argument of the POL_SetupWindow_make_shortcut command that created the application' shortcut.
Most of the time, the application concerned by the Set_WineVersion_Assign command is the application being installed by the script. So this command used to be placed at the end of the script, after the POL_SetupWindow_make_shortcut command(s).
NB: Every "Platinum" rated game in the Wine AppDB must be associated to a fixed version of Wine, because of regression issues between the different versions of Wine.
Example:



Use_WineVersion

Argument:
#1 = "Wine version number"
Prerequisite:
The version of Wine given as argument must have been installed first, using the POL_SetupWindow_install_wine command.
Description:
This function allows to set a specific version of Wine to be used during the installation of the concerned application.
This function shoud be used to do the installation with a version of Wine that is well known for working without troubles.
NB: Use the "--reset" value as argument to set back PlayOnLinux default version of Wine.
Example:

Wine Configuration

Set_Desktop

Arguments:
#1 = "On/Off"
#2 = "Width" *
#3 = "Height" *
Prerequisite:
The prefix of Wine must have been defined first with the select_prefix function.
Description:
This function enables or disables Wine's virtual desktop (which is disabled by default). If you choose to enable it, you must define the virtual desktop's width and height.
When Wine's virtual desktop is enabled, all the applications run by Wine appear in a window of which the width and height are the ones given respectively as second and first arguments.
It gives the same result as if the applications were run on a windows system with a screen of which the resolution is 1st argument x 2nd argument.
It can be useful, for instance, when an old application doesn't support your type of screen resolution (5:4, 16:9 or 16:10 or also since some applications will not run without this virtual desktop .
(*): Obligatory if the first argument is "On".
Example:



Set_DXGrab

Argument:
#1 = "On/Off"
Prerequisite:
The prefix of Wine must have been defined first with the select_prefix function.
Description:
This function defines if DirectX © can control the mouse's pointer (which is disabled by default).
It can be useful when some applications don't manage to directly grab the mouse's pointer in fullscreen mode, for example.
Example:



Set_GLSL

Argument:
#1 = "On/Off"
Prerequisite:
The prefix of Wine must have been defined first with the select_prefix function.
Description:
This function enables or disables the GLSL (OpenGL Shading Language) support for vertex and pixel shaders in Wine. It is enabled by default when it is possible.
GLSL support is sometimes required by application with very advanced graphic technics like recent games. And quite the reverse, some other old games work better without it (in this case, they use ARB shaders instead).
Example:



Set_Iexplore

Argument:
none
Prerequisite:
The prefix of Wine must have been defined first with the select_prefix function.
Description:
This function simulates the presence of Microsoft Internet Explorer 6 ©.
Wine provides an HTML rendering engine (Gecko, Firefox's engine) for application that needs such a thing to display web pages.
But sometimes, those applications only wants to use Internet Explorer's engine even though they could use any engine to display the web pages they want.
That's why Set_Iexplore can be useful.
Example:



Set_Managed

Argument:
#1 = "On/Off"
Prerequisite:
The prefix of Wine must have been defined first with the select_prefix function.
Description:
This function allows your window manager (KWin, Metacity, OpenBox, Enlightenment, etc) to control the application's window (which is disabled by default).
Example:



Set_OS

Argument:
#1 = "win2008/vista/win2003/winxp/win2k/winnt/winme/win98/win95/win31"
Prerequisite:
The prefix of Wine must have been defined first with the select_prefix function.
Description:
This function changes the version of the operating system simulated by Wine. The default version in Wine is winxp.
It can be useful since some applications work better with some specific simulated versions of windows.
Example:



Set_SoundBitsPerSample

Argument:
#1 = "8/16"
Prerequisite:
The prefix of Wine must have been defined first with the select_prefix function.
Description:
It sets the number of bits per sample in DirectSound, the part of the DirectX library which manages the sound.
The higher the number of bits per sample is, the higher the sound quality is.
The default value is "16" in DirectSound.
Example:



Set_SoundDriver

Argument:
#1 = "alsa/oss/esd"
Prerequisite:
The prefix of Wine must have been defined first with the select_prefix function.
Description:
This function defines the audio driver to be used by Wine.
Example:



Set_SoundEmulDriver

Argument:
#1 = "Y/N"
Prerequisite:
The prefix of Wine must have been defined first with the select_prefix function.
Description:
It lets you choose, depending on the argument ("Y" for yes and "N" for no), if the driver emulation must be activated in DirectSound, the part of the DirectX library which manages the sound.
DirectSound's driver emulation is disabled by default.
Example:



Set_SoundHardwareAcceleration

Argument:
#1 = "Full/Standard/Basic/Emulation"
Prerequisite:
The prefix of Wine must have been defined first with the select_prefix function.
Description:
This function sets the type of sound hardware acceleration in DirectSound, the part of the DirectX library which manages the sound.
DirectSound's default sound hardware acceleration is "Full".
Example:



Set_SoundSampleRate

Argument:
#1 = "48000/44100/22050/16000/11025/8000"
Prerequisite:
The prefix of Wine must have been defined first with the select_prefix function.
Description:
It sets the default sample rate in DirectSound, the part of the DirectX library which manages the sound.
DirectSound's default sample rate is "44100".
Example:

Other useful functions (visible effect for the user)

POL_SetupWindow_download

Arguments:
#1 = "Text to be displayed"
#2 = "Title of the window"
#3 = "URL"
Description:
It downloads in the current directory what you indicated in the url.
Example:





POL_SetupWindow_make_shortcut

Arguments:
#1 = "Prefix's folder"
#2 = "Application's folder"
#3 = "Executable to be run"
#4 = "Icon file's name"
#5 = "Shortcut's name"
#6 = "Ignored" *
#7 = "Argument(s) to be passed when running the executable"
Description:
This is the function that creates the shortcut in PlayOnLinux's main window to run the application that your script is installing.
It can also create the same shortcut on the user's desktop or in his applications menu, depending on what the user will choose.
About the icon, similarly to the pictures for POL_SetupWindow_Init, it must be hosted on PlayOnLinux's server. To do so, send it by e-mail to Tinou.
About the seventh argument, its content is argument(s) for the executable (i.e the same argument(s) you could use when running normally the application on Windows) and not Unix type argument(s) for Wine.
(*): The sixth argument becomes obligatory if you want to specify a seventh one. But since POL ignores the sixth argument's content (this argument is still present only for a backward compatibily purpose), just let it blank.
Example:





POL_SetupWindow_reboot

Argument:
none
Prerequisite:
The prefix of Wine must have been defined first with the select_prefix function.
Description:
This function tells Wine to simulate the reboot of Microsoft Windows (with the wineboot command). It is usefull when the application you have just installed requires to restart the computer before being usable.
Example:





POL_SetupWindow_missing

Argument:
none
Prerequisite:
You must have run at least one check_one command.
Description:
This function warns the user if the program(s) checked previously by the check_one command(s), aren't installed on his system.
If everything required is present, the user will not see anything and the remaining part of the script will be run as normal.
But if one or more program(s) is(are) missing, a message window will prompt the user what program(s) is(are) missing then the installation script will be stopped.
So the combination check_one/POL_SetupWindow_missing is useful to check that a specific program you need in your script is installed on the user's system.
Example:

If oowriter and unrar aren't installed:

Other useful functions (invisible effect for the user)

cfg_check [DEPRECATED]

Argument:
none
Description:
This function is deprecated so you shouldn't use it anymore.
It checks that PlayOnLinux's dependancies (ar, cabextract, convert, unzip, wget, wine and xterm) are installed and that your 3D acceleration is enabled.
If everything required is present, the user will not see anything and the remaining part of the script will be run as normal.
But if one or more program(s) is(are) missing, a message window will prompt the user what program(s) is(are) missing then the installation script will be stopped.
It used to be used at the beginning of the scripts, right after the obligatory piece of code that loads PlayOnLinux's functions.
Example:



check_one

Arguments:
#1 = "Program to be checked"
#2 = "Package that contains the program"
Description:
It checks that the program you want is available on the user's system (with the which command).
The first argument must be the command you would use to run the program from a terminal.
If the given program is installed, then nothing happens. But if it isn't installed, it makes the MANQUE variable equal to "true" and fills the MISSING variable with the first and second arguments of check_one.
These variables are intended to be used then by the POL_SetupWindow_missing command to tell the user what is lacking. So you should always use the POL_SetupWindow_missing command after using one or more check_one command(s).
So the combination check_one/POL_SetupWindow_missing is useful to check that a specific program you need in your script is installed on the user's system.
Example:

Result: If oowriter isn't installed:



clean_tmp

Argument:
none
Description:
It removes the whole content of $REPERTOIRE/tmp/ (i.e the content of $HOME/.PlayOnLinux/tmp/).
Example:



Read_autorun

Argument:
none
Prerequisite:
You must have run POL_SetupWindow_cdrom first.
Description:
It searches the CD/DVD-ROM (the $CDROM variable) for an autorun executable and gives the path from the root to the autorun executable if it finds one.
NB:Since Read_autorun sends this path directly to the standard output (like "echo something"), you had better call it like this: "SOME_VARIABLE=$(Read_autorun)" if you want to be able to use this path later in the script.
Example:

Result: