wbcommonapi

WinBuilder

previous page next page

WinBuilder's Scripting "API"

The WinBuilder Scripting API (a.k.a. the "common" API) is a means to extend and add functionality to a WinBuilder project and to make application (and other) scripts more compatible across multiple projects. WinBuilder also provides a means to integrate these "macros" into the internal editor help system, and make them act and "feel" just like internal WinBuilder Commands

The current API project is still in a bit of "flux", however most commands have been around for some time and will continue to be supported in future versions.

A process to better manage the API is also under development.


How It works

The WinBuilder Scripting API is a set of macros, nothing more nothing less.

What makes it valuable is that the WinBuilder community has decided to use these same macro definitions across many projects. This allows individual scripts, especially for Applications, to be more easily used in different projects. If you know how to create a macro in a script, than you can easily figure out how the API is used. What makes this API process different than a script file containing ordinary macros is how it is "hooked into" the WinBuilder process.

Note: A WinBuilder projects does not need to use the API to be a valuable project. In fact, there are some projects that may not use ANY API, or may use the the API process to implement their own API definition.
It is also important to note that the API just defines the Macro names and interface conventions. Individual projects may need to use a different internal implementation of the API, and that is perfectly OK - as long as the API follows the syntax and functionality defined.

Hooking the API into your project

We will start by looking at what makes the API "turn on". If you look in script.project file you will see the following lines and Variables being defined. This first variable 

//-- API File and Some Api project settings
%API%=%ProjectDir%\Build\Common_Api.script

tells WinBuilder what file contains the API, while this variable definition 

%API_TYPE%=2

is used to tell the Common APIi that we are project type 2 (Vista/Win7). This is used internally in the API to make decisions about which implementation should be used when a command is called. Here are the currently defined type values

  • 1 =Gena/LiveXP/NativeEx/PE1 based projects
  • 2 =Vista/Win7 based projects
  • 98=Windows98 based projects

The following line defines the name of the "section in common_api file that contains the actual definitions of the API commands. In other words, what section has the code to be run when you use any given macro (e.g. Add_shortcut etc.). We will look at that section of the Common API later. 

%APIVAR%=ApiVar

There are some additional lines that should be added to the script.project file which help WinBuilder find and display items for the magic wand (i.e. WinBuilders internal help system). This is displayed in a pull-down menu, where the variable, as an example, 

%APIDEF%=API

tells WinBuilder what to display for the top level API menu, and the variable 

%APISUBDEF%=_Calculate,AddAutoRun,*AddPostConfig,*AddPreConfig,*AddToPEShell,Add_Shortcut,
     Add_Asso,*Add_Pin,Add_URL,Arch,Associate_File,Ask_License,CapiC,*CopyDrv,CopyProgram,
     ExtractAndRunc,Others,*ReadENV,Registry,Require_File,*RequireSysFile,RunFrom,Unpack,Variable

tells WinBuilder what the commands are in the API that have internal templates. (This would be all on one line inside the script file) In addition to defining the various variables, we need one last command to activate them at run time. 

[Process]
AddVariables,%API%,ApiVar,GLOBAL

This command loads all commands in the common_api.script from the [ApiVar] section we mentioned above as GLOBAL variables. We will get into this a bit more later, but know that this needs to happen in order for scripts to use the Common API commands.

The Common_API.script file

Ok now on to Common_API.script. As mentioned above, we have defined several variables, and there is typically an [Api_Def] section in the script file. For example: 

[Api_Def]
%APIVAR%=ApiVar
%APIDEF%=API
%APISUBDEF%=_Calculate,AddAutoRun,*AddPostConfig,*AddPreConfig,*AddToPEShell,Add_Shortcut,
     Add_Asso,*Add_Pin,Add_URL,Arch,Associate_File,Ask_License,CapiC,*CopyDrv,CopyProgram,
     ExtractAndRunc,Others,*ReadENV,Registry,Require_File,*RequireSysFile,RunFrom,Unpack,Variable

This section doesn't do anything! It is simply a reminder that you need to set these variables in your own script.project in order to use the Common API. Editing this section will not do anything!

On the other hand, the [!ApiVar] Section is very important. This is the section we defined with the line %APIVAR%=ApiVar back in script.project and loaded into memory with the command 

[Process]
AddVariables,%API%,ApiVar,GLOBAL

This is the part where the commands actually get mapped to their functions. i.e. we create the macro definitions. For example: 

