Scribe Scripting API
Basics
The main syntax of the language is somewhat modelled after Javascript and C, however you don't
need to declared variables with "var". And some more advanced features are missing like passing
functions around as variables, ternary operators etc.
When scripting in Scribe you will encounter objects, like email, the application object, a contact
and so on. These are implemented internally as C++ objects that inherit from the
GDom class. You
can read and write various properties via a simple naming convention. For instance if you have a
pointer to a mail object in that variable 'm' then you can access the sender's email addres using
the syntax 'm.From.Email'. You can look up the fields available in the various objects using the
Scribe DOM reference.
Objects in Scribe generally have a type associated with them. Folders can contain items of one
type, except the trash which can have all types of objects. The types have codes associated with them,
and this is the mapping:
MAGIC_NONE | 0x00000000 | No type
|
MAGIC_MAIL | 0xaaff0001 | Mail item
|
MAGIC_CONTACT | 0xaaff0002 | Contact item
|
MAGIC_FOLDER | 0xaaff0003 | Folder of items
|
MAGIC_MAILBOX | 0xaaff0004 | Root of mail tree (nothing-abstract)
|
MAGIC_ATTACHMENT | 0xaaff0005 | Mail attachment
|
MAGIC_ANY | 0xaaff0006 | Trash folder type (accepts any object)
|
MAGIC_FILTER | 0xaaff0007 | Used to match messages against
|
MAGIC_FOLDER_2 | 0xaaff0008 | Folder v2
|
MAGIC_CONDITION | 0xaaff0009 | Filter condition
|
MAGIC_ACTION | 0xaaff0010 | Filter action
|
MAGIC_CALENDAR | 0xaaff0011 | Calendar event
|
MAGIC_ATTENDEE | 0xaaff0012 | Event attendee
|
MAGIC_GROUP | 0xaaff0013 | Group of contacts
|
There are a number of example scripts in the ./Scripts sub-folder in the scribe directory, and
a copy of this file. Scripts in the ./Scripts sub-folder are automatically scanned and loaded
into the tools menu of Scribe on startup.
They need to define a main function, which is called when Scribe starts. In your main function you
should do any intialization required and then setup a callback hook depending on what type of functionality
you're implementing.
Library Functions:
Built In Language Functions
string Strchr(str, ch[, len]);
Finds a unicode character in a string.
Arguments:
- str - the string to search in
- ch - the character to find
- [Optional] len - the maximum length in 'str' to search
Returns:
- The remainder of the string starting with the character found or NULL if not found.
string Strstr(str1, str2[, case_insensitive[, len]]);
Finds a string in another string.
Arguments:
- str1 - the string to search in
- str2 - the string to search for
- [Optional] case_insensitive - true if you want case sensitivity (default: false)
- [Optional] len - the maximum length in 'str' to search (default: the whole of 'str1')
Returns:
- The remainder of the string starting with the string found or NULL if not found.
int Strcmp(str1, str2[, case_insensitive[, len]]);
Compares 2 strings.
Arguments:
- str1 - the first string to compare
- str2 - the second string to compare
- [Optional] case_insensitive - true if you want case sensitivity (default: false)
- [Optional] len - the maximum length in characters to compare (default: the whole strings)
Returns:
- zero if the strings are the same, non-zero if they are not.
string Substr(str, start[, len]);
Returns a part of another string.
Arguments:
- str - the whole string
- start - the zero based character index of the sub string you want
- [Optional] len - the length of the substring (default: the rest of the string)
Returns:
string LoadString(id);
Loads a string from the resource file.
Arguments:
Returns:
- A string or NULL on failure.
hashtable NewHashTable();
Returns an empty hash table object.
Arguments:
Returns:
See also
this page on container
type handling.
list NewList();
Returns an empty list object.
Arguments:
Returns:
See also
this page on container
type handling.
bool DeleteElement(container, index);
Returns an empty list object.
Arguments:
- container - the list or hashtable container to delete from
- index - the index of the element, if 'container' is a list, then specify the
integer index of the element to delete. If it's a hash table, specific the
key of the element to delete as a string.
Returns:
- non-zero if successful, zero on error.
string ReadTextFile(filename);
Returns the contents of a text file.
Arguments:
- filename - the name of the file
Returns:
- the contents of the file as a string.
bool WriteTextFile(filename, data);
Writes the contents of a variable to a text file.
Arguments:
- filename - the name of the file
- data - the date to write, can either be a string or a binary object
Returns:
- non-zero on succes, zero on failure.
Scribe Specific Functions
bool LoadFolder(folder);
Loads the items in a folder. By default folders are not loaded, to access their
items you first have to load them using this function.
Arguments:
- folder - the object to load
Returns:
string SelectFolder(parent_wnd[, limit_to_type]);
Displays a dialog to the user so they can select a folder.
Arguments:
- parent_wnd - the parent window object or 0
- limit_to_type - an item type specified in the
list of item types at the top of this document.
(Defaults to MAGIC_NONE = 0x0 )
Returns:
- a path to the folder selected or NULL.
object GetFolder(path);
Returns a folder object.
Arguments:
- path - the path to the folder, '/' is the root, '/Inbox' is your inbox etc.
You can also use an integer to refer to various system folders:
- Inbox = 0
- Outbox = 1
- Sent = 2
- Trash = 3
- Contacts = 4
- Templates = 5
- Filters = 6
- Calendar = 7
- Groups = 8
Returns:
- A dom object for the folder, or NULL on failure.
By default folders are not loaded, so to access the items inside them use the LoadFolder
method.
object CreateSubFolder(parent_folder, child_name, child_type);
Creates a new folder object.
Arguments:
- parent_folder - the parent folder
- child_name - the name of the new child folder
- type - the folders type, use one of the values specified in the
list of item types at the top of this document.
Returns:
- A dom object for the new child folder, or NULL on failure.
bool CreateThing(type);
Creates a new Thing.
Arguments:
- Type, the type of object to create, i.e. MAGIC_MAIL
Returns:
- object pointer on success, NULL on failure.
bool MoveThing(dest_folder, object);
Moves an object to another folder.
Arguments:
- dest_folder - the destination folder
- object - the object to move. it will need to be the right type
for the destination folder. if you try and put a contact into a
folder of email it will fail.
Returns:
- non-zero on success, zero on failure.
bool SaveThing(folder, object);
Saves a new object into a folder.
Arguments:
- folder - the destination folder
- object - the object to save.
Returns:
- non-zero on success, zero on failure.
bool Delete(object);
Deletes an object to the trash
Arguments:
- object - the object to delete, can be a Thing or Folder
Returns:
void Print(string);
Prints a string to the debug console.
Arguments:
- string - the string to print
Returns:
You can open the debug console using the Tools->Debug->Show Scripting Console menu.
int MsgBox(parent_wnd, msg, title[, type]);
Displays a message box.
Arguments:
- parent_wnd - the parent window or 0
- msg - the body of the msg
- title - the title for the window
- type - the button type, defaults to "Ok".
- MB_OK = 5
- MB_OKCANCEL = 6
- MB_YESNO = 7
- MB_YESNOCANCEL = 8
Returns:
- A code for which button was pressed.
- IDOK = 1
- IDCANCEL = 2
- IDYES = 3
- IDNO = 4
Scripting Hook Functions
int AddToolsMenuItem(String MenuText, String CallbackFunctionName);
Setup a new callback that shows up in the main window's Tools menu
Arguments:
- MenuText, the text for the menu item.
- CallbackFunctionName, the method to call in the current script
when the user selects the menu item. This callback function should
have the form:
void Callback(ScribeWnd App, int MenuId)
Returns:
- A menu item id, or 0 on failure.
int AddThingMenuCallback(String MenuText, int ThingType, String CallbackFunctionName);
Setup a new menu item in the context menu of Things (mail, contact, calendar event etc).
Arguments:
- MenuText, the text for the menu item.
- ThingType, show this menu for a specific type or use MAGIC_ANY (0xaaff0006) for all types.
- CallbackFunctionName, the method to call in the current script
when the user selects the menu item. This callback function should
have the form:
void Callback(ScribeWnd App, int MenuId, Thing Obj)
Returns:
- A menu item id, or 0 on failure.
int AddThingUiButton(int ThingType, String ButtonText, String ButtonImg, String CallbackFunctionName);
Setup a new menu toolbar button in the window UI of a Thing object (mail, contact, calendar event etc).
Arguments:
- ThingType, show this menu for a specific type or use MAGIC_ANY (0xaaff0006) for all types.
- ButtonText, the text for the button
- ButtonImg, the icon for the button. This is in the form "image_file_name,icon_index", or something
like './Scripts/GpgPluginIcons.gif,2' would pull the 3 icon out of that gif file. The icon size
is the same as whatever other icons are used by Scribe.
- CallbackFunctionName, the method to call in the current script
when the user selects the menu item. This callback function should
have the form:
void Callback(ScribeWnd App, int MenuId, Thing Obj, GWindow Ui)
Returns:
- A menu item id, or 0 on failure.