Copyright: Written by smart-butler.com


Introduction

SmartButler makes working at your computer not only a lot easier, but enjoyable as well!  If you are a fan of ICQ, MSN or AOL’s “Instant Messenger” products, you will love the benefits that SmartButler can offer you.

SmartButler enables you to listen to your incoming messages without reading them and to recognize your online friends by their voices! This is because SmartButler can read messages from users with DIFFERENT voices and languages, using different speed, volume and tone settings set up for each individual user!

SmartButler also understands slang and idioms, will let you know when you have new mail, and can read the clipboard automatically. As SmartButler can speak many languages at once, it also is a good way to study new languages!

Furthermore, if you are familiar with scripting programming (such as VBScript or JScript) you can change or add scripts that drive SmartButler, in order to tailor its behavior exactly the way you want it.


Minimal System Requirements

Processor: 	Pentium-133 or higher (Pentium III is recommended)

Operating System: 	Windows 95, Windows 98, Windows Me, Windows 2000, Windows XP or Windows NT 4.0 or later

Disk Space: 	10 MB available for installation

Memory: 	32 MB RAM (128 MB RAM is recommended)

Browser:	Microsoft® Internet Explorer version 4.01 or later must be installed on your computer, though it does not need to be your default browser

Recommended configuration: Microsoft Windows 2000 (or XP), 128 MB RAM, sound Card, TrueColor video mode.


Contacts

Web site: 	http://smart-butler.com

Registration enquires:  	register@smart-butler.com

Support:	 	support@smart-butler.com

Beta testing enquires:	beta@smart-butler.com

General enquires:  	info@smart-butler.com


Threads Page

This page is for advanced users only.

SmartButler is driven by scripts. Advanced users can edit existing scripts or add their own to extend SmartButler functionality.

Restore default scripts every time SmartButler starts:

Enable this check box if you want SmartButler to restore default scripts only every time it starts. It is recommended to enable this option.

Restore defaults:

This button will restore the original scripts settings.


Advanced Page

This page is for advanced users only.

For further details please contact technical support.


Script Edit Dialog

Here advanced users can edit existing scripts or their own ones.

Script editor supports the source code text coloring. You should select appropriate script language name in combo box on the toolbar.

You can press F5 button when you want to refresh the coloring of the source code, you may need to refresh the coloring after you pasted some script source code from clipboard etc.


Users Page

This page contains the list of users who ever wrote to you. SmartButler will add them automatically.

Message Prefix:

If you want SmartButler to read User's nickname before each incoming message you can specify any text here. For example if you specify " says: " – SmartButler will read "User name says:" before every message.

Chat prefix:

The same as Message prefix but it is related to the chat messages only.


Dictionary Page

This page contains the list of abbreviations, slang such as LOL, BRB, etc. SmartButler reads them as "laughing out loud", "be right back", etc. You can edit existent or create new dictionary items.

If you want to share your dictionary settings with your friends (or backup the dictionary for future usage) you can export the dictionary by clicking “Export” button. Use “Import” button to import the dictionary.

Process Clipboard:

Enable this check box if you want to apply the dictionary to clipboard contents when SmartButler is reading it.

If you want to restore original dictionary settings – click "Restore Defaults" button.


General Page

Speech mode:

Currently SmartButler supports only MS agent mode. New modes will be added in the future.

Character datafile:

You can select different MS agent character by clicking “…” button, which will change an appearance of your SmartButler (such as Peedy, Robbie, Genie, Merlin and so on). You can also download an additional MS Agent characters by clicking “Download button”.

Balloon text font:

You can change balloon text font parameters by clicking “…” button. You can also restore initial font settings by clicking “Default font” button.

Autohide character after (seconds):

Enable this check box if you want specify a time interval after which character will hide automatically.

Show text in balloons:

Enable this check box if you want read text to be seen in balloons.

Don’t play character animation sounds:

Enable this check box if you don’t want to hear animation sounds of character.

Read clipboard when it changes content:

Enable this check box if you want SmartButler to read the clipboard contents every time when it changes.

Character scale ratio (%):

You can select here dimensions of your SmartButler.

Run when Windows starts:

Enable this check box if you want SmartButler to start working every time when your Windows starts (boots up).

Hot Keys:

You can assign key combinations for most common tasks (such as Read Clipboard, Repeat last phrase, Interrupt, etc.)

Internet Connection Settings:

You may need to adjust your Internet Connection Settings if you use Proxy or Firewall servers.


