Product Summary
TreeSurgeon Function Library for 
Borland ObjectVision

Over 100 add-on functions for Borland ObjectVision 2, the Windows application 
development environment.

Application Automator
 
The following functions allow your ObjectVision program to control other applications 
running under Windows. You can manage the interaction between applications and drive 
another program by passing it keystrokes. It is possible to develop a self running 
demonstration of any Windows program and include pop up message boxes which explain 
each step as it happens.

@tsAAExecApp("Command Line",   
Show Option)
Executes a Windows command line.

@tsAAHideAll
Hides all currently running applications.

@tsAAHideApp("Module Name")
Hides a currently running application.

@tsAAIsModuleLoaded("Module Name")
Checks whether an application is currently 
running.

@tsAAItemizeAll
Gets a list of currently running applications.

@tsAASendKey("Character String")
Sends a stream of keystrokes to the active 
application to automate its operation.

@tsAASwitchToApp("Module Name")
Switches to a specified running application.

@tsAAUnHideAll
Makes visible all currently hidden applications.

@tsAAUnHideApp("Module Name")
Makes visible a currently hidden application.


Application Main Window Control 
 
Developers usually like to closely tailor an application so that it works well with the whole PC 
user environment. These functions give you complete control of the main window.

@tsCloseDisable
Disables the Close option in the application 
window system menu.

@tsHide
Hides the application window.

@tsIconize
Minimizes the application window.

@tsMaximize
Maximizes the application window.

@tsRestore
Restores the application window to its previous 
non-maximized size.

@tsTitleGet
Gets the application window caption.

@tsWindowsExit
Exit from Windows.


Clipboard Utilities
 
The clipboard is used to exchange information between applications or between different parts 
of the same program. Textual data can be handled using the following utilities.

@tsClipboardAppend("Clipboard Text")
Appends text to existing text in the clipboard.

@tsClipboardClear
Clears the clipboard.

@tsClipboardRead
Reads text from the clipboard.

@tsClipboardWrite("Clipboard Text")
Writes text to the clipboard.


Directory Management
 
An application does not necessarily always operate on files in its current directory. These 
functions allow you to manipulate directories.

@tsDirectoryChange("Directory Path")
Changes the current directory.

@tsDirectoryExists("Directory Path")
Checks whether a directory exists.

@tsDirectoryItemize("Wildcard Path")
Gets a list of directories matching a wildcard 
path.

@tsDirectoryMake("Directory Path")
Makes a directory.

@tsDirectoryRemove("Directory Path")
Removes a directory.

@tsDirectoryRename("From File Path",            
"To File Path")
Renames a directory.

@tsSystemDirectoryGet
Gets the path to the Windows system directory.

@tsWindowsDirectoryGet
Gets the path to the Windows directory.


Disk Drive Management
 
The following functions are provided to allow you to work with multiple disk drives. This is 
particularly important on networked PCs where data from a variety of different sources may 
be brought together in your application. Your error checks can ensure that network drives are 
present and that sufficient disk space is available.

@tsDiskFreeGet
Gets the free space on the current drive.

@tsDiskSizeGet
Gets the size of the current drive.

@tsDriveCountGet
Gets the number of drives on the system.

@tsDriveCurrentPathGet("Drive Letter")
Gets the current path for a specified drive.

@tsDriveExists("Drive Letter")
Checks whether a drive exists.

@tsDriveGet
Gets the current drive letter.

@tsDriveItemize
Gets a list of drives on the system.

@tsDriveSet("Drive Letter")
Sets the current drive.

@tsDriveTypeGet("Drive Letter")
Gets the type of a specified drive.

@tsVolumeLabelGet("Drive Letter")
Gets a disk volume label.


File Management
 
A complex file handling application may need to manipulate file attributes and date/time 
stamps. It may also have to copy, rename and work with temporary files. A full suite of file 
handling utilities is provided here.

@tsFileAttributeGet("File Path")
Gets a file attribute.

@tsFileAttributeSet("File Path", 
"Attribute")
Sets the attribute on a file.

@tsFileCopy("From File Path",            
"To File Path")
Makes a copy of a file.

@tsFileCreateEmpty("File Path")
Creates an empty file.

@tsFileDateTimeGet("File Path")
Gets the date/time stamp on a file.

