Scripting Scribe
Overview
Scribe can execute scripts to extend it's functionality in the following locations:
- As a filter that is executed on email being sent or received.
- From an item in the tools menu.
- From an item in the context menu of an object like email, contacts etc.
- Before an email is saved and sent.
- On start up.
Scribe Specific Methods
These methods are defined for all scripts run within Scribe, in addition to the various
scripts defined by the system library
(which are available in any script enabled Lgi
application).
-
Print (...)
Prints string representations of any arguments, converting \r, \t, \n etc to the actual whitespace characters. -
MsgBox (ParentWnd ,MsgTxt [,TitleTxt = AppName[,ButtonsType = MB_OK]])
Shows a message box, attached to ParentWnd with the MsgTxt in the body. -
GetFolder (NameOrIndex )
Returns a pointer to a folder. If NameOrIndex is a string then it should be the full path of the folder, otherwise it can be an integer:- FOLDER_INBOX = 0
- FOLDER_OUTBOX = 1
- FOLDER_SENT = 2
- FOLDER_TRASH = 3
- FOLDER_CONTACTS = 4
- FOLDER_TEMPLATES = 5
- FOLDER_FILTERS = 6
- FOLDER_CALENDAR = 7
- FOLDER_GROUPS = 8
- FOLDER_SPAM = 9
-
LoadFolder (FolderPtr )Loads the items in a folder if not already. -
SelectFolder (FolderPtr )Selects the given folder in the UI. -
CreateSubFolder (ParentFolderPtr ,NameTxt ,Type )Creates a subfolder under ParentFolderPtr, with the given name and type. Type can be: "Mail", "Contact", "Filter", "Calendar" or "Group". -
BrowseFolder (ParentWnd [,MessageTxt [,DefaultFolderName ]])Browses for a folder location, returns NULL on Cancel, and the folder's path on Ok. -
CreateThing (Type )Creates a new thing (email, contact etc). Type is an integer, one of:- MAGIC_MAIL: 0xAAFF0001
- MAGIC_CONTACT: 0xAAFF0002
- MAGIC_FILTER: 0xAAFF0007
- MAGIC_CALENDAR: 0xAAFF000b
- MAGIC_GROUP: 0xAAFF000d
-
MoveThing (Folder ,Item )Moves 'Item' into 'Folder'.
'Folder' can either by a direct pointer to a folder object -or- a string specifying the path to the folder. -
SaveThing (DestinationFolder ,Item )Saves 'Item' into 'DestinationFolder', more of a copy. Usually used with new objects that are't already saved somewhere. -
DeleteThing (Item )Deletes an object from memory and disk (or moves it to the trash). -
ShowThingWindow (Item )Opens the user interface for 'Item'. -
AddToolsMenuItem (Name ,CallbackMethodName )Puts a menu item with the text 'Name' for a script function 'CallbackMethodName' in the tools menu. Where 'CallbackMethodName' is the name of the function as a string. Callbacks have the following form:ToolMenuCallback (Application ,CmdId ) -
AddCallback (HandlerName ,CallbackMethodName )Adds a callback to a specific handler. Multiple callbacks can be installed for the same handler. Handlers call the callbacks in the order they were installed.
Available callback handlers:-
OnThingContextMenu (Application ,Menu ,Thing )The callback script function is called after the context menu for a Thing has been constructed but before it's shown to the user. The callback can install commands or submenus that call other callbacks. -
OnThingToolbar (Application ,Toolbar ,Thing )The callback script function is called after the toolbar for a Thing has been constructed, but before the UI is shown to the user. The callback can install extra button(s) that call other callbacks. -
OnApplicationToolbar (Application ,Toolbar )The callback script function is called after the main application toolbar has been constructed, but before the UI is shown to the user. The callback can install extra button(s) that call other callbacks. -
OnBeforeMailSend (Application ,EmailMsg )The callback script function is called before the email window submits an email for sending. If the script returns zero, the email window does nothing, if the script returns non-zero then sending proceeds as normal. -
OnBeforeInstallBar (Application ,UserMsg ,ActionList )The callback script function is called before the install capability bar is shown. The user msg and action list can be adjusted by the script function. If FALSE is returned the capability bar is not shown, if TRUE is returned normal behaviour follows, with any modifications the script makes. -
OnInstallComponent (Application ,ActionName )The callback script function is called to install a component after the capability bar has got user permission. If the function returns TRUE the system installers proceed with their default behaviour. If the function returns FALSE then the installation exits without doing anything further. If the script actually performs the install itself, it should return FALSE. ActionName is the text on the button that the user clicked. It is translated into the current language. The system string IDs used are:- IDS_OK - just hides the capability bar without doing anything.
- IDS_DONT_SHOW_AGAIN - turn off default client warnings.
- IDS_INSTALL - install library from memecode website (openssl, libjpg etc).
- IDS_SHOW_CONSOLE - shows the console.
- IDS_OPEN_SOURCE - opens the script source (on say compile error).
- IDS_SHOW_REMOTE_CONTENT - shows remote content for a HTML email.
- IDS_DOWNLOAD - downloads a spell check dictionary.
- (if you want something added here, ask the author)
-
-
GMenuAddItem (Menu ,Icon ,LabelTxt ,Position ,CallbackMethodName ,CallbackId )Adds an item to 'Menu' as 'Position' with the specified text. If the menu item is clicked, then the scripting function 'CallbackMethodName' is called using the following arguments:OnMenuItem (Application ,Window ,Thing ,CallbackId )Where 'Thing' is the object the menu was use on and 'CallbackId' is the integer supplied to GMenuAddItem. -
GMenuAddSubmenu (Menu ,SubmenuTxt ,Position )Returns a pointer to the submenu or NULL on error. -
GToolbarAddItem (Toolbar ,Icon ,LabelTxt ,Position ,CallbackMethodName ,CallbackId )Adds a toolbar button to 'Toolbar'. When the button is clicked, 'CallbackMethodName' is called. The callback is called with the following parameters:OnToolbarButton (Application ,Window ,Thing ,CallbackId )Where 'Window' is the window the toolbar is attached to. CallbackId is the integer passed to GToolbarAddItem. - Deprecated: FilterDoActions(Filter, Mail)
Executes the actions attached to 'Filter' on 'Mail'.
Use Filter.DoActions(Mail ) instead.
File Based Scripts
When you create a file based script in the ./Scripts subfolder it has to have the extension .script. It will
only be loaded at startup, changes to the script after Scribe loads will not be loaded until next start up.
Scripts should be utf-8 text with \r\n or \n end of line characters. They should have a method called "Main" and
optionally one or more callback methods. The Main function should register the callback(s) via AddToolsMenuItem,
AddThingMenuCallback, AddThingUiButton or AddCallback.
See the existing scripts in that folder for some examples.
Filter Based Scripts
Filter based scripts exist in the Script tab of a filter object. When the script tab has some content any
existing filter conditions are ignored and the script is executed. There doesn't need to be a method defined
in the script. Several pre-defined variables are available:
- App: The main application object.
- Filter: The filter being evaluated.
- Mail: The mail being filtered.
Filter.TestConditionsWhich returns a boolean true of the mail matches the filter's conditions or false otherwise. Also to execute the actions attached to the filter you can call:
Filter.DoActions(Mail)The default behaviour of a filter with no script is:
if (Filter.TestConditions) { Filter.DoActions(Mail); }You can use that as a template to build up to the functionality you want. Alternatively you can replace Filter.DoActions(...) with a set of custom calls to manipulate objects directly from the script.
To stop further filtering of the current email use the StopFiltering method:
Filter.StopFiltering();