User Edit dialog

User ID:

Assigned automatically and cannot be changed.

User Name:

Assigned automatically and you can change it if you wish SmartButler to call this user differently.

User Voice:

You can select the voice for reading incoming massages from this user from the list here. If you have <Default voice> selected for this user SmartButler will use speech settings from the Speech page.

Use "Say!" button for checking your speech choice.

Read incoming messages:

Enable this check box if you want SmartButler to read incoming instant messages from this user.

Read incoming Chat Messages:

Enable this check box if you want SmartButler to read incoming chat messages from this user.


Speech Output Page
Speech Page

You can choose different speech parameters for your SmartButler (voice, speed, volume, tone) on this page.

Use "Say!" button for checking your speech choice.

These speech parameters will be used for clipboard reading and will be used as default voice for reading of incoming messages. If you want to select different speech settings for specific user you can do it on the Users page.


Mail Servers Page

If you want SmartButler to let you know about incoming mail you can add your mailbox information here.

I connected to the Internet via modem (dial-up):

Enable this check box only if you have dial-up connection to the Internet.

Mail check interval:

Specifies how often you want SmartButler to check your mailbox.


Edit mail server dialog

Mail Server Type:

POP3 or Hotmail type.

Mail Server:

Specify here your mail server host name or IP address (POP3 only).

Port:

Specify port number you use for POP3 access to your mail server (POP3 only).

Username/Password:

Specify your mail account login information.

Action on new mail arrival:

Here you can type the text you want SmartButler to say and/or execute some program when new mail arrives to your mailbox.

You can check mailbox settings you specified by clicking "Connect" button.


Check for required components dialog

This dialog shows status of the required components. If you see “Failed” near any component - you need to download and install that component.

“Refresh” button refreshes status of all components.

“Download components...” button will open web page with links to the components you have to download.


Dictionary edit dialog

Word:

Put the word here you want to be pronounced differently.

Pronounce as:

Type here how you want this word to be pronounced.


Reminder dialog

If you want SmartButler to remind you about important events you can add them here.


Reminder edit dialog

Note:

Type here the text you want SmartButler to say when the event is happening.

Animation:

You can select character animation for this event.

Also you can specify the date, start and end time of event, and how often to remind you about this event.

Delete when expired:

Enable this check box if you want SmartButler to delete expired event automatically.


Texts Page

This page contains all texts available for reading in SmartButler such as jokes, news, sayings, etc.

Read this group every (min.):

If you want SmartButler to read specific text group automatically you can specify time interval between readings.

Language of this group:

Specifies the voice language of the group.

Read every item only once:

Enable this check box if you want SmartButler to read every text item only once and delete it after reading.


Resources dialog

This dialog box contains string resources used by scripts.

Restore default resources on start up:

Enable this check box if you want SmartButler to restore Resources settings every time when it starts. It is recommended to keep this check box enabled.

You can restore original resource settings by clicking “Restore default resources” button.


SmartButler pop-up menu

Read clipboard:

Click this menu item when you want SmartButler to read the clipboard contents.

Repeat last phrase:

Click this menu item when you want SmartButler to repeat the last phrase.

Hide/Show:

Click this menu item when you want the character to disappear/to show up.

Interrupt:

Click this menu item when you want to stop reading the current text.

Start/Stop:

Click this menu item when you want to stop/start SmartButler. When SmartButler is stopped it will not read any incoming messages. You can use this feature to suspend SmartButler for some period.

Texts:

Here you can listen jokes, news, saying, proverbs, etc. You can also check our web site for text updates by clicking “Download New” button.

Reminder:

Opens Reminder dialog box where you can enter your important events.

Settings:

Opens SmartButler setting dialog box where you can configure your SmartButler.

Registration:

Opens registration dialog box where you can purchase SmartButler or enter the license key.


Methods and properties exposed to a script
Methods and properties:

ApplyDictionary

CanCheckMailNow

EnumChildWindows

EnumVisibleWindows

EnumWindows

FindChildWindow

FindWindow

GetAnimationNames

GetClipboardText

GetCurrentProcessId

GetDlgItemText

GetMailServersObject

GetUsersObject

GetWindowClassName

GetWindowLong

GetWindowProcessId

GetWindowText

GetWindowTextLine

GetWindowTextLineCount

HideCharacter

IsStopping

IsWindowVisible

MailCheckInterval

MoveCharacterTo

PlayAnimation

