Macro Library - How It works

Macro Library (ML) is a set of macros (apis), nothing more nothing lesss ;)
If you know how to create a macro in a plugin, than you can easly figure out how ML works.

ML add a set of macros to projects (by using Global memory) to ease plugin writing and provide backward compatibility.

ML's goal is helping plugins to be shared between "ML Projects" easly,
not all wb projects need to be a ML project, there are other none-ML projects
ex:
BartPE-Core
Alberich
are 2 verrrry good examples.
Also none of ML projects have to follow ML development, they are free to alter (hardcode) lines since freedom which we (Galapo and I ) fully support provided by open-source progress.

Wb projects tend to die within a year (wb sin ;)) due to its bad development features (=Intetional Sabotages by Nuno Bruto and Peter Schang).
Besides it is today relatively easy (remember old bad days) to update old ML projects with new ML to get them fully function with new plugins.
On TheOven.org, we ignore wb developers who are the reasons of the sin, Developed projects with ML and Other Fundemantals, hence successfully survive  Step by step continue developing , replacing wb with another builder is only another step on roadmap 

RoadMap of ML:
If one remembers old days of capi discussions after pedrole left one would clearly see a set of success archived.
* ML priority changed to have stable builds
* very optimized and faster (many codes improved)
* ML workaround many many internal wb bugs & sabotages which result with stable ML commands now.
* new ML development moves forward to more general and expandable usage instead of hardcoded (troubled license) implementation
* some of previous hardcoded methods removed, some will be removed, they come from pedrole's last api and we work on them due to their priorities.

priorities:
* we do not rush on changing hardcoded things that do not cause troubles, be sure they are in our main progress for a long while now in our free time.
* we are aware of requirements which never requested by any member, they are in development path with low priority.
* bug fixes are top priority, if one reports it is instantly fixed and all ML projects informed & updated. (generally it takes only some hours ;))
* requests are 2nd piority, if a request comes which do not effect backward compatibiltiy having a good reason inside, it is mostly implemented mostly in 2 days.
(real life free time may effect these time numbers, above is mostly what happens)

ML Commands can be found in [Api_Def] section with %APISUBDEF%=     each command seperated by comma.
note: Some commands inside codes unlisted in %APISUBDEF% only to keep backward compatibility.

The only special arrangement for ML is, wb reserve a wand menu for ML commands which is declared to wb by api.

Here is a good explanation written by Homes32:
(with minor changes)

Ok here it goes.
we will start by looking at what makes the Macro Library "turn on"

If you look in script.project you will see the following lines

Code: [Select]

//-- Macro Library File and Some ML project settings
%API%=%ProjectDir%\Build\Macro_Library.script

this line tells us what file contains macros

Code: [Select]

%APIVAR%=ApiVar

this is the name of the section in ML that contains that actual definitions of commands. aka what to do when you Add_shortcut etc.
we will look at this section in the Macro Library later.

Code: [Select]

%APIDEF%=API

this is simply the name that will be displayed for the api menu in the magic wand

Code: [Select]

%API_TYPE%=2

this variable is used to tell the Macro Library that we are project type 2 (Vista/Win7) and is used to decide what functions in the Macro Library to run when a command is called. (for project type commands ;))
1=Gena - PE1 based projects
2=Vista/Win7/Win8 based projects - nt6x projects
98=Windows98 based projects

Code: [Select]

%APISUBDEF%=Add_Shortcut,Add_DesktopIni,Add_Url,Arch,Call,ScriptInterface,Others,Registry,Require_File,RunFrom,Unpack,Variable

this is the api submenu definitions. each entry is a top level menu in the api menu

Code: [Select]

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

this command loads all commands in the Macro_Library.script [ApiVar] as GLOBAL. we will get into this a bit more later. but know that this needs to happen in order for plugins to use the common api commands.


Ok now on to Macro_Library.script

Code: [Select]

[Api_Def]
%APIVAR%=ApiVar
%APIDEF%=MacroLibrary
%APISUBDEF%=Add_Shortcut,Add_DesktopIni,Add_Url,Arch,Call,ScriptInterface,Others,Registry,Require_File,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 Macro Library
editing this section will not do anything!!!!!!!

Code: [Select]

[ApiVar]
[ApiVar]
Add_Shortcut=Run,%API%,AddShortcut%_ML_Shortcut_TYPE%
Add_Pin=Run,%Api%,Add_Pin_Process%API_TYPE%
Add=Run,%API%,Add_
----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

Code: [Select]

