TestWorks Technical Notes: CAPBAK/MSW, Ver. 3.2 (June 1998) -- C Interface Definitions

CAPBAK/MSW Ver. 3.2
C Interface Definitions

This document provides a complete yet compact definition of all CAPBAK/MSW Ver. 3.2 C function calls. These are the C language functions that are generated during a recording and which are interpreted during playback. Note that there is additional C functionality available during playback that involves system calls, etc. That functionality is documented in the CAPBAK/MSW 2.6 Manual.

Function calls that begin with cb_ refer to either True-Time or OCR-based actions, while calls that begin with cbw_ refer to ObjectMode operation.

Calls are presented in this list in strict alphabetic order with int types first and void types last.

Definition of Call Explanation
Editable Commands
These functions are NOT produced during the recording process but may be edited into recorded or hand-created scripts.
int cb_change_cwd("path"); Changes the current working directory of the process to the one specified in "path".
int cb_check_area("filename", x, y, width, height); Compare an image of the screen area that begins at x, y and has a width of width and a height of height with the image saved in file "filename".
int cb_close("file_handle"); Closes the file identified by the "file handle".
int cb_file_exists("filename"); Returns 1 if file "filename" exists, 0 if it does not.
int cb_om_menu_select("Title", "Class", "Menu", Menudelay); Select menu item named by "Menu" in menu object specified by "Title" and "Class". Delay for Menudelay milliseconds before preceding.
int cb_open("filename"); Opens the file for reading. Returns a file handle to be used with cb_close(), cb_read_string().
int cb_pixel_compare(red, green, blue, x, y); Compares the RGB specified with the RGB value of the pixel at location x, y, and returns 1, if they match else 0.
int cb_random(upper_bound); Returns a randomly selected integer value greater than or equal to 0 and less than upper_bound. The value of upper_bound must satisfy: 1 <= upper_bound <= 32766.
int cb_read_string("char_array", "delimiter", "file_handle"); Reads a string from the opened file("file_handle") and fills ("char_array") with it.
int cb_start_app("application_filename); Starts up the Windows application whose filename is "application_filename".
void cb_type("char_string", delay_between_characters); Reads the string "char_string" which can be either a character array or a quoted string, and types the string's characters into the active window.
void cb_wait(wait_time); Wait or "sleep" for wait_time seconds before continuing execution of the keysave file.

Recordable/Editable Commands
Pure True-Time Operation
These functions are used to express activities captured during pure True-Time recording but also can be edited.

void cb_mbutton_down_rel("button", x, y, delay); After a delay of delay milliseconds, identifies a mouse button press by an offset of x, y relative to the last mouse position.
void cb_mbutton_down("button", x, y, delay); Identifies a mouse button press at position x, y after a delay of n milliseconds.
void cb_mbutton_up("button", x, y, delay); Identifies a mouse button release at position x, y after a delay of n millisecond.
void cb_mbutton_up_rel("button", x, y, delay); After delay milliseconds, identifies a mouse button release by an offset of x, y relative to the last mouse position.
void cb_move_mouse(x, y, delay); After a delay of n milliseconds, mouse cursor moves by a offset of x, y relative to the last mouse position.
void cb_move_mouse_rel(x, y, delay); After a delay of n milliseconds, mouse cursor moves by an offset of x, y relative to the last mouse position.

Recordable/Editable Commands
Pure True-Time Operation
These functions are used to express activities captured during mixed ObjectMode and True-Time recording but also can be edited.
void cb_key_down(key, delay); Press the designated key after delay milliseconds.
void cb_key_up(key, delay); Lift the designated key after delay milliseconds.
void cb_save_area("filename", x, y, width, height); Save an image of the screen that begins at position x, y and has width of width and a height of height into basename.bxx when the HotKey window's Save Area button or the F5 function key are used.
void cb_save_area_ascii("filename", x, y, width, height); Save the text recognized from the search area that begins at position x, y and has a width of width and a height of height in the file "filename".
void cb_save_screen("filename"); Save an image of the entire screen into file "filename".
void cb_save_window( "filename", x, y); Save an image of the top window containing the location x, y into the file "filename".
void cb_save_window_ascii("filename", x, y); Save the text recognized from the window containing the location x, y into the file "filename".
void cb_sync_ascii("string", x, y); Looks for the string "string" in the window containing the location x, y.
void cb_sync_win_activate(window_name, x, y, width, height); Wait for a window named window_name that has just activated. Move it so that its upper left-hand corner is at coordinate x, y and size it so it has width of width and a height of height. If x and y are 0 then don't move or resize the window.
void cb_sync_win_activate_maximize(window_name); Wait for a window named window_name that has just activated. When it activates, maximize it.
void cb_sync_win_image("filename", x, y, width, height); Finds the window of the screen whose images matches that saved in basename.sxx, then moves the window so that its upper left corner is at coordinate x, y.
void cb_wait_area("filename", x, y, width, height); Wait until an image of the area that begin at x, y and has a width of width a height of height matches the image saved in the file "filename" before continuing execution of the keysave file script.

Recordable/Editable Commands
Object-Mode Operation
These functions are used to record pure-ObjectMode activities, but may be edited into recorded or hand-created scripts.

void cbw_button_clicked("TargetClass", "TargetWindow", ButtonId, "Buttontext"); Clicks button identified by either Buttontext or ButtonId in window identified by TargetClass and TargetWindow.
void cbw_key_string("Keys", ShiftState, keydelay); Send keystrokes specified by "Keys" to the application under test and a delay between each key of keydelay milliseconds. When done, leaves the shift key down if "ShiftState" is non-zero; otherwise, leaves the shift key up.
void cbw_mbutton_down("button", x, y, delay); Identifies a mouse button press at position x, y after a delay of n milliseconds.
void cbw_mbutton_down_rel("button", x, y, delay); After a delay of delay milliseconds, identifies a mouse button press by an offset of x, y relative to the last mouse position.
void cbw_mbutton_up("button", x, y, delay); Identifies a mouse button release at position x, y after a delay of n millisecond.
void cbw_mbutton_up_rel("button", x, y, delay); After delay milliseconds, identifies a mouse button release by an offset of x, y relative to the last mouse position.
void cbw_move_mouse(x, y, delay); After a delay of n milliseconds, mouse cursor moves by a offset of x, y relative to the last mouse position.
void cbw_move_mouse_rel(x, y, delay); After a delay of n milliseconds, mouse cursor moves by an offset of x, y relative to the last mouse position.

Recordable/Editable Commands
Object-Mode Operation
These functions are used to create actions for pure-ObjectMode playback.

void cbw_combobox_doubleclick("TargetClass", "TargetWindow", ComboboxId); Double click combo box identified by ComboboxId in window identified by TargetClass and TargetWindow.
void cbw_combobox_selection("TargetClass", "TargetWindow", ComboboxId, ItemId); Selects ItemId in combo box identified by ComboboxId in window identified by TargetClass and TargetWindow.
void cbw_combobox_setedit("TargetClass", "TargetWindow", ComboboxId, "Text"); Change text of combo box identified by ComboboxId to "Text" in window identified by TargetClass and TargetWindow.
void cbw_hscroll("TargetClass", "TargetWindow", ScrollBarId, "SubMessage", posThumb); Send "SubMessage" to horizontal scrollbar specified by ScrollBarId in window identified by TargetClass and TargetWindow and if "Submessage" equals SB_THUMBTRACK or SB_THUMBPOSITION then positions the scrollbar's Thumb at posThumb.
void cbw_hscroll_child("TargetClass", "TargetWindow", "ChildClass", ChildId, ScrollBarId, "SubMessage", posThumb); If ChildId is zero or greater than send "SubMessage" to horizontal child scrollbar specified by "ChildClass" and in window identified by TargetClass and TargetWindow. Else send "SubMessage" to horizontal child scrollbar specified by ScrollBarId in window identified by TargetClass and TargetWindow.
void cbw_listbox_doubleclick("TargetClass", "TargetWindow", ListboxId); Double click list box identified by ListboxId in window identified by TargetClass and TargetWindow.
void cbw_listbox_selection("TargetClass", "TargetWindow", ListboxId, ItemId); Selects ItemId in list box identified by ListboxId in window identified by TargetClass and TargetWindow.
void cbw_vscroll("TargetClass", "TargetWindow", ScrollBarId, "SubMessage", posThumb); Send "SubMessage" to vertical scrollbar specified by ScrollBarId in window identified by TargetClass and TargetWindow and if "Submessage" equals SB_THUMBTRACK or SB_THUMBPOSITION then positions the scrollbar's Thumb at posThumb.
void cbw_vscroll_child("TargetClass", "TargetWindow", "ChildClass", ChildId, ScrollBarId, "SubMessage", posThumb); If ChildId is zero or greater than send "SubMessage" to vertical child scrollbar specified by "ChildClass" and in window identified by TargetClass and TargetWindow. Else send "SubMessage" to vertical child scrollbar specified by ScrollBarId in window identified by TargetClass and TargetWindow.

Definition of Call	Explanation
Editable Commands These functions are NOT produced during the recording process but may be edited into recorded or hand-created scripts.
`int cb_change_cwd("path");`	Changes the current working directory of the process to the one specified in "path".
`int cb_check_area("filename", x, y, width, height);`	Compare an image of the screen area that begins at x, y and has a width of width and a height of height with the image saved in file "filename".
`int cb_close("file_handle");`	Closes the file identified by the "file handle".
`int cb_file_exists("filename");`	Returns 1 if file "filename" exists, 0 if it does not.
`int cb_om_menu_select("Title", "Class", "Menu", Menudelay);`	Select menu item named by "Menu" in menu object specified by "Title" and "Class". Delay for Menudelay milliseconds before preceding.
`int cb_open("filename");`	Opens the file for reading. Returns a file handle to be used with cb_close(), cb_read_string().
`int cb_pixel_compare(red, green, blue, x, y);`	Compares the RGB specified with the RGB value of the pixel at location x, y, and returns 1, if they match else 0.
`int cb_random(upper_bound);`	Returns a randomly selected integer value greater than or equal to 0 and less than upper_bound. The value of upper_bound must satisfy: 1 <= upper_bound <= 32766.
`int cb_read_string("char_array", "delimiter", "file_handle");`	Reads a string from the opened file("file_handle") and fills ("char_array") with it.
`int cb_start_app("application_filename);`	Starts up the Windows application whose filename is "application_filename".
`void cb_type("char_string", delay_between_characters);`	Reads the string "char_string" which can be either a character array or a quoted string, and types the string's characters into the active window.
`void cb_wait(wait_time);`	Wait or "sleep" for wait_time seconds before continuing execution of the keysave file.
Recordable/Editable Commands Pure True-Time Operation These functions are used to express activities captured during pure True-Time recording but also can be edited.
`void cb_mbutton_down_rel("button", x, y, delay);`	After a delay of delay milliseconds, identifies a mouse button press by an offset of x, y relative to the last mouse position.
`void cb_mbutton_down("button", x, y, delay);`	Identifies a mouse button press at position x, y after a delay of n milliseconds.
`void cb_mbutton_up("button", x, y, delay);`	Identifies a mouse button release at position x, y after a delay of n millisecond.
`void cb_mbutton_up_rel("button", x, y, delay);`	After delay milliseconds, identifies a mouse button release by an offset of x, y relative to the last mouse position.
`void cb_move_mouse(x, y, delay);`	After a delay of n milliseconds, mouse cursor moves by a offset of x, y relative to the last mouse position.
`void cb_move_mouse_rel(x, y, delay);`	After a delay of n milliseconds, mouse cursor moves by an offset of x, y relative to the last mouse position.
Recordable/Editable Commands Pure True-Time Operation These functions are used to express activities captured during mixed ObjectMode and True-Time recording but also can be edited.
`void cb_key_down(key, delay);`	Press the designated key after delay milliseconds.
`void cb_key_up(key, delay);`	Lift the designated key after delay milliseconds.
`void cb_save_area("filename", x, y, width, height);`	Save an image of the screen that begins at position x, y and has width of width and a height of height into basename.bxx when the HotKey window's Save Area button or the F5 function key are used.
`void cb_save_area_ascii("filename", x, y, width, height);`	Save the text recognized from the search area that begins at position x, y and has a width of width and a height of height in the file "filename".
`void cb_save_screen("filename");`	Save an image of the entire screen into file "filename".
`void cb_save_window( "filename", x, y);`	Save an image of the top window containing the location x, y into the file "filename".
`void cb_save_window_ascii("filename", x, y);`	Save the text recognized from the window containing the location x, y into the file "filename".
`void cb_sync_ascii("string", x, y);`	Looks for the string "string" in the window containing the location x, y.
`void cb_sync_win_activate(window_name, x, y, width, height);`	Wait for a window named window_name that has just activated. Move it so that its upper left-hand corner is at coordinate x, y and size it so it has width of width and a height of height. If x and y are 0 then don't move or resize the window.
`void cb_sync_win_activate_maximize(window_name);`	Wait for a window named window_name that has just activated. When it activates, maximize it.
`void cb_sync_win_image("filename", x, y, width, height);`	Finds the window of the screen whose images matches that saved in basename.sxx, then moves the window so that its upper left corner is at coordinate x, y.
`void cb_wait_area("filename", x, y, width, height);`	Wait until an image of the area that begin at x, y and has a width of width a height of height matches the image saved in the file "filename" before continuing execution of the keysave file script.
Recordable/Editable Commands Object-Mode Operation These functions are used to record pure-ObjectMode activities, but may be edited into recorded or hand-created scripts.
`void cbw_button_clicked("TargetClass", "TargetWindow", ButtonId, "Buttontext");`	Clicks button identified by either Buttontext or ButtonId in window identified by TargetClass and TargetWindow.
`void cbw_key_string("Keys", ShiftState, keydelay);`	Send keystrokes specified by "Keys" to the application under test and a delay between each key of keydelay milliseconds. When done, leaves the shift key down if "ShiftState" is non-zero; otherwise, leaves the shift key up.
`void cbw_mbutton_down("button", x, y, delay);`	Identifies a mouse button press at position x, y after a delay of n milliseconds.
`void cbw_mbutton_down_rel("button", x, y, delay);`	After a delay of delay milliseconds, identifies a mouse button press by an offset of x, y relative to the last mouse position.
`void cbw_mbutton_up("button", x, y, delay);`	Identifies a mouse button release at position x, y after a delay of n millisecond.
`void cbw_mbutton_up_rel("button", x, y, delay);`	After delay milliseconds, identifies a mouse button release by an offset of x, y relative to the last mouse position.
`void cbw_move_mouse(x, y, delay);`	After a delay of n milliseconds, mouse cursor moves by a offset of x, y relative to the last mouse position.
`void cbw_move_mouse_rel(x, y, delay);`	After a delay of n milliseconds, mouse cursor moves by an offset of x, y relative to the last mouse position.
Recordable/Editable Commands Object-Mode Operation These functions are used to create actions for pure-ObjectMode playback.
`void cbw_combobox_doubleclick("TargetClass", "TargetWindow", ComboboxId);`	Double click combo box identified by ComboboxId in window identified by TargetClass and TargetWindow.
`void cbw_combobox_selection("TargetClass", "TargetWindow", ComboboxId, ItemId);`	Selects ItemId in combo box identified by ComboboxId in window identified by TargetClass and TargetWindow.
`void cbw_combobox_setedit("TargetClass", "TargetWindow", ComboboxId, "Text");`	Change text of combo box identified by ComboboxId to "Text" in window identified by TargetClass and TargetWindow.
`void cbw_hscroll("TargetClass", "TargetWindow", ScrollBarId, "SubMessage", posThumb);`	Send "SubMessage" to horizontal scrollbar specified by ScrollBarId in window identified by TargetClass and TargetWindow and if "Submessage" equals SB_THUMBTRACK or SB_THUMBPOSITION then positions the scrollbar's Thumb at posThumb.
`void cbw_hscroll_child("TargetClass", "TargetWindow", "ChildClass", ChildId, ScrollBarId, "SubMessage", posThumb);`	If ChildId is zero or greater than send "SubMessage" to horizontal child scrollbar specified by "ChildClass" and in window identified by TargetClass and TargetWindow. Else send "SubMessage" to horizontal child scrollbar specified by ScrollBarId in window identified by TargetClass and TargetWindow.
`void cbw_listbox_doubleclick("TargetClass", "TargetWindow", ListboxId);`	Double click list box identified by ListboxId in window identified by TargetClass and TargetWindow.
`void cbw_listbox_selection("TargetClass", "TargetWindow", ListboxId, ItemId);`	Selects ItemId in list box identified by ListboxId in window identified by TargetClass and TargetWindow.
`void cbw_vscroll("TargetClass", "TargetWindow", ScrollBarId, "SubMessage", posThumb);`	Send "SubMessage" to vertical scrollbar specified by ScrollBarId in window identified by TargetClass and TargetWindow and if "Submessage" equals SB_THUMBTRACK or SB_THUMBPOSITION then positions the scrollbar's Thumb at posThumb.
`void cbw_vscroll_child("TargetClass", "TargetWindow", "ChildClass", ChildId, ScrollBarId, "SubMessage", posThumb);`	If ChildId is zero or greater than send "SubMessage" to vertical child scrollbar specified by "ChildClass" and in window identified by TargetClass and TargetWindow. Else send "SubMessage" to vertical child scrollbar specified by ScrollBarId in window identified by TargetClass and TargetWindow.