App Scripts Guide
Index
Chapter 1 - Introduction
Chapter 2 - How to create a new app script
Chapter 3 - Adding Registry keys
Chapter 2 - Creating a new app script
Introduction
Now it's time to learn how you can create an app script to add your favourite programs to a boot disk project.
There are several details that you need to take into account when creating a new app script - most of these details are not specific to winbuilder because they depend exclusively on the conditions that you need to provide in order to allow the program to run in the target operative system.
On this tutorial we will pick on a simple program that doesn't require anything special to run and use it as example to demonstrate some of the basic functions of app scripts.
This will cover the steps used to create shortcuts, show how to attach files to your script and also explain a bit how the coding part works.
This tutorial is suited for programs that are already portable.
On later tutorials we will teach how you can write your registry keys along with other more advanced techniques that explore the full potential of app scripts.
If something is not clear on this tutorial, please post a message so that we can correct or explain in more detail how everything works.
How can I create my app script?
There are a few different ways to create your scripts, we'll mention them here so that you can use the one you prefer best.
- Text Editors
- Internal wb Tools
Text editors:
As any other script - you can use any standard text editor like the windows notepad for example.
Your app scripts are usually placed inside "%BaseDir%\Projects\MyProject\Apps"
Where %BaseDir% is the folder where your "WinBuilder.exe" is placed and "MyProject" is the project that you want to build.
For plain text edit, here are some good and free options.
Notepad ++ http://notepad-plus.sourceforge.net/
SciTE http://www.scintilla.org/SciTE.html
This method is only recommended for users who already know their way around the app scripts codings. If you're just starting up fresh then it is recommended to use the internal wb tools since they contain good features that help you make a new script.
----------------------------------------
Internal tools
Inside WinBuilder you find a tool to create a new app script from scratch, let's explain how it works.
Where to find it?
Open up WinBuilder.exe and click on the "Advanced" button, select "Create script"
This is how the Create script tool looks like:
------------------------------
First step - Path
The first step to start is selecting the folder where you want your new app script to be placed.
This window will display all folders inside the projects folder. Open the folder corresponding to the project that you are using and look for the "Apps" folder.
It's not an obrigation to place your new script inside this Apps folder but we use it as a way to keep things organized. You can also place your script inside a subfolder of Apps that better describes the category in which it should be placed.
------------------------------
Second step - Filename
Now we will choose the filename for your new script.
The only thing needed to be done here is writing the filename on the appropriate box
You don't need to write the extension .script since it will be added automatically, for example "Test" will create an app script called "Test.script" on your disk.
------------------------------
Third step - Attach files
Now let's add files inside your script.
On this case we are using as example a very simple program that only uses a few files and doesn't require any registry entries or special DLL's on the window folder - we will talk about these cases over the next tutorials.
Click on the "Add files" tab:
Next, click on the + (plus) button and a dialog box will allow you to select the files that you want to include on this list.
You can also remove files when you click on the - (minus) button.
One limitation: this tool will not allow to include subfolders and will only add files.
Later ahead we will mention how to include subfolders inside your app scripts.
------------------------------
Fourth step - Write the code
This the most important step of them all.
Many people usually think that writing an app script is complicated but after reading this tutorial you will surely think otherwise.
This is our code window:
The code window already contains by default the code that you need.
The only thing you need to change on this case are all words that start with "My"
Change these words with the respectives ones that fit your app script.
Let's pick on the example of NotePad++ and show how these words should be changed.
My Program (title) --> Notepad++
my Program description (description) --> Open source text editor
myProgram (Title of the shortcut) --> Notepad++
myProgram.exe (filename of the shortcut executable) --> notepad++.exe
myProgramFolder (folder where the files will be placed) --> NotePad++
This means that our end result should look like this:
Let's now explain what each line of code means so that you can understand how things are done.
[main] Title=Notepad++ Description=Open source text editor Selected=True Level=5 Version=1
The [main] section is where the generic information about this script is stored.
- Title is the name that will be displayed on the WinBuilder script list - it doesn't need to be the same as the filename.
- Description is a small explanation to provide more informations.
- Selected value is a way to specify if whether this script should run or not when you build the project.
- Level - each project will execute scripts based on the number of their level (1..10), app scripts use 5 as default
- Version is the current version of this script to help other users to know when a new version is available.
---------------------------------
Next is the [variables] section, as other code languages - you can use variables inside your code that will then be replaced by the respective value that you declare inside this section.
A small apart regarding how variables work. WinBuilder has four levels of possible variables and all of them can be used inside your code.
- WinBuilder.exe - the script engine will add variables containing information about your machine
- WinBuilder.ini [variables] - variables placed here will affect all projects and all scripts
- script.project [variables] - variables on the project file will be available on all scripts inside the project
- Test.script [variables] - variables inside the script will be available inside the script
More informations: http://boot-land.net..._variables.html
On the case of app scripts we will define the variables that apply to your program
[variables] %ProgramTitle%=Notepad++ %ProgramEXE%=notepad++.exe %ProgramFolder%=Notepad++
- %ProgramTitle% is the variable that will define how the program should be named (used on shortcut title)
- %ProgramEXE% will point to the filename that will be launched by the shortcut
- %ProgramFolder% is the folder name where your program files will be placed
-------------------------------------------------
We finish with the [process] section - this where the code inside the script will be executed by default, for simple app scripts we only need two lines that don't require any editing because they will use the values mentioned on the [variables] section.
[process] Add_Shortcut unpack
Explaining how Add_Shortcut works
Add_Shortcut is a generic command that will create a shortcut. On most projects it will create this shortcut inside the Start Menu and will place it inside a subfolder that has the same name as the folder where the respective script is placed.
You don't need to worry where the shortcut will be placed because each project will create them in the best possible way.
By default you should leave this command without changes to be as generic as possible.
Only if required, here are the possible options for this API command.
The first parameter will define the type of shortcut
Add_Shortcut,Desktop (places a icon on the desktop)
Add_Shortcut,StartMenu (default action, will place the icon the StartMenu)
Add_Shortcut,QuickLaunch (Adds the icon the Quick Launch bar)
Add_Shortcut,SendTo (Will add the icon on the right-click menu "Send To")
This seems that it was coded exclusively to work with the explorer shell but it wasn't. If the user prefers (for example) to use xoblite, then the Add_Shortcut will either use the equivalent shortcut or simply ignore the request if it is not possible to execute.
Full syntax of Add_Shortcut
This is a very complete command and you can simply use it without need for parameters or decide to forge your shortcut to work under very specific conditions where supply the needed settings.
Add_Shortcut,[Type],[Folder],[FullFileName],[Title],[Work Folder],[Parameters],[IconFile( .ico .exe)],[StartMode(1, 2, 3, or 4)]
- [Type] - can be Desktop, StartMenu, QuickLaunch, SendTo
- [Folder] - fill this value if you want to force the shortcut to be placed on a specific folder
- [FullFilename] - this switch is used if you want to create a shortcut different of %program_exe%
- [Title] - set your own title for this shortcut
- [Work folder] - decide the value for the work folder
- [Parameters] - if you want to launch the exe with command line parameters, write them here
- [Iconfile] - you can specify what the icon to be used on the shortcut
- [StartMode] - Value to set how the window of the launched program should be. 1=Show; 2=Show_Minimized; 3=Show_Maximized; 4=Hide
One note:
As you may note - commas (,) are used to split the options of the command - if you need to use a comma on the title of a shortcut or something similar then you can use the special character #$c that will be replaced by a comma when the script is running.
Here is the list of all possible special characters:
Parameter Replace With Read as in english , #$c Commma space #$s Space " #$q Quote % #$p Percentage break line #$x Starts a new line
Explaining how unpack works
unpack is a command that is used to extract the program files from your script onto a program folder on your boot disk project.
If you followed the instructions that were used on our example above then all you need to do at this moment is simply call "unpack" and this command will create a new folder inside the target program files folder and extract all files inside your script onto this newly created folder.
---------
But let's go into more details about this command so that you can also use it for any special situation where you need things to work in a more specific manner.
Script allow to attach files inside them and also to organize this files using a sort of folders, this allows you to choose which files or folders to extract as needed.
The unpack command will use the folder called "Folder" as default place to keep all files that you attached using the "Create script" tool
--------------------------
How to unpack from another folder?
Use this syntax:
unpack,AnotherFolder
Where AnotherFolder is the name of the folder to be extracted
How to include a huge number of files or subfolders?
The best solution is packing all files inside a compressed file. The supported formats are .ZIP .RAR and .7z
To use this feature you will need to include the folder name where this compressed file is found.
For example
unpack,folder,myCompressedFile.zip
How to use a SFX with unpack?
This is an option that will allow you to compress all your program files inside a self-extractable exe file.
How does it work?
First it will extract your SFX file to the respective program folder, then it will run the SFX so that all files are extracted.
You can also include switches to make this sfx become silent.
A good example to explain how this works can be found here: http://livexp.boot-l...are_free.script
The code for the above example is:
unpack,folder,asquared_free.exe,"-y"
Last step - Create your script
If everything is ready then it's time to finally create your script.
At this moment all you need to do is press this button:
The script will be created using the settings that you have defined.
--------------------
Close this tab and press the Refresh button to view you script listed on the WinBuilder script list.
-----------------------------------------
In conclusion..
I hope this tutorial helps you understand how you can create your first app script.
The Add_Shortcut and Unpack commands are very simple to use and also very complete whenever you need a special function.
More examples of app scripts to help you understand this lesson are available here: http://livexp.boot-l...et/LiveXP/Apps/
The next tutorials will focus more advanced methods but I think that this is all you really need for simple programs.
Edited by Nuno Brito, 24 August 2008 - 09:59 PM.
