Using SyncBackPro > Technical Reference > Scripting

These are functions that are defined in your Main Interface script and are called by SyncBackPro. A main interface script can enhance or change the main user interface. For example, you can add columns to show extra information about profiles, or perform some action when a key is pressed. The functions are called by SyncBackPro at the appropriate time. Main Interface scripts have access to the SBSystem, SBVariables, and SBHistory objects.

All the example code below is written in using the Pascal scripting language.

function MainColumnHint(Col, IsGroup, ProfileName);

Col: The column number

IsGroup: True if the profile is a group

ProfileName: The name of the profile

Return value: The hint string to display

This subroutine is called from the main window when a custom column hint is required. The first custom column is column zero (0). The script is only called for its custom columns and not for columns created by other scripts.

function MainColumnsCount;

Return value: The number of custom columns, or zero if none are required

This function is called from the main window to ask the script how many custom columns it wants created in the main window. Note that this value is cached so the function is only called once (when the main window appears, i.e. when the program is run).

function MainColumnSort(Col, IsGroup1, IsGroup2, ProfileName1, ProfileName2);

Col: The column the display is being sorted on

IsGroup1: True if ProfileName1 is a group

IsGroup2: True if ProfileName2 is a group

ProfileName1: The name of a profile

ProfileName2: The name of a profile

Return value: An integer (<0 if profile 1 should go before profile 2, 0=same profile, > 0 if profile 1 should go after profile 2)

This function is called from the main window when a custom column is being sorted. The first custom column is column zero. The script is only called for its custom columns and not for columns created by other scripts.

Important: As little processing or disk reading as possible should be done in this subroutine. Whenever possible use in-memory caching. See the History.vbs script as an example.

function MainColumnText(Col, IsGroup, ProfileName);

Col: The column number

IsGroup: True if ProfileName refers to a group profile

ProfileName: The name of the profile

Return value: The text to display in the column

This function is called from the main window when text for a custom column is required. The first custom column is column zero (0). The script is only called for its custom columns and not for columns created by other scripts.

Important: As little processing or disk reading as possible should be done in this subroutine. Whenever possible use in-memory caching. See the History.vbs script as an example.

function MainColumnTitle(Col; var Width);

Col: The column number

Width: Set it to the width the column should be (in pixels)

Return value: The columns title

This function is called from the main window when the title for a custom column is required. The first custom column is column zero (0). The script is only called for its custom columns and not for columns created by other scripts.

function NewVersionCheck(var ErrMsg);

ErrMsg: If a check cannot be made then set an error message, else set to an empty string

Return value: If a new version is available then return the URL to open the web browser with, else return empty string

This function is deprecated. SyncBack V9 introduced NewVersionCheckEx which is the replacement.

This function is called when SyncBack checks to see if a new version of SyncBack is available. The function should not prompt the user as update checks are usually made in the background. Also take into account that it may be unattended.

- If any script returns an error message then the update check is aborted.

- If any script returns a URL then the update check is aborted and the user is told a new version is available.

- If a script returns the URL string '*' then the update check is aborted and the user is told there is no new version.

- If all the scripts return an empty string URL, and no error messages, then SyncBack will check the 2BrightSparks web site to see if there is a new version available.

function NewVersionCheckEx(var ErrMsg);

ErrMsg: If a check cannot be made then set an error message, else set to an empty string

Return value: If a new version is available then return the URL to open the web browser with, else return empty string

- If any script returns an error message then the update check is aborted.

- If any script returns a URL then the update check is aborted and the user is told a new version is available.

- If a script returns the URL string '*' then the update check is aborted and the user is told there is no new version.

- If all the scripts return an empty string URL, and no error messages, then SyncBack will check the 2BrightSparks web site to see if there is a new version available.

function PollingRefresh;

Return value: True if the script wants RefreshDisplayEx or RefreshDisplay called even if there is no reload or refresh of profile data