@tsFileDateTimeSet("File Path", 
Year,Month,Day,Hour,Minute, 
Second)
Sets the date/time stamp on a file.

@tsFileDelete("File Path")
Deletes a file.

@tsFileExists("File Path")
Checks whether a file exists.

@tsFileItemize("Wildcard Path", 
"Attribute")
Gets a list of files matching a wildcard path.

@tsFileRename("From File Path",            
"To File Path")
Renames a file.

@tsFileSizeGet("File Path")
Gets the size of a file.

@tsPathMake("Drive Letter","Directory", 
"File Name","File Extension")
Constructs a full path from separate 
components.

@tsPathSplit("File Path","Separator")
Splits a path into its individual components.

@tsTempDontCareCreate("Prefix")
Creates a temporary file in default directory.

@tsTempFileCreate("Drive Letter", 
"Prefix")
Creates a temporary file in a specific directory.

@tsTempFileNameGet("Drive Letter", 
"Prefix",Unique Number)
Gets a temporary file name.


Form Handling & Special Effects
 
ObjectVision provides tools for you to build visually attractive applications, limited only by 
your own imagination and artistic skills. The following utilities provide some additional special 
effects and give you more control over the display of forms on screen.

@tsFormCloseDisable("Form Name")
Disables the Close option in the system menu 
of a form.

@tsFormExplode("Form Name")
Draws exploding rectangles over a form.

@tsFormFlash("Form Name",Count, 
Interval Milliseconds)
Flashes a form border and caption.

@tsFormHide("Form Name",        
Implode YesNo)
Hides a form.

@tsFormImplode("Form Name")
Draws imploding rectangles over a form.

@tsFormIsVisible("Form Name")
Checks whether a form is currently displayed.

@tsFormPosition("Form Name",              
X Position,Y Position)
Changes the position of a form.

@tsFormRedraw("Form Name")              
Redraws a form so that all fields are shown in 
their current state.

@tsFormUnHide("Form Name",    
Explode YesNo)
Unhides a form.

@tsResetCalculated("Field Name")
Resets the 'calculated' flag on a field.

@tsResetOverride("Field Name")
Resets the 'override' flag on a field.


Function Registration 
 
Before a function can be used it must be registered by ObjectVision using @REGISTER, 
which has a rather complicated set of arguments. The following functions simplify the 
registration process for you.

@tsRegisterAll
Registers the whole TreeSurgeon library.

@tsRegisterChoice("Function Name")
Registers a specific function.

@tsRegisterPrintInterface
Registers just the printer interface functions.


List & String Handling 
 
Many applications need to be able to deal with lists of data. Sometimes a list has to be 
dynamically constructed and then presented for the user to make selections. These utilities 
allow you to work with list items assembled into a string.

@tsListChoose("Caption",X Position,      
Y Position,List Width,                
List Height,"List String", 
"Separator",Sort Position, 
Ascend/Descend)
Displays a list of items from which the user can 
make a single choice.

@tsListChooseMultiple("Caption",          
X Position,Y Position,List Width,                
List Height,"List String", 
"Separator",Sort Position, 
Ascend/Descend)
Displays a list of items from which the user can 
make multiple choices.

@tsListSort("List String", "Separator", 
Sort Position,Ascend/Descend)
Sorts a list of string items.


@tsParseCount("String","Separator")
Parses a string to count the number of 
delimited elements.

@tsParseString("String","Separator", 
Element Number)
Parses a string to extract a specific delimited 
element.

@tsStripString("String","Substring")

Removes from a string multiple occurrences of 
a substring.


Looping Control 
 
Process looping is often required in programs. The following functions provide two different 
methods of doing this.

@tsWhilefield("Condition Field",     
"Event Field")
Looping under control of a condition field, 
repeatedly generating a Change event.

@tsWhileloop("Condition Expression", 
"Action Expression")
Looping under control of a condition 
expression, repeatedly executing an action 
expression.


Miscellaneous Utilities 
 
The following utilities provide a variety of functionality that may be useful to specialised 
applications.

@tsCPUTypeGet
Gets the type of processor in the system.

@tsDateSet(Year,MonthDay)
Sets the system date.

@tsdBasePack("dBase File Path",  
"dBase Index Path")
Removes dBase records marked for deletion.

@tsEnvironmentStringGet(   
"Environment Variable Name")
Gets an environment variable.