PostMessage

ReadDialogueBoxes

RegQueryValue

Say

SayWithAnimation

SendMessage

ShellExecute

ShowCharacter

Sleep

WindowFromPoint


Sleep method
Method Sleep

The Sleep method suspends the execution of the current thread for the specified interval.

Sleep (long nMilliseconds)

Parameters

nMilliseconds

[in] Specifies the time, in milliseconds, for which to suspend execution. A value of zero causes the thread to relinquish the remainder of its time slice to any other thread of equal priority that is ready to run. If there are no other threads of equal priority ready to run, the method returns immediately, and the thread continues execution.

Example [VBScript]:

Do Until IsStopping

  ' Do something here

  ' ...

  Sleep(500) ' sleep 0.5 of second

Loop


IsStopping property
Property IsStopping

Returns true when program requires stopping of all script threads.

IsStopping

Return Values

Returns true when program requires stopping of all script threads.

Example [VBScript]:

Do Until IsStopping

  ' Do something here

  ' ...

Loop


FindWindow method
Method FindWindow

The FindWindow method retrieves a handle to the top-level window whose class name and window name match the specified strings. This method does not search child windows. This method does not perform a case-sensitive search.

To search child windows use the FindChildWindow method.

FindWindow (String strClassName, String strWindowName)

Parameters

strClassName

[in] String that specifies the windows class name.

strWindowName