This function is called from the main window to ask the script if it wants to have RefreshDisplayEx or RefreshDisplay called even when no profiles have been reloaded or refreshed.

It is called just before MainColumnsCount and is only called once on program startup. If the function is not defined then it is assumed the script does not want to be called.

procedure MainColumnClicked(Col, IsGroup, ProfileName);

Col: The column number

IsFile: True if it is a group profile

ProfileName: The name of the profile

This subroutine is called from the main window when a custom column is clicked. The first custom column is column zero (0). The script is only called for its custom columns and not for columns created by other scripts.

procedure MainEnded(EndSession);

EndSession: Passed as TRUE on Windows shutdown, restart or logout

This subroutine is called when SyncBack stops. The script should not prompt the user or expect any user interaction. It should also not try to stop the program from exiting.

In previous versions this subroutine was not called on Windows shutdown, restart or logout if profiles were set to run in those situations. In V7 and newer it is called and also EndSession will be passed as TRUE (it is FALSE if the program is closing because the user manually closed it, for example). When EndSession is TRUE you must not delay as Windows may terminate the process if it is taking too long.

procedure MainFocusChanged(IsGroup, ProfileName);

IsGroup: True if ProfileName refers to a group

ProfileName: The name of the profile

This subroutine is called from the main window when the focused node changes.

procedure MainKeyPress(Key, Shift, IsGroup, ProfileName);

Key: The key that as pressed

Shift: The shift state

IsGroup: True if ProfileName refers to a group profile

ProfileName: The name of the profile

This subroutine is called from the main window when a key is pressed. It is called for each selected row. It is not called if the Delete key is pressed (as that is handled by SyncBack itself).

The Key value refers to the virtual key codes.

The Shift state can be a selection values (see RunDiffKeyPress for details)

procedure MainStarted(Unattended);

Unattended: If True then do not prompt the user or expect any user interaction

This subroutine is called when SyncBack starts.

procedure RefreshDisplay;

This subroutine is called when SyncBack refreshes or updates the main display. It is deprecated and instead RefreshDisplayEx is recommended.

Important: As little processing or disk reading as possible should be done in this subroutine. Whenever possible use in-memory caching. See the History.vbs script as an example.

procedure RefreshDisplayEx(Reloading, Refreshing);

Reloading: Passed as TRUE if the list was reloaded

Refreshing: The names of the profiles that were refreshed. If using newer scripting then this is a TStringList. If using legacy Windows Scripting then this is a Scripting.Dictionary object.

This subroutine is called when SyncBack refreshes or updates the main display.

Reloading is TRUE if the list of profiles has been reloaded. This usually happens when a profile has been deleted, created, or renamed. If a profile has been renamed then the old profile name is passed in Refreshing. On program start, and when the users refreshes the list by pressing V5, for example, Reloading is passed as TRUE and Refreshing contains just one empty string (meaning all profiles are being refreshed).

Refreshing lists the names of all the profiles that were refreshed (in the key, the item is always empty). This usually happens when a profile has been modified. If Refreshing contains just one key, and the key is an empty string, then all the profiles have been refreshed.

For the legacy Windows Scripting, Refreshing is a Scripting.Dictionary object. For newer scripting it's a TStringList object. So you can get the total number of profiles via TStringList(Refreshing).Count and get the profile names via TStringList(Refreshing).Strings[0] (the list is zero-based).

If Reloading is FALSE and Refreshed is empty then this is just a polling call. For example, if nothing is happening (which includes profiles running), then it may be a polling call. Note that when a profile starts and stops then RefreshDisplayEx (or RefreshDisplay) is called with the name in Refreshing.

How frequently a polling call is made depends on the refresh rate set by SyncBackPro. In most cases you won't need to do anything and so your script will not be called. However, if you do want the script to be called in these cases then see PollingRefresh.

Important: As little processing or disk reading as possible should be done in this subroutine. Whenever possible use in-memory caching. See the History.vbs script as an example.

Main Interface Scripts

Main Interface Scripts