@tsFreeMemoryGet
Gets the amount of Windows free memory.

@tsIsLeapYear(Year)
Checks whether a specified year is a leap year.

@tsNumberOfTasksGet
Gets the number of programs currently running 
under Windows.

@tsRandom
Gets a random number.

@tsRandomSeed(Seed)
Seeds the random number generator.

@tsTimeSet(Hour,Minute,Second)
Sets the system time.

@tsWindowsModeGet
Gets the Windows operating mode.

@tsWindowsTimeGet
Gets the number of milliseconds elapsed since 
Windows was started.

@tsWindowsVersionGet
Gets the Windows version number.


Printer Interface 
 
In ObjectVision a report is produced by sending a form image to the printer. This is fine for 
simple reports, but in practise developers need to be able to set up page headings and sub-
headings, and have to group data in different ways. The following functions provide an easy to 
use printer interface that has the flexibility required to produce any type of report layout. 

@tsPIBitmapDraw("File Path",               
X Position,Y Position,Width, 
Height)
Draws a Windows format bitmap.

@tsPIClose
Closes the current printing session.

@tsPIEndPage
Sends the current report page to the printer.

@tsPIFontSet(Height,"Weight",Italic?, 
Underline?,"Font Family")
Sets the current printer interface font.

@tsPILineDraw(X From,Y From,X To,     
Y To)
Draws a line between two points.

@tsPIOpen("Document Name", 
"Orientation","Print Quality")
Opens a printing session.

@tsPIPenSet(Width,"Style")
Sets the current printer interface line style.

@tsPITextDraw(X Position,Y Position, 
"Justification","Text")
Draws text with justification.


Profile (.INI) File Management
 
Profile files are useful for holding configuration information for your application. In fact they 
are ideal for handling any sort of data which falls into the two level hierarchy provided, and are 
an alternative to using database or ASCII links.

@tsIniFilePrivateRead(           
"Application Name",               
"Key Name","File Path")
Reads from a private profile file.

@tsIniFilePrivateWrite(           
"Application Name",               
"Key Name","Key Value",       
"File Path")
Writes to a private profile file.

@tsIniFileWinRead(                
"Application Name","Key Name")
Reads from the Windows profile file 
(WIN.INI).

@tsIniFileWinWrite(                
"Application Name",               
"Key Name","Key Value")
Writes to the Windows profile file (WIN.INI).


Program Control 
 
Developers often need real-time control of their applications, particularly if they are interacting 
with external processes. They also need to be able to display messages and get user response. 
These functions address a range of problems of program control.

@tsBeep
Sounds the system bell.

@tsExecute("Command To Execute")
Executes an ObjectVision expression.

@tsHardwareInputStart
Re-starts mouse and keyboard hardware input 
to Windows.

@tsHardwareInputStop
Stops all mouse and keyboard hardware input 
to Windows.

@tsHourGlassOff
Removes the hour-glass cursor.

@tsHourGlassOn
Puts up the hour-glass cursor

@tsInProgressStart("Caption","Message",
X Position, Y Position, Text Width, 
Text Height)
Displays a message while a long running 
procedure is in progress.

@tsInProgressStop
Removes the currently displayed in-progress 
message.

@tsInputStart
Re-starts mouse and keyboard input to the 
application.

@tsInputStop
Stops mouse and keyboard input to the 
application while a long running procedure is in 
progress.

@tsInputSuspend(Suspend Seconds)
Stops mouse and keyboard input for a timed 
period.

@tsMessageBox("Message","Caption", 
"Buttons","Icon")
Displays a message box and gets the user 
response.

@tsPause(Pause Seconds)
Pauses application execution for a timed 
period.

@tsPauseBox("Message",X Position,       
Y Position,Text Width,Text Height, 
Pause Seconds)
Displays a message and pauses application 
execution for a timed period.

@tsTimerStart(Interval Milliseconds, 
Timer Number)
Starts an event timer.

@tsTimerStop(Timer Number)
Stops an event timer.



Documentation
 
TreeSurgeon is delivered with a 65 page comb-bound manual which includes descriptions of 
each of the functions together with notes and examples of their use.


T. J. Techniques Limited
82 Upper George St.
Chesham
Bucks
HP5 3EH
United Kingdom

Phone/FAX: +44 (0)494 783229

1


