Ok here it goes.
we will start by looking at what makes the common api "turn on"
If you look in script.project you will see the following lines
//-- API File and Some Api project settings
%API%=%ProjectDir%\Build\Common_Api.script
this line tells us what file contains the api
%APIVAR%=ApiVar
this is the name of the section in common_api that contains that actual definitions of the api commands. aka what to do when you
Add_shortcut etc.
we will look at this section in the common api later.
%APIDEF%=API
this is simply the name that will be displayed for the api menu in the magic wand
%API_TYPE%=2
this variable is used to tell the common api that we are project type 2 (Vista/Win7) and is used to decide what functions in the common api to run when a command is called.
1=Gena/LiveXP/NativeEx/PE1 based projects
2=Vista/Win7 based projects
98=Windows98 based projects
%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 is the api submenu definitions. each entry is a top level menu in the api menu
[Process]
AddVariables,%API%,ApiVar,GLOBAL
this command loads all commands in the common_api.script [ApiVar] as GLOBAL. 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.
Ok now on to Common_API.script
[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 script.project in order to use the Common api
editing this section will not do anything!!!!!!!
[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---------
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.
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
next we define the menu entries for the magic wand
[API]
[_Calculate]
Full Syntax="//_Calculate,AutoIT Command(expression),ReturnVar(without %)"
Note="//Allways use simple quote in expression ,use [#$c] in place of [,] 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"
the line [API] doesn't do anything. its just a reminder to developers that the next sections are menu definitions and not actually functions
now you will se a bunch of sections all with names corresponding to the submenus we defined in %APISUBDEF%
this is where we actually define the commands to be displayed in the API magic wand menu
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 with the 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:
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 thats the quick and dirty to the common api. the rest of the code is functions for actually doing the work.
answers to specific questionsOK, so how does WB know which things are for the wand and which ones to "skip"...
winbuilder does not scan the sections. it only displays the contents of the section referenced by the corresponding name defined in %APISUBDEF%
And is it also why the API for "CheckCD, while defined, doesn't have a wand entry?
because it is not listed in any of the sections referenced by %APISUBDEF%
I can't seem to make it add another routine... So how is that done, if not based on the definition of the APISUBDEF? Do I have to somehow refresh WB? Or will it load this (somehow) when the project is loaded? or do I have to execute the project at least once for the Wand to be effective or ???
APISUBDEF is only used by winbuilder itself for building the API menu entries
routines/functions are added in the [ApiVar] section
hope it helps. I know its a lot of information to absorb all at once.
-Homes32