[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 Add_Pin in any plugin it internally replaces the Add_Pin with Run,%Api%,Add_Pin_Process%API_TYPE% which will execute the [Calculate] section in %API% which we defined earlier in script.project as being %ProjectDir%\Build\Macro_Library.script


next we define the menu entries for the magic wand

Code: [Select]

[API]
[*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""
Sample RecentPrograms="Add_Pin,RecentPrograms,,$Start_Menu\Programs\Accessories\Notepad.lnk"
-=
StartMenu="Add_Pin,StartMenu"
TaskBar="Add_Pin,Taskbar"
RecentPrograms="Add_Pin,RecentPrograms"

[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"

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 Macro Library 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 Macro Library. the rest of the code is functions for actually doing the work.



answers to specific questions

winbuilder does not scan the sections. it only displays the contents of the section referenced by the corresponding name defined in %APISUBDEF%

because it is not listed in any of the sections referenced by %APISUBDEF%


APISUBDEF is only used by winbuilder itself for building the API menu entries
routines/functions are added in the [ApiVar] section

here is published code snippet of wb that is used to implement Macro Library commands to wand.

Code: [Select]

procedure TForm1.ApiMenu(project: string);
var
  i, j, p: integer;
  subitm, itm, api: TMenuItem;
  men: TPopupMenu;
  apiscript, apidef, apivar, apisub: string;
  ini: TIniFile;
  subs, cmds: TStringList;
  sub, cmd: string;
  capt: string;
  delete: boolean;
  TempRunner: TScriptRunner;
begin
  //  First free an eventually present menu entry
  men := PluginEdit.Popup_Source;
  delete := false;
  for i := men.Items.Count - 1 downto 0 do
  begin
    itm := men.Items[i];
    if delete then
    begin
      Men.Items.Remove(itm);
      delete := true;
    end
    else
    begin
      capt := AnsiReplaceText(itm.Caption, '&', '');
      if AnsiSameText(capt, 'API') then
      begin
        Men.Items.Remove(itm);
        delete := False;
      end
    end;
  end;
  // Create a 'quick' Scriptrunner. It does do only the functions necessary here
  TempRunner.Create('', '', '', project, '', Form1.ProgressBar1, Form1.ProgressBar3, lblComment, Log_box.lvLog,
    log_box.lvVariables, tvProgress, True);
  TempRunner.refreshGlobals := True;
  TempRunner.buildScriptVars;
  // now the name of the API section
  apiscript := TempRunner.scriptVars.TranslateVars('%API%', '%');
  CodeBoxAPI := '';
  hasAPI := False;
  if apiscript <> '%API%' then // Only if %API% is defined
  begin
    apidef := TempRunner.scriptVars.TranslateVars('%APIDEF%', '%');
    apivar := TempRunner.scriptVars.TranslateVars('%APIVAR%', '%');
    apisub := TempRunner.scriptVars.TranslateVars('%APISUBDEF%', '%');
    if apidef <> '%APIDEF%' then // Only if %APIDEF% is defined
    begin
      // we have to create the menu
      api := TMenuItem.Create(men);
      api.Caption := '-';
      men.Items.Add(api);
      api := TMenuItem.Create(men);
      api.Caption := apidef;
      men.Items.Add(api);
      CodeBoxAPI := 'AddVariables,"' + apiscript + '",' + apivar + ',GLOBAL';
      cmds := TStringList.Create;
      ini := TiniFile.Create(apiscript);
      ini.ReadSectionValues(apidef, cmds);
      for i := 0 to cmds.Count - 1 do
      begin
        cmd := cmds[i];
        p := AnsiPos('=', cmd);
        itm := TMenuItem.Create(api);
        itm.Caption := AnsiLeftStr(cmd, p - 1);
        itm.Hint := AnsiMidStr(cmd, p + 1, MaxInt);
        itm.OnClick := PluginEdit.APIClick;
        api.add(itm);
      end;
      if apisub <> '%APISUBDEF%' then
      begin
        subs := TStringList.Create;
        subs.CommaText := apisub;
        for i := 0 to subs.Count - 1 do
        begin
          sub := subs[i];
          itm := TMenuItem.Create(api);
          itm.Caption := sub;
          api.add(itm);
          ini.ReadSectionValues(sub, cmds);
          for j := 0 to cmds.Count - 1 do
          begin
            cmd := cmds[j];
            p := AnsiPos('=', cmd);
            subitm := TMenuItem.Create(itm);
            subitm.Caption := AnsiLeftStr(cmd, p - 1);
            subitm.Hint := AnsiMidStr(cmd, p + 1, MaxInt);
            subitm.OnClick := PluginEdit.APIClick;
            itm.add(subitm);
          end;
        end;
        subs.Free;
      end;
      cmds.Free;
      ini.Free;
      hasAPI := True;
    end;
  end;
  // now free all grabbed ressources
  TempRunner.FreeAll;
end;

Hi Lancelot !
Where you took source codes of WB?
Can I look at them?

hi olegpov,

they are sometimes in "lie-pro" topics, sometimes a snippet published around ;) and since I catch I copy-paste here to get tidy