Introduction

Starting from the version 0.5.6, QTerm supports scripts with QtScript. With the greatest and latest script support in QTerm, you can:

• Do boring and repeating operation automatically.
• Change the default behavior of QTerm with system scripts.
• Try new functions with script (In order to do this you might want to have Qt bindings for QtScript installed, they can be downloaded from http://labs.trolltech.com/page/Projects/QtScript/Generator)

How to Use

You can run simple scripts using Script->Run, for example, save the following code

for (var i = 0; i < 10; i++)
    QTerm.sendString("q");

to a script file, run it in QTerm will send 10 q's to the server.

To use the system control script. Open the address book, in the very end of the General tab. First enable the Load Control Script checkbox, then choose your system script.

How to Debug

If you want to develop serious/complicate scripts for QTerm, it is very helpful to have QScriptEngineDebugger enable. This feature is introduced in Qt 4.5, make sure your qt is new enough. Then you can run cmake with -DQTERM_ENABLE_SCRIPT_DEBUGGER=ON, for example:

cmake .. -DQTERM_ENABLE_SCRIPT_DEBUGGER=ON

Then do the usual make, make install to install QTerm

After you enable the debugger. It will pop up every time the script engine catches a exception. You can also call the debugger any time by Script->Debug.

How to Write a Script

Here is a list of functions you can call in the scripts, they are all in the "QTerm" object, so for example if you want to call "version()" you should call "QTerm.version()" instead.

QString version()

   Return the version of QTerm.

int caretX()

int caretY()

   Return the x or y coordinate of the current position of caret.

int columns()

int rows()

   Return the number of columns or rows of the current window.

int charX(int x, int y)

int charY(int x, int y)

   Given the graphical coordinate in the current window, convert it to the
   text coordinate.

int posX()

int posY()

   Return the x or y coordinate of the mouse.

QString getUrl()

QString getIP()

   Return the URL or IP address under the mouse pointer, if no url is
   detected an empty string will be returned.

bool isConnected()

   Check if the current window is conneced to a BBS server.

void reconnect()

   Reconnect to the BBS server, do nothing if the current window is already
   connected.

void disconnect()

   Disconnect from the current BBS server.

void buzz()

   Shake QTerm.

void sendString(const QString & string)

   Send string to the BBS server.

void sendParsedString(const QString & string)

   Send parsed string to the BBS server. you can use '^M' to represent the
   return key for example.

void osdMessage(const QString & message, int icon = 1, int duration = 0)

   Show message in the osd, icon = 0, 1, 2, 3 means No/Info/Warning/Error
   icon. Duration is in the unit of ms, 0 means forever.

void showMessage(const QString & message, int duration = -1)

   Show message in the notification area or system tray. duration is not
   really useful for now.

void cancelZmodem()

   Cancel the current zmodem transfer.

void setZmodemFileList(const QStringList & fileList)

   Set the list of files you want to upload with zmodem. call it before your
   start zmodem to avoid the file selection dialog.

QScriptValue getLine(int line)

   Get the object represent the 'line' line text.

QScriptValue window()

   Return the current window object.

bool addPopupMenu(QString id, QString menuTitle, QString icon = "QTerm")

   Add a menu item to the popup menu, you can access to the new action with
   QTerm.id property if the method succeed. menuTitle is the text displayed
   in the menu. currently icon parameter has no effect. Return true if
   succeed, otherwise it will return false.

bool addUrlMenu(QString id, QString menuTitle, QString icon = "QTerm")

   Add a menu item to the url popup menu, you can access to the new action
   with QTerm.id property if the method succeed. menuTitle is the text
   displayed in the menu. currently icon parameter has no effect. Return true
   if succeed, otherwise it will return false.

void addPopupSeparator()

void addUrlSeparator()

   Add separators to the popup/url menu so they will look nicer.

void loadScript(const QString & filename)

   Load external javascript files, QTerm will search the file under the
   "scripts" directory under the local path (e.g.SHOME/.qterm) first and then
   search the global path (e.g. /usr/share)

void globalPath()

   Return the global data path, for example, if you installed QTerm to /usr,
   then it will return /usr/share.

void localPath()

   Return the local data path, $HOME/.qterm under Linux.

QString getSelectedText(bool rect = false, bool color = false, const QString & escape = "")

   Return the current selected region. rect should always be false currently.
   color indicate if you want the copy the attribute of the text, escape is
   only useful when color is true, indicate how you want to represent the
   escape sequence.

void openUrl(const QString & url)

   Open the url using the http browser specified in QTerm.

void loadExtension(const QString & extension)

   Load extension, if you want to use the classes in Qt bindings, you
   need to load them first.

How to Write a System Script

In order to change the behavior of QTerm. You can reimplement the following functions in the system script, again all the functions are members of 'QTerm' object, for example init() should be understand as QTerm.init():

There is a property which is important for this usage: QTerm.accepted. It should be set to true if you do not want the native QTerm code to handle the event any further, otherwise it should set to false.

init()

   This function is called every time the system script is loaded. You can
   show messages or initiate some variables here.

setCursorType(x,y)

   Determine what kind of mouse cursor should be shown in the current
   context, if mouse release events is not handle by the script this function
   also determine how the mouse release will be handled.

setPageState()

   Determine the current state of the BBS page, useful for further determine
   the mouse behavior

isLineClickable(x,y)

   Determine if the current line under mouse cursor is clickable, x and y is
   the mouse text coordinate.

getClickableString(x,y)

   Determine if the string under mouse cursor is clickable, x and y is the
   mouse text coordinate, the string should be returned and will be
   highlighted by QTerm.

onMouseEvent(type, button, buttons, modifiers, pt_x, pt_y)

   Handle the mouse event, type, button, buttons, modifiers follow the
   definition in QMouseEvent, pt_x and pt_y is the graphical coordinate of the
   mouse pointer.

onKeyPressEvent(key, modifiers, text)

   Handle the key press event, the definition of the arguments again follows
   QKeyEvent.

onWheelEvent(delta, buttons, modifiers, orientation, pt_x, pt_y)

   Handle the mouse wheel event, the definition of delta, button, modifiers,
   and orientation follow QWheelEvent. pt_x and pt_y is the graphical
   coordinate of the mouse pointer.

onNewData()

   The function will be called every time QTerm gets new data, you can
   manipulate the received data a little bit.

antiIdle()

   Determine how the anti idle event should be handled.

autoReply()

   Determine how to reply the incoming message. Useful for those who want to
   write BBS robots.

checkUrl()

   Determine if there is a URL under the mouse pointer, return the URL if
   found, otherwise return a empty string.

checkIP()

   Determine if there is a IP address under the mouse pointer, return the URL
   if found, otherwise return a empty string.

onTelnetState(int state)

   Handle telnet events

onZmodemState(int type, int value, const QString& msg)

   Handle zmodem events

endOfArticle()

   Implement this to check the end of articles for downloading articles

There is also a signal: scriptEvent(const QString& type) which can be used by the script to emit and handle signals