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).List of system folder identifiers:
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 |
MAGIC_MAIL | 0xAAFF0001 |
MAGIC_CONTACT | 0xAAFF0002 |
MAGIC_ATTACHMENT | 0xAAFF0005 |
MAGIC_FILTER | 0xAAFF0007 |
MAGIC_CALENDAR | 0xAAFF000b |
MAGIC_GROUP | 0xAAFF000d |
-
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 a system folder identifier (integer). -
GetSourceFolders (SystemFolderId )
Returns a list of folders. SystemFolderId is a system folder identifier (integer). Use this to get all the folders for a particular item type. For instance to get all the contacts folder (across all mail stores) you would call:Flds = GetSourceFolders(4);
-
LoadFolder (FolderPtr )Loads the items in a folder if not already. -
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 [,Folder =None])Creates a new thing (email, contact etc). Type is an integer (e.g. MAGIC_MAIL). Optionally you can supply a folder to create the object for. This is especially important if you want to create an IMAP mail. By default CreateThing creates a mail3 based object. -
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 object(s) from memory and disk (or moves it to the trash). You can supply multiple arguments if needed, including List objects. To specify deleting to trash or deleting without trash use a string parameter. The default is not to delete to the trash.- DeleteThing(MyObj, "trash");
-
ShowThingWindow (Item )Opens the user interface for 'Item'. -
LookupContact (Email )Searches for the contact with a given email address. -
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 [,Parameter ])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 ,Thing ,Menu )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. -
OnFolderContextMenu (Application ,Folder ,Menu )The callback script function is called after the context menu for a Folder 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. -
OnTimer (Application )Calls the function periodically. Set the period via AddCallback's "Parameter". Values for that are in the form [number][unit], where Unit can be:- m/min/minute
- h/hr/hour
- d/day
- AddCallback("OnTimer", "MyFunction", "5min");
- AddCallback("OnTimer", "DoEveryHour", "1hr");
- (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 ,Object ,CallbackId )Where 'Object' is the either a 'Thing' or the 'Folder' the menu was used on.
And 'CallbackId' is the integer supplied to GMenuAddItem.
This will also append a separator:Menu.AppendSeparator();
-
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 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:
| The main application object. |
| The filter being evaluated. |
| 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();
Specific Notes on Fields
The SENT | Email has been sent via SMTP |
RECEIVED | Email was received by POP or IMAP |
CREATED | User created email |
FORWARDED | Email has been forwarded |
REPLIED | Email has been replied to |
ATTACHMENTS | Email has attachments (can be wrong if email hasn't been parsed yet, more a display hint for user) |
READ | User requested monospace font |
READY_TO_SEND | Email is marked for sending in the next SMTP connection |
READ_RECEIPT | User requested a receipt |
IGNORE | User requested thread to be ignored |
FIXED_WIDTH_FONT | User requested monospace font |
BOUNCED | Messaged was bounced to somewhere |
BOUNCE | Message IS a bounce (copy that is sent onwards) |
SHOW_IMAGES | User requested external resources |
BAYES_HAM | Currently classified as 'Ham' by the spam filter |
BAYES_SPAM | Currently classified as 'Spam' |
NEW | Email has been newly received |
STORED_FLAT | Encrpytion implementation specific (don't use) |
if (MailObj.Flags["NEW"]) Print("New mail!\n");
The
FOLDER_INBOX | 0 | The mail3 Inbox. |
FOLDER_OUTBOX | 1 | The mail3 Outbox. |
FOLDER_SENT | 2 | The mail3 Sent folder. |
FOLDER_TRASH | 3 | The trash. |
FOLDER_CONTACTS | 4 | The mail3 Contacts folder. |
FOLDER_TEMPLATES | 5 | The templates folder. |
FOLDER_FILTERS | 6 | The filters. |
FOLDER_CALENDAR | 7 | The primary calendar folder. |
FOLDER_GROUPS | 8 | The contact groups. |
FOLDER_SPAM | 9 | All the spam. |
/{MailStoreName}/{LocalPath}