[ApiVar]
%ToRoot%=
%CapiArchApi%=
%CapiAdd_ShortcutProcess%=
%CapiSubFoldersToRoot%=Falsy
%CapiNoShortcutSubfolders%=
%CapiBSExplorerFix%=Nope
%CapiNowarnPreserveNodebugwarn%=
%reg_temp%=wb-hive
%reg%=%reg_temp%
%CopyMui%=Off
%WarnWhenSetApi%=False
%Shc_Mode%=0
_Calculate=Run,%API%,Calculate
Add_Asso=Run,%API%,Association%API_TYPE%
Add_Shortcut=Run,%API%,AddShortcut%Capi_Shortcut_TYPE%%CapiAdd_ShortcutProcess%
Add_Pin=Run,%Api%,Add_Pin_Process%API_TYPE%
Add_URL=Run,%API%,Add_URL%API_TYPE%
AddAutoRun=Run,%API%,Add_Auto_Run%API_TYPE%
AddPostConfig=Run,%API%,Add_Post_Config%API_TYPE%
----ETC ETC ETC---------

An easy way to think of it is that whenever WinBuilder sees the command _Calculate in any script it internally replaces the _Calculate with 

Run,%API%,_Calculate

which will execute the [_Calculate] section in %API% which we defined earlier in script.project as being %ProjectDir%\Build\Common_Api.script

Defining the menu entries (syntax templates) for the magic wand

The definitions are contained (as mentioned above) in the [API] Section. Note that line doesn't actually do anything - its just a reminder to developers that the next sections are menu definitions and not actually functions.

Following that line, you will see a bunch of sections all with names corresponding to the submenus we defined in the %APISUBDEF% variable in our project. this is where we actually define the commands to be displayed in the APIs magic wand menu. For example: 

[API]
[_Calculate]
Full Syntax="//_Calculate,AutoIT Command(expression),ReturnVar(without %)"
Note="//Always use simple quote in expression ,use `#$c` in place of the comma" and use %ReturnVar% (with %) as result in your code . See AutoIT doc"
-=
MsgBox="_Calculate,MsgBox(2#$c'Test Calculate'#$c'Choice:'#$c5),Choice"
InputBox="_Calculate,InputBox('Question'#$c 'Where were you born?'#$c 'Planet Earth'#$c ''#$c -1#$c -1#$c -1#$c -1),Answer"

[Add_URL]
Default Value="Add_URL,Favorites,<filename>,<webaddress>"
Full Syntax="Add_URL,[Favorites][Links]<TargetPath>,<filename>,<webaddress>,[UrlDll][None]<url icon address>,[None]<IconIndex>,[None]<HotKey>"
-=
Sample Favorites="Add_Url,,Google.url,http://www.google.com"
Sample Links="Add_Url,Links,Google.url,http://www.google.com"
-=
Sample Favorites SubF="Add_Url,Favorites\My Folder,Google.url,http://www.google.com"
Sample AnyFolder="Add_Url,%target_win%,Google.url,http://www.google.com"
Sample Icon Url.dll="Add_Url,,Google.url,http://www.google.com,UrlDLL"
Sample Icon Ico="Add_Url,,Google.url,#$psystemroot#$p\system32\blabla.ico"

[*Add_Pin]
Full Syntax="//Add_Pin,Type,Order(0,1,2,..,8,9), path\)FileName,Title,Work Folder,Parameters,path\)IconFile#$cIconIndex,StartMode=(1,2,3)#$cHotKey,ToolTipText"
Default Value="Add_Pin,StartMenu,,%PE_Programs%\%ProgramFolder%\%ProgramExe%,%ProgramTitle%"
-=
Sample File="Add_Pin,Taskbar,,#$pSystemRoot#$p\calc.exe"
Sample Lnk="Add_Pin,StartMenu,0,"$Desktop\My Computer.lnk""
-=
StartMenu="Add_Pin,StartMenu"
TaskBar="Add_Pin,Taskbar"

When winbuilder builds the api menu it looks at %APISUBDEF% and makes the top level entries based on the contents of this variable. Next it looks for sections inside the API script file that have the matching name of the top level entries and fills the top level menus with the lines in each section.

The sections are layed out like so:

  • the name of command as shown in api menu = command to paste into the code editor when you select the command.
  • -= makes a line/divider.
and that's the quick and dirty introduction to the common api. The rest of the code inside the script file are the functions that actually doing the work.

NOTE: WinBuilder does not scan the sections. It only displays the contents of the section referenced by the corresponding name defined in %APISUBDEF%

  • If it is not listed in any of the sections referenced by %APISUBDEF%, even if it has code to implament the functionality and is listed in the macro declaration, it won't have a Magic Wand entry.
  • The variable %APISUBDEF% is only used by WinBuilder itself for building the API menu entries. The actual routines/functions are added in the [ApiVar] section.
previous page start next page