[in] String that specifies the window name (the window's title). If this parameter is Null, all window names match.

Return Values

If the method succeeds, the return value is a handle to the window that has the specified class and window names.

If the method fails, the return value is zero.

Example [VBScript]:

Dim hWnd

Do Until IsStopping

  ' MS Window Calculator has class name equal to "SciCalc"

  hWnd=FindWindow("SciCalc", Null)

  ' hWnd will be not equal to zero if any window with "SciCalc"

  ' class name is oppened

  If hWnd <> 0 Then

    ' Inform about presence of calculator and leave the loop.

    Say "Calculator is here!"

    Exit Do

  End If

Loop


FindChildWindow method
Method FindChildWindow

The FindChildWindow method retrieves a handle to a child window whose class name and window name match the specified strings. This method does not perform a case-sensitive search.

FindChildWindow (long nParentHwnd, String strClassName, String strWindowName)

Parameters

nParentHwnd

[in] Handle to the parent window whose child windows are to be searched.

strClassName

[in] String that specifies the windows class name.

strWindowName

[in] String that specifies the window name (the window's title). If this parameter is Null, all window names match.

Return Values

If the method succeeds, the return value is a handle to the window that has the specified class and window names.

If the method fails, the return value is zero.

Example [VBScript]:

Dim hWnd

Dim hChildWnd

hWnd=FindWindow("SomeClassName", "SomeTitle")

If hWnd <> 0 Then

  hChildWnd=FindChildWindow(hWnd, "SomeChildClassName", "SomeChildTitle")

  If hChildWnd <> 0 Then

    ' Here do something

    ' ...

  End If

End If


GetWindowText method
Method GetWindowText

The GetWindowText method copies the text of the specified window's title bar (if it has one) into a buffer. If the specified window is a control, the text of the control is copied.

GetWindowText (long nHwnd)

Parameters

nHwnd

[in] Handle to the window or control containing the text.

Return Values

If the method succeeds, the return value is a string containing text.

If the method fails, error exception will be thrown.

Example [VBScript]:

' it will enumerate all visible top-level windows

' then it will say how many of them has been found

' and at last it will say all titles

hWndarray=EnumVisibleWindows

Say "Found " & CStr(UBound(hWndarray) - LBound(hWndarray)) & " opened windows"

For i=LBound(hWndarray) To UBound(hWndarray)

  Say GetWindowText(hWndarray(i))

Next


GetWindowTextLine method
Method GetWindowTextLine

This method retrieves a line of text from an edit control. This call is not processed for a single-line edit control.

GetWindowTextLine (long hWnd, long nLineIndex)

Parameters

nHwnd

[in] Handle to the window or control containing the text.

nLineIndex

[in] Specifies the zero-based index of the line to retrieve from a multiline edit control. A value of zero specifies the topmost line. This parameter is ignored by a single-line edit control.

Return Values

If the method succeeds, the return value is a string containing line of text.

If the method fails, error exception will be thrown.

Example [VBScript]:

' ...

' hWnd contains valid window handle

' of the multiline edit control

' Say text of fifth line

Say GetWindowTextLine(hWnd, 4)


GetWindowTextLineCount method
Method GetWindowTextLineCount

This method retrieves the number of lines in a multiple-line edit control.

GetWindowTextLineCount (long hWnd)

Parameters

nHwnd

[in] Handle to the window or control containing the text.

Return Values

If the method succeeds, an integer containing the number of lines in the multiple-line edit control. If no text has been entered into the edit control, the return value is one.

If the method fails, error exception will be thrown.

Example [VBScript]:

' ...

' hWnd contains valid window handle

' of the multiline edit control

' Say number of the lines

Say "Edit control contains " & CStr(GetWindowTextLineCount(hWnd)) & " lines of text"


GetDlgItemText method
Method GetDlgItemText

The GetDlgItemText method retrieves the title or text associated with a control in a dialog box.

GetDlgItemText (long nDlgHwnd, long nControlID)

Parameters

nDlgHwnd

[in] Handle to the window or control containing the text.

nControlID

[in] Specifies the identifier of the control whose title or text is to be retrieved.

Return Values

If the method succeeds, the return value is a string containing text.

If the method fails, error exception will be thrown.

Example [VBScript]:

' It will say text contained control with ID 100

' (each dialog control has ID)

' in dialog box with window handle hwnd

Say GetDlgItemText(hwnd, 100)


Say method
Method Say

Produce sound output of text string with Text-To-Speech engine with default voice. (See Speech Output page)

Say (String strText)

Parameters

strText

[in] Text to speak with default voice (See Speech Output page). If strText is empty – method simply returns.

Return Values

No return values.

If the method fails, error exception will be thrown.

Example [VBScript]:

' say with default voice "Hello world!"

Say "Hello world!"


MoveCharacterTo method
Method MoveCharacterTo

Moves character into specified screen position. Applicable for MSAgent mode only, in other modes - simply returns.

MoveCharacterTo (long nX, long nY)

Parameters

nX

[in] new character’s screen X-coordinate.

nY

[in] new character’s screen X-coordinate.

Return Values

No return values.

If the method fails, error exception will be thrown.

Example [VBScript]:

' show MS Agent character first to produce moving animation

' on next method

ShowCharacter

' move character to screen coordinates (100,100)

MoveCharacterTo 100, 100


ShowCharacter method
Method ShowCharacter

Shows character. Applicable for MSAgent mode only, in other modes - simply returns.

ShowCharacter

Return Values

No return values.

If the method fails, error exception will be thrown.

Example [VBScript]:

' show MS Agent character

ShowCharacter


HideCharacter method
Method HideCharacter

Hides character. Applicable for MSAgent mode only, in other modes - simply returns.

HideCharacter

Return Values

No return values.

If the method fails, error exception will be thrown.

Example [VBScript]:

' hide MS Agent character

HideCharacter


SayWithAnimation method
Method SayWithAnimation

Produce sound output of text string with Text-To-Speech engine with default voice. (See Speech Output page) and play character animation.

SayWithAnimation (String strText, String strAnimationName)

Parameters

strText

[in] Text to speak with default voice (See Speech Output page). If strText is empty – method simply returns.

strAnimationName

[in] Animation name, specific for concrete character (see GetAnimationNames method). Applicable for MSAgent mode only, ignored in other modes.

Return Values

No return values.

If the method fails, error exception will be thrown.

Example [VBScript]:

' it will say "I like reading!" and play animation "Read"

' if currently active MS Agent character supports it

SayWithAnimation "I like reading!", "Read"


PlayAnimation method
Method PlayAnimation

Play character animation. Applicable for MSAgent mode only, in other modes - simply returns.

PlayAnimation (String strAnimationName)

Parameters

strAnimationName

[in] Animation name, specific for concrete character (See GetAnimationNames method).

Return Values

No return values.

If the method fails, error exception will be thrown.

Example [VBScript]:

' it will play animation "Think"

' if currently active MS Agent character supports it

PlayAnimation "Think"


EnumWindows method
Method EnumWindows

Returns array of window handles for all top-level windows.

EnumWindows

Return Values

If the method succeeds, the array of window handles.

If the method fails, error exception will be thrown.

Example [VBScript]:

' it will enumerate all top-level windows (even invisible)

' and then it will say how many of them has been found

hWndarray=EnumWindows

Say "Found " & CStr(UBound(hWndarray) - LBound(hWndarray)) & " opened windows"


GetWindowClassName method
Method GetWindowClassName

The GetWindowClassName method retrieves the name of the class to which the specified window belongs.

GetWindowClassName (long nHwnd)

Parameters

nHwnd

[in] Handle to the window or control containing the text.

Return Values

If the method succeeds, the return value is a class name string.

If the method fails, error exception will be thrown.

Example [VBScript]:

' it will enumerate all visible top-level windows

' then it will say how many of them has been found

' and at last it will say all theirs class names

hWndarray=EnumVisibleWindows

Say "Found " & CStr(UBound(hWndarray) - LBound(hWndarray)) & " opened windows"

For i=LBound(hWndarray) To UBound(hWndarray)

  Say GetWindowClassName(hWndarray(i))

Next


GetAnimationNames method
Method GetAnimationNames

Returns array of animations names for current character.  Applicable for MSAgent mode only, in other modes – returns empty array.

GetAnimationNames

Return Values

If the method succeeds, the return value is an array of animations names

If the method fails, error exception will be thrown.

Example [VBScript]:

' it will retrieve all supported animation names

' for currently active MS Agent character

' then it will say number of retrieved animation names

' and at last it will say all animation names

' (it can be a very long list)

strAnimationsArray=GetAnimationNames

Say "Current MS Agent character supports " & CStr(UBound(strAnimationsArray) - LBound(strAnimationsArray)) & " animations!"

For i=LBound(strAnimationsArray) To UBound(strAnimationsArray)

  Say strAnimationsArray(i)

Next


GetWindowLong method
Method GetWindowLong

The GetWindowLong method retrieves information about the specified window. The method also retrieves the 32-bit (long) value at the specified offset into the extra window memory.

GetWindowLong (long nHwnd, long nIndex)

Parameters

nHwnd

[in] Handle to the window.

nIndex

[in] Specifies the zero-based offset to the value to be retrieved. Valid values are in the range zero through the number of bytes of extra window memory, minus four; for example, if you specified 12 or more bytes of extra memory, a value of 8 would be an index to the third 32-bit integer.

Return Values

If the method succeeds, the return value is the requested 32-bit value.

If the method fails, error exception will be thrown.

Example [VBScript]:

' it will retrieve style of the window with handle hWnd

' See MSDN documentation for GetWindowLong

nWindowStyle=GetWindowLong(hWnd, -16)


EnumChildWindows method
Method EnumChildWindows

EnumChildWindows (long nParentHwnd)

Parameters

nParentHwnd

[in] Handle to the parent window whose child windows are to be enumerated.

Return Values

If the method succeeds, the array of handles to the child windows of the nParentHwnd.

If the method fails, error exception will be thrown.

Remarks

If a child window has created child windows of its own, EnumChildWindows enumerates those windows as well. A child window that is moved or repositioned in the Z order during the enumeration process will be properly enumerated. The method does not enumerate a child window that is destroyed before being enumerated or that is created during the enumeration process.

Example [VBScript]:

hChildWndArray=EnumChildWindows(hParentWnd)

Say "Found " & CStr(UBound(hChildWndArray) - LBound(hChildWndArray)) & " child windows for specified window!"


ApplyDictionary method
Method ApplyDictionary

Apply dictionary to the specified string (See Dictionary Page).

ApplyDictionary (String strText)

Parameters

strText

[in] String to which apply dictionary.

Return Values

If the method succeeds, the result string after applying of the dictionary.

If the method fails, error exception will be thrown.

Example [VBScript]:

REM it will apply dictionary to the string "LOL - it's very funny!"

REM For example:

REM if dictionary contains entry for "LOL" (to replace it with

REM "laughing out loud")

REM it will return value:

REM "laughing out loud - it's very funny!"

REM with default dictionary it must say:

REM "laughing out loud - it's very funny!"

strResult=ApplyDictionary("LOL - it's very funny!")

say strResult


ReadDialogueBoxes property
Property ReadDialogueBoxes

Returns true when program requires reading of dialogue boxes. (See General Page)

ReadDialogueBoxes

Return Values

Returns true when program requires reading of dialogue boxes.

Example [VBScript]:

If ReadDialogueBoxes Then

  ' here proceed reading of dialogs or whatever

  ' ....

End If


IsWindowVisible method
Method IsWindowVisible

Retrieves the visibility state of the specified window.

IsWindowVisible (long nHwnd)

Parameters

nHwnd

[in] Handle to the window to test.

Return Values

If the method succeeds, returns true if specified window is visible.

If the method fails, error exception will be thrown.

Example [VBScript]:

' trying to find some window

hWnd=FindWindow("SomeWndClass", "SomeWndTitle")

If hWnd <> 0 Then

  If IsWindowVisible(hWnd) Then

    ' window exist and visible

    Say "Window is visible!"

  Else

    ' window exist but invisible

    Say "Window is invisible!"

  End If

End If


GetWindowProcessId method
Method GetWindowProcessId

Retrieves the identifier of the process that created the specified window.

GetWindowProcessId (long nHwnd)

Parameters

nHwnd

[in] Handle to the window.

Return Values

If the method succeeds, the return long value is the identifier of the process that created the window.

If the method fails, error exception will be thrown.

Example [VBScript]:

' trying to find some window

hWnd=FindWindow("SomeWndClass", "SomeWndTitle")

If hWnd <> 0 Then

  nProcessID=GetWindowProcessID(hWnd)

  Say "Process ID is: " & CStr(nProcessID)

End If


GetCurrentProcessId method
Method GetCurrentProcessId

Retrieves the process identifier of the SmartButler process.

GetCurrentProcessId

Return Values

If the method succeeds, the return long value is the identifier of the SmartButler process.

If the method fails, error exception will be thrown.

Example [VBScript]:

Say "SmartButler process ID is: " & CStr(GetCurrentProcessID)


EnumVisibleWindows method
Method EnumVisibleWindows

Returns array of window handles for all top-level visible windows.

EnumVisibleWindows

Return Values

If the method succeeds, the array of window handles.

If the method fails, error exception will be thrown.

Example [VBScript]:

' it will enumerate all visible top-level windows

' and then it will say how many of them has been found

hWndarray=EnumVisibleWindows

Say "Found " & CStr(UBound(hWndarray) - LBound(hWndarray)) & " visible windows"


CanCheckMailNow property
Property CanCheckMailNow

The return true when SmartButler can proceed mail checking.

CanCheckMailNow

Return Values

The return true when SmartButler can proceed mail checking.

Remarks

CanCheckMailNow depends on Mail Servers Page settings – If “Check mail only if online” has been checked CanCheckMailNow will return true only if there is at least one RAS (dial-up) connection active. If “Check mail only if online” has been unchecked CanCheckMailNow will return true always.

Example [VBScript]:

' this sample will wait when SmartButler can check mail

' and then it inform user about successful condition

' for mail checking and will exit loop

Do

  If CanCheckMailNow Then

    Say "Now you can check mail"

    Exit Do

  End If

  Sleep(1000)

Loop


MailCheckInterval property
Property MailCheckInterval

Returns mail check interval selected on Mail Servers Page

MailCheckInterval

Return Values

Returns mail check interval selected on Mail Servers Page

Example [VBScript]:

'Set initial value for LastMailCheckTime - current time

LastMailCheckTime=Now

Do

  If Abs(DateDiff("n", LastMailCheckTime, Now)) >= MailCheckInterval Then

    ' If difference between time stored in LastMailCheckTime

    ' and current time bigger or equal than MailCheckInterval

    ' ...

    ' do here something

    ' ...

    ' update LastMailCheckTime

    LastMailCheckTime=Now

  End If

  Sleep(500)

Loop


ShellExecute method
Method ShellExecute

This method performs an action on a file. The file can be an executable file or a document.

ShellExecute (String strVerb, String strFile, String strParameters, String strDirectory, long nShow)

Parameters

strVerb

[in] A string, referred to as a verb, which specifies the action to be performed. The set of available verbs depends on the particular file or folder. Generally, the actions available from an object's shortcut menu are available verbs. The following verbs are commonly used:

edit  	Launches an editor and opens the document for editing. If strFile is not a document file, the method will fail.

explore 	Explores the folder specified by strFile.

find 	Initiates a search starting from the specified directory by strFile.

open  	Opens the file specified by the strFile parameter. The file can be an executable file, a document file, or a folder.

print  	Prints the document file specified by strFile. If strFile is not a document file, the method will fail.

strFile

[in] A string that specifies the file or object on which to execute the specified verb. Note that not all verbs are supported on all objects. For example, not all document types support the "print" verb.

strParameters

[in] If the strFile parameter specifies an executable file, strParameters is a string that specifies the parameters to be passed to the application. The format of this string is determined by the verb that is to be invoked. If strFile specifies a document file, strParameters should be an empty string.

strDirectory

[in] A string that specifies the default directory.

nShow

[in] Long value that specify how an application is to be displayed when it is opened. If strFile specifies a document file, the flag is simply passed to the associated application. It is up to the application to decide how to handle it.

0 	Hides the window and activates another window.

1 	Activates and displays a window. If the window is minimized or maximized, Windows restores it to its original size and position. An application should specify this flag when displaying the window for the first time.

2 	Activates the window and displays it as a minimized window.

3 	Activates the window and displays it as a maximized window.

4 	Displays a window in its most recent size and position. The active window remains active.

5 	Activates the window and displays it in its current size and position.

6 	Minimizes the window and activates the next top-level window in the z-order.

7 	Displays the window as a minimized window. The active window remains active.

8 	Displays the window in its current state. The active window remains active.

9 	Activates and displays the window. If the window is minimized or maximized, Windows restores it to its original size and position. An application should specify this flag when restoring a minimized window.

10 	Shows window with default parameters

Return Values

No return values.

If the method fails, error exception will be thrown.

Example [VBScript]:

REM Launches the Shell's Find utility for "C:\Program Files" directory

ShellExecute "find", "C:\Program Files", "", "", 1

' Explores "C:\Program Files" directory

ShellExecute "explore", "C:\Program Files", "", "", 1

' Launches minimized Notepad editor

ShellExecute "open", "notepad.exe", "", "", 2


PostMessage method
Method PostMessage

The PostMessage method places (posts) a message in the message queue associated with the thread that created the specified window and returns without waiting for the thread to process the message.

PostMessage (long hWnd, long nMsg, long wParam, long lParam)

Parameters

hWnd

[in] Handle to the window whose window procedure is to receive the message. The following value has special meaning:

65535	The message is posted to all top-level windows in the system, including disabled or invisible unowned windows, overlapped windows, and pop-up windows. The message is not posted to child windows.

nMsg

[in] Specifies the message to be posted.

wParam

[in] Specifies additional message-specific information.

lParam

[in] Specifies additional message-specific information.

Return Values

No return values.

If the method fails, error exception will be thrown.

Remarks

Windows 2000 or later: There is a limit of 10,000 posted messages per message queue. This limit should be sufficiently large. If your application exceeds the limit, it should be redesigned to avoid consuming so many system resources.

Be careful with posting of messages – some message types require memory addresses for return parameters. Scripting languages don’t allow handling of such message types correctly – it may corrupt memory of SmartButler process or of the any other process.

Example [VBScript]:

' hwnd contains valid handle to the window

' 515 - this message is posted when the user double-clicks

' the left mouse button while the cursor is in the client area of a window.

' See MSDN Documentation for message WM_LBUTTONDBLCLK

' this will simulate double-click of the left mouse button

' in the coordinates (0,0) of the specified window

PostMessage hwnd, 515, 0, 0

' Another example:

' Makes loop until it finds running instance or the MS Windows Calculator

REM then it posts three messages to the calculator's window

' and exits from loop

' 258 - this message is sent when user presses keyboard

' wParam contains the character code of the key that was pressed

' See MSDN Documentation for message WM_CHAR

' this will simulate that user input "123" into calculator window

Do

  hWnd=FindWindow("SciCalc", null)

  If hWnd <> 0 Then

    PostMessage hWnd, 258, Asc("1"), 0

    PostMessage hWnd, 258, Asc("2"), 0

    PostMessage hWnd, 258, Asc("3"), 0

    Exit Do

  End If

  Sleep(500)

Loop


RegQueryValue method
Method RegQueryValue

The RegQueryValue method reads value from the registry.

RegQueryValue (long nKey, String strSubKey, String strValueName)

Parameters

nKey

[in] Specifies the registry root handle. Only these values are supported:

0 - HKEY_CLASSES_ROOT

1 - HKEY_CURRENT_CONFIG

2 - HKEY_CURRENT_USER

3 - HKEY_LOCAL_MACHINE

4 - HKEY_USERS

5 - HKEY_PERFORMANCE_DATA (Windows NT/2000 or later only)

6 - HKEY_DYN_DATA (Windows 95/98/Me only)

strSubKey

[in] Specifies the string containing the name of the subkey to open.

strValueName

[in] Specifies string containing the name of the value to query.

Return Values

If the method succeeds, the return long, string or array read from the registry.

If the method fails, error exception will be thrown.

Remarks

RegQueryValue supports only REG_SZ, REG_DWORD and REG_BINARY registry value types.

Method will return numeric value if strValueName points to REG_DWORD value into registry.

Method will return string value if strValueName points to REG_SZ value into registry.

Method will return array of bytes if strValueName points to REG_BINARY value into registry.

Windows 95/98/Me: No registry subkey or value name may exceed 255 characters.

Example [VBScript]:

On Error Resume Next

Dim regValue

Const HKEY_CURRENT_USER = 2

' now trying to read "LastOwner" value from the registry

' this sample will work if you use ICQ messenger.

regValue=RegQueryValue(HKEY_CURRENT_USER, "Software\Mirabilis\ICQ\Owners", "LastOwner")

If Err = 0 Then

  Say "Last ICQ Number used on you PC is " & CStr(regValue)

Else

  Say Err.Description

End If


SendMessage method
Method SendMessage

The SendMessage method sends the specified message to a window or windows. It calls the window procedure for the specified window and does not return until the window procedure has processed the message.

SendMessage (long hWnd, long nMsg, long wParam, long lParam)

Parameters

hWnd

[in] Handle to the window whose window procedure is to receive the message. The following value has special meaning:

65535	The message is sent to all top-level windows in the system, including disabled or invisible unowned windows, overlapped windows, and pop-up windows. The message is not sent to child windows.

nMsg

[in] Specifies the message to be sent.

wParam

[in] Specifies additional message-specific information.

lParam

[in] Specifies additional message-specific information.

Return Values

If the method succeeds, the return long value specifies the result of the message processing; it depends on the message sent.

If the method fails, error exception will be thrown.

Remarks

Be careful with sending of messages – some message types require memory addresses for return parameters. Scripting languages don’t allow handling of such message types correctly – it may corrupt memory of SmartButler process or of the any other process.

Example [VBScript]:

' Broadcast WM_SHOWWINDOW to all toplevel windows

' hide all top-level windows (some application may ignore this message)

SendMessage 65535, 24, 0, 1

' Wait 2 seconds

Sleep(2000)

' show all top-level windows (some application may ignore this message)

SendMessage 65535, 24, 1, 1


WindowFromPoint method
Method WindowFromPoint

The WindowFromPoint method retrieves a handle to the window that contains the specified point.

WindowFromPoint (long X, long Y)

Parameters

X

[in] X screen coordinate of the point to be checked.

Y

[in] Y screen coordinate of the point to be checked.

Return Values

If the method succeeds, the return long value is a handle to the window that contains the point. If no window exists at the given point, the return value is zero. If the point is over a static text control, the return value is a handle to the window under the static text control.

If the method fails, error exception will be thrown.

Remarks

The WindowFromPoint method does not retrieve a handle to a hidden or disabled window, even if the point is within the window.

Example [VBScript]:

hWnd=WindowFromPoint(100, 100)

If hWnd <> 0 Then

  Say "There is a window at point (100,100) with handle: " & CStr(hWnd)

Else

  ' probably it will never say this because Desktop is a window with handle too

  Say "There is no window at point (100,100)"

End If


GetClipboardText method
Method GetClipboardText

This method retrieves text content from clipboard.

GetClipboardText

Return Values

If the method succeeds, the return value is a string containing clipboard content.

If the method fails, error exception will be thrown.

Example [VBScript]:

' Will read text contained into clipboard

Say GetClipboardText


GetMailServersObject method
Method GetMailServersObject

Returns instance of MailServersObject

GetMailServersObject

Return Values

If the method succeeds, the return value is an instance of MailServersObject

If the method fails, error exception will be thrown.

Example [VBScript]:

Dim objMailServers

Dim i

'Get instance of MailServersObject

Set objMailServers=GetMailServersObject

' Say name of every mail server

For i=0 To objMailServers.Count-1

  Say objMailServers(i).MailServer

Next

' Release MailServersObject to free up memory

Set objMailServers=Nothing


GetUsersObject method
Method GetUsersObject

Returns instance of UsersObject

GetUsersObject

Return Values

If the method succeeds, the return value is an instance of UsersObject

If the method fails, error exception will be thrown.

Example [VBScript]:

Dim objUsers

Dim i

'Get instance of UsersObject

Set objUsers=GetUsersObject

' Say name of every users

For i=0 To objUsers.Count-1

  Say objUsers(i).Name

Next

' Release UsersObject to free up memory

Set objUsers=Nothing