accels.inc

Created: Tue Jan 22 13:14:48 2008


accels.inc:
function hGetAccel( cCommand as string ) as string

Retrieve a keyboard accelerator for a specific function

Uses: framework/tools/input/accelerators.txt
NOTE: Accelerator is language dependent
Input:
  1. Name of the action to be executed (string). Valid options are:
Returns:
  1. Accelerator (string)
Description: Test/sub/function documentation

arrayfuncs.inc

Created: Tue Jan 22 13:14:48 2008


arrayfuncs.inc:
function listdebug( lsList() as string , cComment as string ) as integer

Write the content of a list plus a comment out to a file.

It is required that following global variables are defined

arrayfuncs.inc:
function initlistdebug( cComment as string ) as integer

Print leading text to a file and an index of the current debug session

It is required that following global variables are defined

arrayfuncs.inc:
function listmoveitem( source() as string, target() as string, itemid as integer ) as integer

Move one item from one list to another by index


arrayfuncs.inc:
function listconvertpath( lsList() as string ) as integer

Execute convertpath on a list containing filepaths


arrayfuncs.inc:
function listInsertSection( lsList() as string, cSection as string ) as integer

Appends a section (as ordinary list element) to a list

Test/sub/function documentation

basicide_tools.inc

Created: Tue Jan 22 13:14:48 2008


basicide_tools.inc:
function hShowMacroControls() as boolean

Tear off the ToolsCollectionBar from the MacroBar

Starting point: Basic dialog editor is open and has the focus

basicide_tools.inc:
function hGetBasicWorkFile( cMajorID as string ) as string

Retrieve a filename, depending on gApplication and Build-ID

Structure: work-directory/basic[.suffix]

basicide_tools.inc:
function hOpenBasicIDE() as boolean

Open the Basic IDE for the last module listed in the Macro Organizer

Starting point: Basic Macro Organizer has focus

basicide_tools.inc:
function hCloseBasicIDE() as boolean

Close the BASIC-IDE with best effort verification

Starting point: Basic IDE is open and has the focus
  1. File-menu
  2. Slot FileClose
  3. hCloseDocument()/hDestroyDocument()

basicide_tools.inc:
function hReOpenBasicDialog() as boolean

Open BASIC-IDE after loading a workfile with documentbound macro

Starting point: Focus on document containing at least one macro
IMPORTANT: Errorhandling is incomplete, test may end up in undefined state

basicide_tools.inc:
function hFindFirstDialog() as boolean

Find the first dialog in the BASIC-IDE

Starting point: Basic IDE must be open and has the focus

basicide_tools.inc:
function hSelectDialogPane() as boolean

Select the dialog pane in the Basic dialog editor

Starting point: Basic dialog editor is open and has the focus

basicide_tools.inc:
function hCloseCollectionBar() as boolean

Close the ToolsCollectionBar (Macro Controls Float)

Starting point: Basic Dialog editor is open, ToolsCollectionBar is open

basicide_tools.inc:
function hDeleteMacro() as boolean

Delete all text in the Basic IDE editor

Starting point: Basic IDE is open, has focus, code can be edited

basicide_tools.inc:
function hIsEditWindowEmpty() as boolean

Test if the Basic-EditWindow is empty

Starting point: Basic IDE editor is open and has the focus

basicide_tools.inc:
function hRenameTab( cTabName as string ) as integer

Rename the first tab in the Basic IDE Tabbar

Starting point: Basic IDE is open, at least one tab exists
Return values are: Description

basicide_tools.inc:
function hGetTabNameFromOrganizer() as string

Retrieve the name of a tab from the Basic Library Organizer

Starting point: Basic IDE is open and has the focus

basicide_tools.inc:
function hNewDialog() as boolean

Create a new BASIC dialog

Starting point: Basic IDE is open

basicide_tools.inc:
function hNewModule() as boolean

Create a new BASIC module

Starting point: Basic IDE is open

basicide_tools.inc:
function hHideModule() as boolean

Hide a Basic Module from the IDE

Starting point: Basic IDE is open and has the focus

basicide_tools.inc:
function hInitFormControls( cModule as string ) as boolean

Get from a new document to the Macro Controls Float in one go

Starting point: Plain document
This function performs following steps:
  1. Open the Basic Organizer
  2. Create a new module for the current document
  3. Open a new basic dialog
  4. Open the Macro controls float
Description: NOTE: The function will try to cleanup after itself in case of failure

basicide_tools.inc:
function hInitBasicIde( cModule as string ) as boolean

Get from a new document to the Basic IDE in one go

Starting point: New, plain document NOTE: The function will try to to clean up after itself in case of any error

basicide_tools.inc:
function hInsertMacro( _id as integer ) as boolean

Insert a macro into the Basic-IDE edit window by Index

Starting point: Basic IDE is open, has the focus

basicide_tools.inc:
function hTestMacro( _id as integer ) as integer

Verify that the correct macro is visible in the IDE edit Window

Starting point: Basic IDE is open and has focus

basicide_tools.inc:
function hCreateBasicWorkFiles() as string

Create a macro, attach it to a file, save the file

Starting point: The first doc or any other plain document

basicide_tools.inc:
function hIDESelectTabByIndex( iIndex as integer ) as string

Select a tab within the BASIC-IDE by index

The BASIC-IDE has to be open and has the focus. This function selects the tab by sending CTRL+PAGEUP or CTRL+PAGEDOWN to the IDE using the .typeKeys method. It is assumed that - when opening the IDE - the first tab is active. When the specified index has been reached we retrieve the name of the current tab by opening the context menu on the tab and selecting "Rename". The name (which should be highlighted by default) is then copied to the clipboard and returned to the calling function.

Parameter(s):
  1. Index of the requested Tab (Integer)
Returns:
  1. Name of the selected tab (string)
Description: Test/sub/function documentation

basicorganizer_tools.inc

Created: Tue Jan 22 13:14:48 2008


basicorganizer_tools.inc:
function hSelectTheLastModule( bEditEnabled as Boolean ) as boolean

Select the last module in the Macro Treelist

Starting point: Plain Writer document
This function has many problems and should be replaced, see inline documentation

basicorganizer_tools.inc:
function hCreateModuleForDoc( optional cName as string ) as boolean

Create a new Basic module for the current document

Starting point: Basic Macro Organizer is visible and has focus

basicorganizer_tools.inc:
function hOpenBasicObjectOrganizer( iTabPage as integer ) as boolean

Open the Basic Library/Module/Dialog Organizer

Starting point: Basic IDE is open and has focus

basicorganizer_tools.inc:
function hOpenBasicOrganizerFromDoc() as boolean

Open the Basic Macro Organizer from a plain document

Starting point: Plain document

basicorganizer_tools.inc:
function hSelectBasicObjectOrganizerTab( iTabPage as integer ) as boolean

Switch between tab pages in the Basic Object Organizer

Starting point: Masic Object Organizer is visible and has focus
  1. 1 = Modules
  2. 2 = Dialogs
  3. 3 = Libraries
Description:

basicorganizer_tools.inc:
function hDeleteLibrary( iLocation as integer, cLibName as string ) as boolean

Delete a library by name via Macro Object Organizer

Starting point: Plain document

basicorganizer_tools.inc:
function hIsMacroEditButtonEnabled() as boolean

Test whether the "Edit..." button is enabled or not

Starting point: Basic Macro Organizer

basicorganizer_tools.inc:
function hIsMacroNewButtonEnabled() as boolean

Find out whether the "New..." button is enabled or not

Starting point: Basic Macro Organizer

basicorganizer_tools.inc:
function hNameBasicModule( cName as string ) as boolean

Name a Basic Module

Starting point: Clicked "New..." button in Basic Macro organizer.
On success the kontext will be on the Basic IDE. In case of failure we remain on the naming dialog so that the function can be triggered again.

Input:
  1. Name of the module (string)
Returns:
  1. Errorcondition (Boolean)
Description: Test/sub/function documentation

control_objects.inc

Created: Tue Jan 22 13:14:48 2008


control_objects.inc:
function checkRadioButtons( _file as string , sKey as string , control1 as object , control2 as object , optional control3 as object , optional control4 as object ) as integer

EXPERIMENTAL: Get/Set function for some control types

This is a function that allows to change the state/content of a control via a configuration file. This function is experimental and should not be used.
This function checks if the correct radiobutton of a group is selected. at least two radiobuttons must be provided, the third and fouth are optional. The value for sKey in the reference file must be of type integer


control_objects.inc:
function checkRadioButton( _file as string , sKey as string , control as object ) as boolean

EXPERIMENTAL: Get/Set function for some control types

This is a function that allows to change the state/content of a control via a configuration file. This function is experimental and should not be used.

control_objects.inc:
function checkCheckBox( _file as string , sKey as string , control as object , optional cBugID as string ) as boolean

EXPERIMENTAL: Get/Set function for some control types

This is a function that allows to change the state/content of a control via a configuration file. This function is experimental and should not be used.

control_objects.inc:
function setCheckBox( _file as string , sKey as string , control as object , optional bverbose as boolean ) as boolean

EXPERIMENTAL: Get/Set function for some control types

This is a function that allows to change the state/content of a control via a configuration file. This function is experimental and should not be used.

control_objects.inc:
function checkComboBox( _file as string , sKey as string , control as object ) as boolean

EXPERIMENTAL: Get/Set function for some control types

This is a function that allows to change the state/content of a control via a configuration file. This function is experimental and should not be used.

control_objects.inc:
function setComboBox( _file as string , sKey as string , control as object , optional bverbose as boolean ) as integer

EXPERIMENTAL: Get/Set function for some control types

This is a function that allows to change the state/content of a control via a configuration file. This function is experimental and should not be used.

control_objects.inc:
function checkEntryField( _file as string , sKey as string , control as object , optional cBugID as string ) as boolean

EXPERIMENTAL: Get/Set function for some control types

This is a function that allows to change the state/content of a control via a configuration file. This function is experimental and should not be used.

control_objects.inc:
function setEntryField( _file as string , sKey as string , control as object , optional bverbose as boolean ) as string

EXPERIMENTAL: Get/Set function for some control types

This is a function that allows to change the state/content of a control via a configuration file. This function is experimental and should not be used.

control_objects.inc:
function checkListBox( _file as string , sKey as string , control as object ) as boolean

EXPERIMENTAL: Get/Set function for some control types

This is a function that allows to change the state/content of a control via a configuration file. This function is experimental and should not be used.

control_objects.inc:
function setListBox( _file as string , sKey as string , control as object , optional bverbose as boolean ) as integer

EXPERIMENTAL: Get/Set function for some control types

This is a function that allows to change the state/content of a control via a configuration file. This function is experimental and should not be used.

control_objects.inc:
function checkListItem( _file as string , _iIndex as integer , sKey as string , control as object ) as boolean

EXPERIMENTAL: Get/Set function for some control types

This is a function that allows to change the state/content of a control via a configuration file. This function is experimental and should not be used.

control_objects.inc:
function hSetControlValue( oObject as object, cValue as string ) as integer

Enter some text into a EntryField/TextField

This extends .setText() to provide a returnvalue
The function runs silent as long as no errors occur
Input:
  1. Control Object (Object)
    • The object must exist
    • The object must be enabled
    • The object must be visible
  2. String (string)
    • Any string, including empty strings (=delete)
Returns:
  1. Status of the control (integer)
    • 0 = EntryField was updated correctly
    • 1 = Object does not exist
    • 2 = Object it not visible
    • 3 = Object is disabled
Description:
  • Verify that the control exists
  • Verify that the object is visible
  • Verify that the control is enabled
Test/sub/function documentation

customize_tools.inc

Created: Tue Jan 22 13:14:48 2008


customize_tools.inc:
function hToolsCustomizeOpen() as boolean

Open Tools/Customize

Starting point: Any plain document
Input:
  1. Nothing
Returns:
  1. Errorstatus (boolean)
    • TRUE if the Keyboard-Tab is open
    • FALSE on any other case
Description:
  • Open Tools/Customize using the ToolsCustomize slot
  • Switch to the Events Tab
  • Verify that the requested tabpage is open
  • Return TRUE on success

customize_tools.inc:
function hToolsCustomizeSelectTab( cTab as string ) as boolean

Switch Tabpages on ToolsCustomize Dialog

Starting point: The Tools/Customize dialog
Input:
  1. Name of the Tab (string)
    • "Keyboard"
    • "Menu"
    • "Toolbars"
    • "Events"
Returns:
  1. Errorstatus (boolean)
    • TRUE if the requested tab is open
    • FALSE on any other condition
Description:
  • Switch to one of the four available tabpages
    1. Keyboard
    2. Menu
    3. Toolbars
    4. Events
  • Return TRUE on success

customize_tools.inc:
function hToolsCustomizeClose( iMode as integer ) as boolean

Close the ToolsCustomize-Dialog

Starting point: Tools/Customize dialog
Input:
  1. Closing mode (integer)
    • 1: Use OK-button
    • 2: Use Cancel-button
Returns:
  1. Errorstatus (boolean)
    • TRUE if executing close action succeeded
    • FALSE on any other condition
Description:
  • Switch to the Events page by default
  • Close dialog by OK or CANCEL
    1. OK
    2. Cancel
  • Verify that the dialog has indeed been closed

customize_tools.inc:
function hToolsCustomizeAddNewMenu( cName as string, bMode as boolean ) as boolean

Add a new menu via Tools/Customize/Menu

Starting point: Tools/Customize with Menu-Tab open
Input:
  1. Name of the new menu (string)
  2. Mode (boolean). Options:
    • TRUE = The entry will be created (OK)
    • FALSE = The entry will not be created (Cancel)
Returns:
  1. Errorstatus (boolean)
    • TRUE on success
    • FALSE on failure
Description:
  • Click the "New..." button
  • Verify that the menu organizer exists
  • Name the new menu if we intend to create the new entry

customize_tools.inc:
function hDeselectSeparator() as integer

Make sure that we do not work on a separator item (Toolbars)

Starting point: Tools/Customize: Toolbars must be open
Input:
  1. Nothing
Returns:
  1. Position of the selected item (integer)
    • Always > 1
    • Always < Max number of items
Description:
  • Check whether the selected item contains a number of minus-chars (---)
  • If we are at the beginning of the list: Move up
  • If we are somewhere else in the list, move down

customize_tools.inc:
function hClickCommandButton( iItemToClick as integer ) as boolean

Click a given entry on the command button


Parameter(s):
  1. Position of the item to click (Integer)
    • Only active items are selectable
    • Position must be > than 0 and ≤ number of active items in menu
    • Set context (kontext) before calling this function
Returns:
  1. Success or failure (Boolean)
    • TRUE on success
    • FALSE on failure or unknown status
Description:
  • Click the command button
  • Verify that the menu is open
  • Verify that the selected menuitem is valid
  • Now click on the requested item
  • Look for the Menu renaming dialog
  • Look for the Toolbar renaming dialog
Test/sub/function documentation

docfuncs.inc

Created: Tue Jan 22 13:14:48 2008


docfuncs.inc:
function hUseImpressAutopilot( bEnable as boolean ) as boolean

Enable/disable the Impress Autopilot in Tools/Options

Starting point: Any plain document
  • Create a new IMPRESS document
  • Open Tools/Options, go to Presentataion/General page
  • Check or uncheck to start with autopilot
  • Return Status of Checkbox (checked=TRUE)
  • Close Tools/Options
  • Close IMPRESS document
  • Returncode is undefined

docfuncs.inc:
function hCloseNavigator() as boolean

Function to close the navigator

Starting point: Any document
  • close the navigator if found
  • verify that the navigator is indeed closed, return true on success

docfuncs.inc:
function hNumericDocType( doctype as integer ) as string

Convert a numeric expression to a gApplication

BEWARE: This is a core function used by many testcases!
Using file: framework/tools/input/applications.txt as reference
  • Retrieve matching list from file
  • Verify that the functionparameter (documenttype) is valid
  • Set gApplication to the requested document type
  • Set a plain text name as returnvalue for the function

docfuncs.inc:
function hChangeDoc() as string

Function to modify all documenttypes to set the "changed" flag

Starting point: Any plain document
Input:
  1. Nothing
Returns:
  1. String, ready to use in printlog
    • "Changed <Documenttype>"
Description:
  • WRITER: Type some text
  • CALC: Write some text into the current location (usually A1)
  • DRAW: Draw a rectangle
  • IMPRESS: Draw a rectangle
  • MATH: Create a simple formaula

docfuncs.inc:
function hIdentifyWriterDoc( cString as string, bWarn as boolean ) as boolean

Function to validate that the expected WRITER doc has the focus

Starting point: Any WRITER document containing some text
  • Test the function parameter
  • Verify function prerequisites
  • Go to the very beginning of the current writer document
  • Select the entire line
  • copy the string to the clipboard and store it into a variable
  • compare the string to the reference (given as parameter)
  • Write the result to the printlog if desired
  • Return TRUE only if the current document is the expected one

docfuncs.inc:
function hCreateDocument() as boolean

Create anew document, extends hNewDocument()

Starting point: Any document
Note: When calling this function with gApplication "BACKGROUND" the function will actually close one document to get to the backing window
Input:
  1. Nothing, valid gApplication must be set
Returns:
  1. Errorstatus (boolean)
    • TRUE if a new document was created successfully
    • FALSE if anything went wrong
Description:
  • Retrieve the number of open documents
  • Special treatment if gApplication = BACKGROUND (virtual gApplication)
  • Open a new document using hNewDocument()
  • Retrieve the number of open documents
  • Verify that there is exactly one more document than before

docfuncs.inc:
function hDocumentTypeKeys( cString as string ) as boolean

Type a string to a document

The documenttype is determined by gApplication.
See hNumericDocType for details and number/gApplication matching

Input:
  1. Keystrokes to be sent to the document (string), e.g.
    • "<SHIFT HOME>"
    • "<MOD1 A>"
    • "<MOD2 Q>"
    • "Hello"
Returns:
  1. Errorstatus (boolean)
    • TRUE if all went well
    • FALSE on any error
Description:
  • Set focus to the current documenttype determined by gApplication
  • Type the string passed as function parameter
  • Print some message to the log on success

docfuncs.inc:
function hDestroyDocument() as boolean

Enhanced version of hCloseDoc()

Close a document and print some additional information to the log to ease debugging tests which handle a lot of documents

Parameter(s):
  1. No input parameters
Returns:
  1. Return value description
    • TRUE: The document was closed successfully (-1 open document)
    • TRUE: We are on backing window, no document closed
    • FALSE: The number of documents is unchanged, closing failed
    • FALSE: If any error occurred during close (open dialogs etc.)
Description:
  • Get the current number of documents
  • Handle special case of 0 open documents
    • If gApplication has been set to BACKGROUND explicitly we do a restart
    • Otherwise just do not close the backing window - do nothing
  • Handle more than one open document - handle FileOpen/FileSave dialogs
    • FileOpen
    • FileSave
    • Check for any messagebox (some might still be floating around)
      • Try to close the dialog clicking on "OK"
      • Try to close the dialog clicking on "YES"
    • Close the current document using hCloseDocument()
    • Verify that the document has indeed been closed, exit function if yes
Test/sub/function documentation

extras_tools.inc

Created: Tue Jan 22 13:14:48 2008


extras_tools.inc:
function hCompareStylesAndFormats( sFormatListFromGUI() as string, iIndex as integer, iVariant as integer ) as boolean

Compare styles and formats (drawing objects) to a reference

  • Create filenames for:
    • Line styles ( standard.sod, *.sod )
    • Line ends ( arrows ) ( standard.sow, *.soe )
    • Colors ( standard.soc, *.soc )
    • Gadients ( Standard.sog, *.sog )
    • Hatchings = standard.soh
    • Bitmap = standard.soh
  • Create filenames (inluding paths) for input and output
  • Compare the lists or create a new one if it does not exist
  • Return TRUE if comparision succeeded with no errors

extras_tools.inc:
function hApplyBlackList( sFileName as string ) as boolean

Function to identify blacklisted files that will not be tested

  • Make sure we have a valid functionparameter
  • newslttr.ott is broken and should not be loaded.
  • idxexample.sxw is not a regular document and should not be loaded.
  • files with the suffix .table are to be skipped as well.
  • Test the suffix and skip graphics files (.gif, .jpg, .bmp)

extras_tools.inc:
function hSelectLineStylesTab( cTab as string ) as boolean

Switch between tabpages in the format linestyles dialog

Starting point: FormatLine must be open
Input:
  1. Name of the tabpage (string). Valid options are:
    • "Line"
    • "LineStyles"
    • "LineEnds"
Returns:
  1. Errorstatus (boolean)
    • TRUE if tabpage could be accessed
    • FALSE on any other condition
Description:
  • Set Tabpage
  • Set Context
  • Warn about errors

extras_tools.inc:
function hSelectAreaStylesTab( cTab as string ) as boolean

INCOMPLETE! Switch between tabpages in the format area dialog

Starting point: FormatLine must be open
Input:
  1. Name of the tabpage (string). Valid options are:
    • "Colors"
    • "Gradients"
    • "Hatchings"
    • "Bitmaps"
Returns:
  1. Errorstatus (boolean)
    • TRUE if tabpage could be accessed
    • FALSE on any other condition
Description:
  • Set Tabpage
  • Set Context
  • Warn about errors

extras_tools.inc:
function hGetDrawObjectStyleFileName( cCategory as string ) as string

Retrieve the filename of a Draw-Object style (localized)

Uses file: framework/tools/input/i18ndata.txt
Input:
  1. The category to retrieve (string). Valid options are
    • "ArrowHead"
    • "LineStyles"
    • "Colors"
    • "ClassicGradients"
    • "ModernGradients"
    • "Hatchings"
    • "Bitmaps"
Returns:
  1. fully qualified path to a styles file (string)
    • e.g. /somewhere/nowhere/hatchings_en-US.soh
Description:
  • Construct the path to the file where the definitions are stored
  • Initialize an array that can hold the entire file content
  • Create a valid language code (string)
  • Retrieve the relevant section from the definitions file
  • Create path to office installation
  • Append path to styles directory
  • Append file prefix
  • Append language dependent string - it differs in details from gISOLang!
  • Append suffix
  • Do ConvertPath()

extras_tools.inc:
function hGetDrawObjectSpecialFileName( cCategory as string, cSpecial as string ) as string

Retrieve the filename of a Draw-Object style (non localized)

Uses file: framework/tools/input/i18ndata.txt
Input:
  1. The category to retrieve (string). Valid options are
    • "ArrowHead"
    • "LineStyles"
    • "Colors"
    • "ClassicGradients"
    • "ModernGradients"
    • "Hatchings"
    • "Bitmaps"
  2. The category to retrieve (string). Valid options are
    • "Default" (should always exist)
    • Any other identifier found in the section of the definitions file
Returns:
  1. fully qualified path to a styles file (string)
    • e.g. /somewhere/nowhere/standard.sod
Description:
  • Construct the path to the file where the definitions are stored
  • Initialize an array that can hold the entire file content
  • Retrieve the relevant section from the definitions file
  • Create path to office installation
  • Append path to styles directory
  • Append file prefix
  • Append suffix
  • Do ConvertPath()
Test/sub/function documentation

fFileSaveAs.inc

Created: Tue Jan 22 13:14:48 2008


fFileSaveAs.inc:
testcase fFileSaveAs

fFileSaveAs

Synopsis
Please add freeform text here
Specification document
Please add link to specification document
Files used
Please add path to additional files used by this test
Test case specification
Test/sub/function documentation

filedlg_tools.inc

Created: Tue Jan 22 13:14:48 2008


filedlg_tools.inc:
function hFileOpenMultiSelect( iArray() as integer ) as integer

Multiselect files with the fileopen dialog

This function uses keyboard navigation to select a number of files (multiselection).
Starting point: FileOpen dialog has context, workdirectory is open

Input value(s):
  1. Array (integer)
    • if ( array( n ) = 1 ) select the file at pos n, starting at n = 1
    • Any other value: Do not select, preferably preset with 0!
    • The size of the array must less or equal the number of files in the filepicker
      Array( 0 ) is ignored
Return Value:
  1. Number of selected files (integer)
    • = 0: any error
    • > 0: Number of selected files (Sum of Array( n ) = 1)
Description:
  • Get the size of the array
  • Get the number of items from the filepicker
  • Verify that the array size is equal or less the number of files
    Exit with rc = 0 on error
  • Select the first object in the filelist
  • Run through the filelist and select all items that are marked in the array
    • Select a file with CTRL+SPACE
    • Move one down with CTRL key pressed
Test/sub/function documentation

fileoperations.inc

Created: Tue Jan 22 13:14:48 2008


fileoperations.inc:
function hSaveLoadDelSuccess( cFile as string ) as integer

Successfully save, close, load, close and delete a file

Uses: framework\tools\stringtools.inc

Input:
  1. Filename incl. extension (string)
Returns:
  1. Errorcode (integer)
    • 0 = all ok
    • 1 = Saving failed
    • 2 = Closing the file failed
    • 3 = Reloading failed
    • 4 = Closing the file failed
    • 5 = Deleting failed
    • -1 = Post operation error
Description:
  • Close the navigator if it exists
  • Save the current file, overwriting existing
  • Close the file
  • Reload the file
  • Close the document
  • Delete the file via FileOpen
  • Close possible Messagebox (#i33946#)
  • Close document

fileoperations.inc:
function hLoadFileExpectSuccess( fpath as string ) as boolean

Load a file where failure is expected

Uses: framework\tools\stringtools.inc

This function is quite similar to hLoadFile but does much less errorhandling so the information of the type of failure is a little more exact

Input:
  1. Filename incl. extension (string)
Returns:
  1. Errorcondition (boolean)
    • TRUE = File was loaded without problems
    • FALSE = Any error
Description:
  • Click FileOpen (or use the menu)
  • Enter the filename (with extension)
  • Click "Open"
  • Watch out for an unexpected messagebox
    recover in case of error so the test has a chance to continue
  • Return the errorcode

fileoperations.inc:
function hLoadFileExpectFailure( fpath as string ) as boolean

Load a file where failure is expected

Uses: framework\tools\stringtools.inc

Input:
  1. Filename incl. extension (string)
Returns:
  1. Errorcondition (boolean)
    • TRUE = There was an error loading the file (as expected)
    • FALSE = The file was loaded without problems/any other error
Description:
  • Click FileOpen
  • Enter filepath
  • Click "Open"
  • Close the expected warning dialog, return to FileOpen
  • Verify that we are on FileOpen dialog, set errorcondition true
  • If the document is loaded, set errorcondition to false
  • Click away possible messagebox to recover
  • Return errorcondition

fileoperations.inc:
function hSaveFileExpectSuccess( fpath as string , bReplace as boolean ) as boolean

Save a file with optional replace where success is expected

Uses: framework\tools\stringtools.inc

Input:
  1. Filename incl. extension (string)
  2. Replace file (boolean)
    • TRUE = Replace the file
    • FALSE = Do not replace the file
Returns:
  1. Errorcondition (boolean)
    • TRUE = There was an error loading the file (as expected)
    • FALSE = The file was loaded without problems/any other error
Description:
  • Make sure we start from the backing window
  • Open a new document
  • Click "Save As..."
  • Enter a filename (with extension)
  • Click "Save"
  • If the file exists, say "yes" to replace it
  • Handle any unexpected errormessage with "OK"
  • The FileSave dialog should be closed at this point
  • Verify that exactly one document is open

fileoperations.inc:
function hSaveFileExpectFailure( fpath as string , errortype as integer ) as boolean

Save a file where failure is expected

Uses: framework\tools\stringtools.inc

Input:
  1. Filename incl. extension (string)
  2. Errortype (Integer). Valid options are:
    • 0 = Invalid characters in string
    • 1 = Filename is interpreted as device
Returns:
  1. Errorcondition (boolean)
    • TRUE = There was an error saving the file (as expected)
    • FALSE = The file was saved without problems/any other error
Description:
  • Open an new document
  • Click "Save As;"
  • Enter the filename
  • Click "Save"
    • Handle invalid characters (Errormessages)
  • Close the document
  • Return errorcondition

fileoperations.inc:
function hCreateDirectoryExpectSuccess( dirname as string ) as boolean

Create a directory where success is expected

Uses: framework\tools\stringtools.inc

Input:
  1. Name of the directory (string)
    • Relative or absolute, absolute is recommended
Returns:
  1. Errorcondition (boolean)
    • TRUE = The directory wass created
    • FALSE = On any error (Unable to create or file already exists)
Description:
  • Click "File Open"
  • Click on "New folder"
  • Enter a name for the folder into the dialog
  • Click "OK"
  • Handle possible messagebox (unexpected)
  • Return errorcondition

fileoperations.inc:
function hDeleteFileViaFileOpen( cFile as String ) as boolean

Delete a file using the File Open dialog

Uses: framework\tools\stringtools.inc

Input:
  1. Filename incl. extension (string)
Returns:
  1. Errorcondition (boolean)
    • TRUE = File was deleted
    • FALSE = Any other condition
Description:
  • Click "File Open"
  • Look for the requested file, get the position from the filelist
  • If the file exists, delete it + verify, if not: Warn and exit
  • Cancel the FileOpen dialog
  • Return errorcondition

fileoperations.inc:
function hGetFileCountViaFileOpen() as integer

Get the number of items listed in the FilePicker (File Open)

Note: This function works on the current workdirectory

Input:
  1. Nothing
Returns:
  1. Number of items listed in filepicker
Description:
  • Click "File open"
  • Retrieve the number of items in the filepicker window
  • Close "File Open"

fileoperations.inc:
function hNameGen_append( iDecChar as long ) as string

Create a filename with specified character at the end

Input:
  1. Character as number (integer)
    • Only positive numbers are allowed
    • Respect integer boundaries
Returns:
  1. A filename containing a special character at the end (before suffix)
Description:
  • Create a string "test", append ascii char
  • Return the new filename

fileoperations.inc:
function hNameGen_lead( iDecChar as long ) as string

Create a filename with specified character at the beginning

Input:
  1. Character as number (integer)
    • Only positive numbers are allowed
    • Respect integer boundaries
Returns:
  1. A filename containing a special character at the beginning
Description:
  • Create a string beginning with ascii char and append "test"
  • Return the new filename

fileoperations.inc:
function hGetRelPath( cStartDir, cFileName as String ) as string

Remove the absolute component from a path specification

Usually you do not need this function, avoid using it

Input:
  1. Absolute part of a filespec (startdirectory) (string)
    • e.g. "/home/oscar/mydir"
  2. Fully qualified path to the file/directory (string)
    • e.g. "/home/oscar/mydir/somedir/myfile.txt"
Returns:
  1. Remaining part of the fully qualified path minus startdirectory (string)
    • e.g. "/somedir/myfile.txt"
Description:
  • Find the end of startdir within the FQ filename

fileoperations.inc:
function hFindFileObjectViaFileOpen( cName as string ) as integer

Get the position of a filesystem object in filelist of fileopen dialog

Note that the filepicker must be open in order to use this function.
The object with the given name is selected when leaving the function.

Input:
  1. Filename incl. extension (string) but without any pathseparator
Returns:
  1. Position of the object in the filepicker list
    • 0: Object not found
    • > 0: Position
Description:
  • If a fully qualified path has been provided we have to split it up
  • And walk to the directory
  • get the number of items in the filepicker
  • Jump to the first item in the filelist and select it with SPACE
  • Navigate through the list until we find the requested object
  • Print some info to the log
  • return the position or 0 on failure
Test/sub/function documentation

filetools.inc

Created: Tue Jan 22 13:14:48 2008


filetools.inc:
function hDeleteFile( cFileOrig as string ) as boolean

Delete a file

In many cases it is a good idea to use this function outside the testcase.
You should always evaluate the returncode

Input:
  1. Filename (string)
    • The function converts the path to system specific syntax (convertpath) but does not modify the input parameter
Returns:
  1. Errorstatus (boolean)
    • TRUE: File was deleted/does not exist
    • FALSE: File could not be deleted/any other error
Description:
  • We may never delete a file outside gOfficePath/user/work
  • Check that the file exists
  • Use kill to delete
  • Verify that the file does not exist anymore
  • in very rare cases 'kill' fails and can be handled this way
  • write some text to the log if the file does not exist

filetools.inc:
function hLoadFile( cFile as string ) as boolean

Load a file via FileOpen

Replaces: hDateiOeffnen
Input:
  1. Filename (string)
Returns:
  1. Errorstatus (boolean)
    • TRUE: File was loaded
    • FALSE: File was not loaded or loading takes too long (timeout)
Description:
  • look if the requested file exists
  • if the workfile does not exist, return false and end the function
  • Open the FileOpen dialog
  • Enter the filename
  • Click "Open"
  • Verify that the document is opened

filetools.inc:
function hLoadRecentDocument( bSecWarn as boolean, iSecLevel as integer, iTries as integer ) as boolean

Load the topmost document from the picklist

Starting point: Plain document (recommended)
NOTE: Non-optional parameter iSecLevel is yet unused
Input:
  1. Allow security warning (boolean). valid options are:
    • TRUE: Yes
    • FALSE: No
  2. Security Level (integer). Valid options are:
    • 0: Low
    • 1: Medium
    • 2: High
    • 3: Very high
  3. Retries (integer)
    • Number of expected dialogs/warnings/messageboxes during load
Returns:
  1. Errorstatus (boolean)
    • TRUE: File was successfully loaded
    • FALSE: File not loaded/Loading too slow/getDocumentCount returned 0
Description:
  • Init Menu usage
  • Select "File"
  • Select "Recent Documents"
  • Select "1"
  • Wait for the document to load
  • Handle Actives on load (like "Update external links" etc.)
  • Handle special dialogs for some documents

filetools.inc:
function hSaveFile( sFile as string, sBuildId as string, bOverwrite as boolean, bAutoSuffix as boolean ) as boolean

Save a file with options

Replaces: hSpeichernUnterMitFilterKill
NOTE: Special behavior to suit framework needs, use original function if possible
Please refer to the inline documentation for more details
Input:
  1. Filename (string)
  2. Build-ID (string). Valid options are:
    • "Current": Uses default extension/filter
    • "680": Use 680 default format
    • "645": Use 645 default format (alien xml-filter)
    • "641": Use 641 default format (alien xml-filter)
    • "569": Use 569 default format (alien bin-filter)
  3. Delete file in advance (boolean). Valid options are:
    • TRUE: Yes
    • FALSE: No
  4. Use automatic filename-extension (boolean)
    • TRUE: Append suffix
    • FALSE: Omit suffix
Returns:
  1. Errorstatus
    • TRUE: Saving succeeded/document is still open
    • FALSE: On any other condition
Description:
  • Count the open documents, Saving should not change the number
  • Check if the file exists, if we may not overwrite we quit, otherwise try to delete it (may fail)
  • Open FileSaveAs
  • Verify that the FileSaveAs dialog is indeed open
  • Use a filter for saving - if provided
  • Set the filename
  • Save the file by clicking on "save"
  • Handle Alien-Warning, if it comes up
  • In rare cases the overwrite warning pops up even if we tried to delete it earlier
  • Check if saving was successful, giving it extra time to complete

filetools.inc:
function hHandleActivesOnLoad( iTries as integer , iAdd as integer ) as boolean

Handle any dialogs that might pop up when loading a file

Beware: This function gives only limited control over the dialogs closed, it just closes anything it can.
Please refer to the inline documentation for further details
Input:
  1. Number of dialogs to be closed (integer)
    • Max 3 allowed
  2. Additional dialogs (integer).
    • Max 2 allowed
Returns:
  1. Errorcondition (boolean)
    • TRUE: The expected number of dialogs were closed
    • FASLE: On any other condition
Description:
  • OK to create a new document based on a template
  • YES to update links
  • YES to execute macros

filetools.inc:
function hHandleInitialDialogs() as integer

Handle dialogs while opening samples/templates etc.

The returnvalue is of limited use
Input:
  1. Nothing
Returns:
  1. Id of the dialog (integer)
    • 0: No dialog was found
    • 1: UseOfThisTemplate
    • 2: StarOfficeCalendar1
    • 3: NewsletterLayout
    • 4: PortfolioCurrency
Description:
  • Test for UseOfThisTemplate-dialog
  • Test for StarOfficeCalendar1-dialog
  • Test for NewsletterLayout-dialog
  • Test for PortfolioCurrency-dialog

filetools.inc:
function hWaitWhileLoading() as boolean

Wait for a document to load

Extends: IsItLoaded with 10 retries
Input:
  1. Nothing
Returns:
  1. Errorstatus (boolean)
    • TRUE: Document was loaded
    • FALSE: Document not loaded
Description:
  • Cycle for at most ten times to check the IsDocLoading-slot
  • while the file is loaded the slot will not be dispatched -> catch
  • "exit for" within try...catch does not always work
  • Warn if the document did not respond in at most 10 seconds

filetools.inc:
function hFileHasThreeCharSuffix( sFile as string ) as boolean

Test whether a standard three-char suffix exists in a filename

Input:
  1. Filename with optional suffix (string)
Returns:
  1. Errorstatus (boolean)
    • TRUE: A suffix was found
    • FALSE: A suffix could not be identified
Description:
  • Check that the filename is long enough to have a standard suffix
  • If the fourth character from right is a dot, return true

filetools.inc:
function hGetSuffixFromFilename( sFile as string ) as string

Retrieve the suffix from a filename

Suffix must be of type ".xxx"
Input:
  1. Filename (string)
Returns:
  1. Suffix (string)
    • "" if file has no suffix
    • The suffix ".XXX"
Description:
  • Determine the length of the filename
  • Verify that the length is at least 5 chars (a letter, dot, suffix)
  • Verify that the 4th character from right is a dot
  • Isolate the dot plus three-letter suffix
  • Return the suffix

filetools.inc:
function hCancelFilterDialog() as boolean

Handle filter selection dialog

This dialog might come up if the documenttype could not be determined. This is most likely a bug since we should handle any type of document correctly
Input:
  1. Nothing
Returns:
  1. Errorstatus
    • TRUE: If the dialog was found and closed
    • FALSE: If no filterdialog exists
  2. Variable
    • Variable description
    • Variable description
Description:
  • Check whether the filter dialog is open or not, close it

filetools.inc:
function hGetFileNameFromProperties() as string

Retrieve the filename from document-properties

This is one of the few places where the suffix is actually displayed
Input:
  1. Nothing
Returns:
  1. Filename without path(string)
Description:
  • Open File->Properties
  • Select Document tab
  • Get name of document from entryfield
  • Check that the name has a suffix
  • Return the filename including suffix

filetools.inc:
function hGetWorkPath() as string

Retrieve the users work directory

Uses: Call to UNO service
Errorhandling: Fixes "$(user)"-type path (uses fallback)
Errorhandling: Handles broken UNO connection (uses fallback)
Input:
  1. Nothing
Returns:
  1. Path to local workdir (string)
    • Includes trailing slash/backslash
Description:
  • Create an UNO service and ask it for the location of "Work"
  • Handle broken UNO connection
  • If the path differs from the default do a warnlog
  • Apply fallback in case of broken connection or invalid path
  • Add trailing pathseparator, do convertpath
  • Print info to the log and return the path

filetools.inc:
function hGetInputPath( byval sBasePath as string, byval sFile as string ) as string

Create an input path for reference files

Input:
  1. BasePath (string) without trailing slash/backslash
    • Format: gTesttoolPath & "[project]\input\[dir]"
  2. Filename (string)
    • The name of the file below BasePath to be used
    • The filename may be an empty string
Returns:
  1. Full path to file: BasePath + Build-Id + ProductName + sFile
    • Build-ID (e.g. "680", from environment)
    • ProducName (e.g "OpenOffice.org", from environment)
Description:
  • None of the two parameters may be empty
  • Remove trailing slash or backslash
  • At least Basepath should exist
  • We must be certain, that basepath is a directory
  • Now we concatenate all the information we have to a fully qualified path
  • ...and return it (without further verification)

filetools.inc:
function hGetFileSizeAsLong( cFileName as string ) as long

Get the size (long) of a file

Input:
  1. Filename (string)
Returns:
  1. Size of file (long)
Description:
  • Verify that the given file exists
  • Return the size for a file or -1 for a directory
  • Return a size of 0 if the file was not found

filetools.inc:
function hCreateDirectory( cDir as string ) as integer

Create a directory (if it does not exist)

Input:
  1. Name of the directory without trailing slash/backslash
Returns:
  1. Errorstatus (integer)
    • 0: Directory exists/has been created
    • 1: Failed to create directory
    • 2: Object exists but is no directory
Description:
  • See if anything exists a the designated location
  • Create the directory
  • Verify that the directory exists

filetools.inc:
function hGetWorkFile( cFileName as string ) as string

Returns a fully qualified filename to a workfile

Input:
  1. Filename without path (string)
Returns:
  1. Filename including path to user work directory (string)
Description:
  • Concatenate workpath and filename, convertpath

filetools.inc:
function hGetLocalizedFileName( cFileName as string ) as string

Function to prepend numeric language code to a filename

Input:
  1. Filename (string)
Returns:
  1. Filename with leading numeric language code (string)
Description:
  • Build a string of type Number + _ + Filename, convertpath

filetools.inc:
function hTestFile( cFile as string ) as boolean

Test whether a file exists or not


Input:
  1. Filename (string)
Returns:
  1. Errorstatus (boolean)
    • TRUE: File exists
    • FALSE: File does not exist
Description:
  • Stat the file
Test/sub/function documentation

filter_tools.inc

Created: Tue Jan 22 13:14:48 2008


filter_tools.inc:
function hGetFilter680FromUNO( bTemplate as boolean ) as string

Retrieve a localized filtername from UNO


filter_tools.inc:
function hFindUNOTemplateInFilterList( sFilter as string ) as integer

Function to find a TEMPLATE filter in the filter list

Test/sub/function documentation

formcontrols.inc

Created: Tue Jan 22 13:14:48 2008


formcontrols.inc:
function hGetControlParams( cParam as string ) as integer

Retrieve basic parameters to draw formcontrols to a dialog

All values are in percent relative to the window size. All values are optimized for 1024x768 pixels screen resolution but have been tested successfully with 1280x1024 and 800x600
In most cases it is desired to place multiple controls on a single dialog pane. To prevent the controls from overlapping each other they are arranged in rows and columns. Each control is identified by a unique number (see description for hInsertControl(...)). The dimensions are defined in hGetControlParams(...). The coordinates returned by this function can be used to draw and to select a control.
Input:
  1. Name of the coordinate (string). Valid options are:
    • "XOREGO" (Upper left corner)
    • "YOREGO" (Upper left corner)
    • "XDIST" (Distance between the upper left corners of neighbor controls)
    • "YDIST" (Distance between the upper left corners of neighbor controls)
    • "XSIZE" (Width of control)
    • "YSIZE" (Heighth of the control)
Returns:
  1. Coordinate/Distance/Size in percent of window size (integer)
    • A number between 1 and 100
    • 0 on error (invalid function parameter)
Description:
  • Currently following values are defined:
    • XOREGO = 31
    • XDIST = 8
    • XSIZE = 6
    • YOREGO = 30
    • YDIST = 7
    • YSIZE = 5
    • Incorrect function parameter = 0

formcontrols.inc:
function hGetControlName( iControl as integer ) as string

A function to deliver a speaking name for all form controls

Note that the numbers of the controls are unique
In most cases it is desired to place multiple controls on a single dialog pane. To prevent the controls from overlapping each other they are arranged in rows and columns. Each control is identified by a unique number (see description for hInsertControl(...)). The dimensions are defined in hGetControlParams(...). The coordinates returned by this function can be used to draw and to select a control.
Input:
  1. Number of the control (integer)
    • Any number between 1 and 22, see description below
Returns:
  1. Name for a control (string)
    • Name for a control (may contain whitespaces)
    • An empty string in case of an invalid function parameter
Description:
  • Currently following control are defined:
    1. Push Button
    2. Image Control
    3. Check Box
    4. Radio Button
    5. Fixed Text
    6. Edit Field
    7. List Box
    8. Combo Box
    9. Vertical ScrollBar
    10. Horizontal ScrollBar
    11. Frame
    12. Progress Bar
    13. Vertical Fixed Line
    14. Horizontal Fixed Line
    15. Date Field
    16. Time Field
    17. Numeric Field
    18. Currency Field
    19. Form Field
    20. Pattern Field
    21. File Control
    22. Tree Control
  • "" for function parameter < 1 or > 22

formcontrols.inc:
function hInsertControl( iControl as integer ) as string

Function to insert one of the BASIC formcontrols by index

Note that the numbers of the controls are unique
In most cases it is desired to place multiple controls on a single dialog pane. To prevent the controls from overlapping each other they are arranged in rows and columns. Each control is identified by a unique number (see description for hInsertControl(...)). The dimensions are defined in hGetControlParams(...). The coordinates returned by this function can be used to draw and to select a control.
Input:
  1. Number of the control (integer)
    • Any number between 1 and 22, see description below
Returns:
  1. Name for a control (string)
    • Name for a control (may contain whitespaces)
    • An empty string in case of an invalid function parameter
Description:
  • Click on the requested button on the ToolsCollectionBar:
    1. Push Button
    2. Image Control
    3. Check Box
    4. Radio Button
    5. Fixed Text
    6. Edit Field
    7. List Box
    8. Combo Box
    9. Vertical ScrollBar
    10. Horizontal ScrollBar
    11. Frame
    12. Progress Bar
    13. Vertical Fixed Line
    14. Horizontal Fixed Line
    15. Date Field
    16. Time Field
    17. Numeric Field
    18. Currency Field
    19. Form Field
    20. Pattern Field
    21. File Control
    22. Tree Control
  • "" for function parameter < 1 or > 22

formcontrols.inc:
function hDrawControlOnDialog( iControl as integer ) as string

Draw a control on a dialog at a fixed position

Note that the numbers of the controls are unique
In most cases it is desired to place multiple controls on a single dialog pane. To prevent the controls from overlapping each other they are arranged in rows and columns. Each control is identified by a unique number (see description for hInsertControl(...)). The dimensions are defined in hGetControlParams(...). The coordinates returned by this function can be used to draw and to select a control.
Input:
  1. Number of the control (integer)
    • Any number between 1 and 22, see description for hInsertControl()
Returns:
  1. Name for a control (string)
    • Name for a control (may contain whitespaces)
    • An empty string in case of an invalid function parameter
Description:
  • Verify function parameter (this is a top level function)
  • determine where the control is to be painted (hGetControlPos...)
  • click the desired control
  • Draw the control (using hDrawControl(...))

formcontrols.inc:
function hDrawControl( xPos as integer, yPos as integer, xEnd as integer, yEnd as integer ) as boolean

Draw a control on the dialog pane in the dialog editor

Starting point: Basic IDE/Dialog editor
In most cases it is desired to place multiple controls on a single dialog pane. To prevent the controls from overlapping each other they are arranged in rows and columns. Each control is identified by a unique number (see description for hInsertControl(...)). The dimensions are defined in hGetControlParams(...). The coordinates returned by this function can be used to draw and to select a control.
Note: All units are in percent of the relative to the current window size
Input:
  1. X-Orego (Upper left corner) (integer)
    • Min = 0
    • Max = 100 (allowed but not useful)
  2. Y-Orego (Upper left corner) (integer)
    • Min = 0
    • Max = 100 (allowed but not useful)
  3. X-End (Lower right corner) (integer)
    • Min = 0
    • Max = 100 (allowed but not useful)
  4. Y-End (Lower right corner) (integer)
    • Min = 0
    • Max = 100 (allowed but not useful)
Returns:
  1. Errorstatus (boolean)
    • TRUE on success
    • FALSE on failure
Description:
  • Set context to Basic IDE
  • Draw the control using mouse actions
    1. Mouse down on pos X/Y-Orego
    2. Mouse move to pos X/Y-End
    3. Mouse up on pos X/Y-End

formcontrols.inc:
function hGetControlPosXO( iControl as integer ) as integer

Retrieve the upper left X-coordinate for a control

In most cases it is desired to place multiple controls on a single dialog pane. To prevent the controls from overlapping each other they are arranged in rows and columns. Each control is identified by a unique number (see description for hInsertControl(...)). The dimensions are defined in hGetControlParams(...). The coordinates returned by this function can be used to draw and to select a control.
Input:
  1. Number of the control (integer)
    • Any number between 1 and 22, see description for hInsertControl()
Returns:
  1. X-Orego in percent of window size (integer)
Description:
  • Define an offset for the control depending on its ID
    • < 7 : Column one
    • 7 ... 12 : Column two
    • 13 ... 18 : Column three
    • > 18 : Column four

formcontrols.inc:
function hGetControlPosYO( iControl as integer ) as integer

Retrieve the upper left Y-coordinate for a control

In most cases it is desired to place multiple controls on a single dialog pane. To prevent the controls from overlapping each other they are arranged in rows and columns. Each control is identified by a unique number (see description for hInsertControl(...)). The dimensions are defined in hGetControlParams(...). The coordinates returned by this function can be used to draw and to select a control.
Input:
  1. Number of the control (integer)
    • Any number between 1 and 21, see description for hInsertControl()
Returns:
  1. Y-Orego in percent of window size (integer)
Description:
  • Define an offset for the control depending on its ID
    • 1 , 7 , 13 , 19 : Row one
    • 2 , 8 , 14 , 20 : Row two
    • 3 , 9 , 15 , 21 : Row three
    • 4 , 10 , 16 , 22 : Row four
    • 5 , 11 , 17 : Row five
    • 6 , 12 , 18 : Row six

formcontrols.inc:
function hGetControlPosXE( iControl as integer ) as integer

Retrieve the lower right X-coordinate for a control

In most cases it is desired to place multiple controls on a single dialog pane. To prevent the controls from overlapping each other they are arranged in rows and columns. Each control is identified by a unique number (see description for hInsertControl(...)). The dimensions are defined in hGetControlParams(...). The coordinates returned by this function can be used to draw and to select a control.
Input:
  1. Number of the control (integer)
    • Any number between 1 and 22, see description for hInsertControl()
Returns:
  1. X-End in percent of window size (integer)
Description:
  • Get pos for X-Orego, add "XSIZE"

formcontrols.inc:
function hGetControlPosYE( iControl as integer ) as integer

Retrieve the lower right Y-coordinate for a control

In most cases it is desired to place multiple controls on a single dialog pane. To prevent the controls from overlapping each other they are arranged in rows and columns. Each control is identified by a unique number (see description for hInsertControl(...)). The dimensions are defined in hGetControlParams(...). The coordinates returned by this function can be used to draw and to select a control.
Input:
  1. Number of the control (integer)
    • Any number between 1 and 22, see description for hInsertControl()
Returns:
  1. Y-End in percent of window size (integer)
Description:
  • Get pos for Y-Orego, add "YSIZE"

formcontrols.inc:
function hGetControlPosXM( iControl as integer ) as integer

Retrieve the center (X) of a control

In most cases it is desired to place multiple controls on a single dialog pane. To prevent the controls from overlapping each other they are arranged in rows and columns. Each control is identified by a unique number (see description for hInsertControl(...)). The dimensions are defined in hGetControlParams(...). The coordinates returned by this function can be used to draw and to select a control.
Input:
  1. Number of the control (integer)
    • Any number between 1 and 22, see description for hInsertControl()
Returns:
  1. X-Center in percent of window size (integer)
Description:
  • Find X-Orego
  • Find X-End
  • Calculate the distance, find the middle between the two

formcontrols.inc:
function hGetControlPosYM( iControl as integer ) as integer

Retrieve the center (Y) of a control

In most cases it is desired to place multiple controls on a single dialog pane. To prevent the controls from overlapping each other they are arranged in rows and columns. Each control is identified by a unique number (see description for hInsertControl(...)). The dimensions are defined in hGetControlParams(...). The coordinates returned by this function can be used to draw and to select a control.
Input:
  1. Number of the control (integer)
    • Any number between 1 and 22, see description for hInsertControl()
Returns:
  1. Y-Center in percent of window size (integer)
Description:
  • Find Y-Orego
  • Find Y-End
  • Calculate the distance, find the middle between the two

formcontrols.inc:
function hSelectControl( iControl as integer ) as boolean

Function to select one of the BASIC formcontrols by index

Note: Refer to the inline documentation for implementation details
In most cases it is desired to place multiple controls on a single dialog pane. To prevent the controls from overlapping each other they are arranged in rows and columns. Each control is identified by a unique number (see description for hInsertControl(...)). The dimensions are defined in hGetControlParams(...). The coordinates returned by this function can be used to draw and to select a control.
Input:
  1. Number of the control (integer)
    • Any number between 1 and 22, see description for hInsertControl()
Returns:
  1. Errorstatus (boolean)
    • TRUE if the properties-button on ToolsCollectionBar is enabled
    • FALSE in any other case
Description:
  • Check function parameter, this is a top level function
  • Verify that the ToolsCollectionBar is visible. if not: Abort
  • Enable the selection mode on ToolsCollectionBar
  • Try four different ways of selecting the control before giving up
    1. Mouse-Click in the middle
    2. Mouse-Click on upper left corner
    3. Mouse-Click on lower right corner
    4. Rubberband around the control (Mouse movement)
    5. Deselct everything and use to activate the control
  • Check that the ToolsCollectionBar is open
Test/sub/function documentation

help_tools.inc

Created: Tue Jan 22 13:14:48 2008


help_tools.inc:
function hOpenHelp() as boolean

Function to open the Help Browser

Input:
  1. Nothing
Returns:
  1. Errorcondition (boolean)
    • TRUE if the help is open
    • FALSE if the help did not open
Description:
  • Open the help Browser using the slot
  • Verify that the help is indeed open (max 10 sec.)
  • Print a status to the log, return TRUE or FALSE

help_tools.inc:
function hCloseHelp() as boolean

Function to close the Help Browser

Input:
  1. Nothing
Returns:
  1. Errorcondition (boolean)
    • TRUE if the help is closed
    • FALSE if the help did not close
Description:
  • Verify that the Help Browser is Open
  • Close the Help Browser by typing CTRL+F4
  • Verify that the Help Browser is not open (anymore)
  • Return TRUE or FALSE

help_tools.inc:
function hSelectHelpTab( cTab as string ) as boolean

Select a tab on the help dialog by name

Input:
  1. The tab to open (string)
    • "content" for the contents tab
    • "index" for the index tab
    • "find" for the find tab
    • "bookmarks" for the bookmarks tab
Returns:
  1. Errorcondition (boolean)
    • TRUE if the requested tabpage is open
    • FALSE if the requested tabpage did not open
Description:
  • Select the requested Tabpage, verify that it is open
  • Print a comment to the log
  • Return TRUE or FALSE

help_tools.inc:
function hUseBookmarksContextMenu( cAction as string ) as boolean

handle the bookmarks context menu in Help Browser

Input:
  1. The context item to execute (string)
    • "show"
    • "rename"
    • "delete"
Returns:
  1. Errorcondition (boolean)
    • TRUE on success
    • FALSE on any other error
Description:
  • Verify that we are on the Bookmarks Page
  • Find the index of the requested entry
  • If action is unsuported, return false and exit the function
  • Open the context menu and select the requested index
  • Return TRUE if all went well so far

help_tools.inc:
function hHelpGetAboutItemCount() as integer

Get the number of applications listed in the Help ListBox

Input:
  1. Nothing
Returns:
  1. Number of applications listed (integer)
    • The default is 7
Description:
  • Open Help
  • get the number of applications from the drop down box
  • Print the list of items to the log
  • close help

help_tools.inc:
function hHelpGetSearchIndexItemCount() as integer

Get the number of items in the Help Search Index

Starting point: Help / Index page
Note: Workaround for incorrect value returned by .getItemCount()
Input:
  1. Nothing
Returns:
  1. Number of items in the list (integer)
Description:
  • Run through the list and count the items, break on error

help_tools.inc:
function hGetHelpContentHeader( iLength as integer ) as string

Get the header of the content in the help browser

This is the first line of the content page, truncated (if desired)

Parameter(s):
  1. Length of the requested string (Integer)
    • The max length of the string to be returned
    • ≤ 0 = do not truncate
Returns:
  1. Header (String)
    • A string containing the content header
    • The header is the first line of the content page
Description:
  • Maximize the help viewer (required to avoid cut off strings)
  • Go to the top left position in the help browser
  • Mark the entire line - note that this ends at the linebreak
  • Copy the string to the clipboard
  • Assign the string to a variable
  • Truncate string
Test/sub/function documentation

i18n_tools.inc

Created: Tue Jan 22 13:14:48 2008


i18n_tools.inc:
function hGetI18nData( cSection as string, cLanguage as string ) as string

Retrieve various information about i18n

Uses datafile: framework/tools/input/i18ndata.txt
Input:
  1. Section from which to retrieve the data (string)
    • Any name of a section existing in the datafile
  2. Language code as string
    • Use hGetTwoDigitLangCode(...) to ensure proper string formatting
Returns:
  1. Language identifier (string)
Description:
  • Create the path to the datafile
  • Find out the required size of the array to hold the entire file
  • Define an array to hold the datafile
  • Retrieve the requested section from the datafile
  • Isolate the requested language item

i18n_tools.inc:
function hGetTwoDigitLangCode( iLanguage as integer ) as string

Retrieve a two digit language code from integer

Replaces and enhances deprecated sub "siSpracheSetzen"
Input:
  1. Language Code (integer)
    • Any number between (and including) 1 and 99
Returns:
  1. Language Code (string)
    • 1 - 9 -> "01" - "09"
    • 10 - 99 -> "10" - "99"
Description:
  • Convert single digit language code to two digit language string

i18n_tools.inc:
function hTestLocale() as boolean

Test whether we are running on an utf8 locale (Linux only)


Parameter(s):
  1. No input parameters
Returns:
  1. Errorcondition (boolean)
    • TRUE: Yes, this is a UTF-8 locale
    • FALSE: Anything else
Description:
  • Retrieve LANG
  • Retrieve LC_ALL (Note that this variable is mostly set but has no value assigned)
Test/sub/function documentation

init_tools.inc

Created: Tue Jan 22 13:14:48 2008


init_tools.inc:
function hInitSingleDoc() as boolean

Make sure exactly one single writer document is open

The wizards cannot be triggered correctly from the backing window. As a workaround this function checks the amount of open documents and creates exactly one unchanged Writer document

Parameter(s):
  1. No input parameters
Returns:
  1. Errorcondition (Boolean)
    • TRUE: Exactly one Writer document is open
    • FALSE: Any error
Description:
  • Close all documents until we are on the backing window
  • Save the previous gApplication
  • Set gApplication to WRITER
  • Open one new Writer document
  • Verify that exactly one document is open
  • Restore gApplication

init_tools.inc:
function hInitBackingMode() as boolean

Make that we are on the backing window (no open documents)

Close all open documents

Parameter(s):
  1. No input parameters
Returns:
  1. Errorcondition (Boolean)
    • TRUE: No open documents are present
    • FALSE: Any error
Description:
  • Close all documents until we are on the backing window
  • verify that we do not have any open documents left (redundant check)

init_tools.inc:
function hInitWriteDocIdentifier( cString as string ) as boolean

Write a specific string to an open writer document

This function verifies that exactly one document is open, that this is a Writer document and writes the string to the document

Parameter(s):
  1. A free form string (String) which serves as identifier for the document
    • The first character should be uppercase
Returns:
  1. Errorcondition (Boolean)
    • TRUE: The string was written correctly
    • FALSE: Too many open documents
    • FALSE: Not a Writer document
    • FALSE: Any other error
Description:
  • Verify number of open documents
  • Verify that it is a writer document
  • Write the string
  • Verify the string
Test/sub/function documentation

javatools.inc

Created: Tue Jan 22 13:14:48 2008


javatools.inc:
function hBatchLoadJavaFiles( aFileList() , cIdent as string )

Load and close a list of files with recovery on error

Input: A list containing files to load
Returns: No returnvalue
  • Loop through the list, starting at index 2
  • Load a file, verify
  • close the file, verify
  • There should be one document left: The first doc
  • Check for hs_err_pidXXXX.log files (Java Exceptions)

javatools.inc:
function hFindCopyRemoveJavaLogs( cSourcePath as string ) as boolean

Search/move hs_err_pidXXXX.log files within a directory recursively

Input: Start directory
Returns: TRUE if no errors were found
  • Look for leftover hs_err_pidXXXX.log files
  • Print the list to the log
  • Copy the hs_err...log files to the local work directory
  • Delete the original log file(s)
Test/sub/function documentation

key_tools.inc

Created: Tue Jan 22 13:14:48 2008


key_tools.inc:
function hGetDataPairAsString( sKey as string, sVal as long ) as string

Concatenate two strings and insert an = sign

About "KEY"-functions:
These functions are used whenever data is to be processed that is stored in a key=value format.
They handle a single string or a list of strings to e.g. isolate a key, a value or to just retrieve the pair.


Input:
  1. KEY (string)
    • Anything but should not contain # or '
  2. VALUE (string)
    • Anything but should not contain # or '
Returns:
  1. KEY=VALUE pair (string)
Description:
  • Returns string1=string2

key_tools.inc:
function hGetValueForPairAsString( cLine as string ) as string

Retrieve value from a key=value string

About "KEY"-functions:
These functions are used whenever data is to be processed that is stored in a key=value format.
They handle a single string or a list of strings to e.g. isolate a key, a value or to just retrieve the pair.


Input:
  1. KEY=VALUE pair (string)
Returns:
  1. VALUE (string)
    • Anything after the = character
Description:
  • Locate the equal sign
  • Isolate everything to the right of the equal sign
  • Return the value as string

key_tools.inc:
function hGetValueForPairAsLong( cLine as string ) as long

Retrieve the value from a key=value pair as long

About "KEY"-functions:
These functions are used whenever data is to be processed that is stored in a key=value format.
They handle a single string or a list of strings to e.g. isolate a key, a value or to just retrieve the pair.


Input:
  1. KEY=VALUE pair (string)
Returns:
  1. VALUE (long)
    • Anything after the = character as long integer value
Description:
  • Locate the equal sign
  • Isolate and return the Value as long datatype

key_tools.inc:
function hGetValueForKeyAsInt( lsList() as string, sKey as string ) as integer

Retrieve the value of a key=value pair as integer

About "KEY"-functions:
These functions are used whenever data is to be processed that is stored in a key=value format.
They handle a single string or a list of strings to e.g. isolate a key, a value or to just retrieve the pair.


Prerequisite: Array compatible to listfuncs, known, valid key

Input:
  1. List of KEY=VALUE pairs (string)
    • List must be compatible to listfunctions (see listfuncs.inc)
  2. Key to be searched for within the list (string)
    • Key must be valid
Returns:
  1. VALUE (integer)
    • The value for a given key
Description:
  • Search the list for the key
  • Verify that this is really the correct key by reverse-checking
  • Retrieve the value for the key as string
  • Convert the stringvalue to integer and return it

key_tools.inc:
function hGetValueForKeyAsLong( lsList() as string, sKey as string ) as long

Retrieve the value of a key=value pair as integer

About "KEY"-functions:
These functions are used whenever data is to be processed that is stored in a key=value format.
They handle a single string or a list of strings to e.g. isolate a key, a value or to just retrieve the pair.


Prerequisite: Array compatible to listfuncs, known, valid key

Input:
  1. List of KEY=VALUE pairs (string)
    • List must be compatible to listfunctions (see listfuncs.inc)
  2. Key to be searched for within the list (string)
    • Key must be valid
Returns:
  1. VALUE (long integer)
    • The value for a given key
Description:
  • Search the list for the key
  • Verify that this is really the correct key by reverse-checking
  • Retrieve the value for the key as string
  • Convert the stringvalue to long integer and return it

key_tools.inc:
function hGetKeyForPairAsString( cLine as string ) as string

Retrieve the KEY from a key=value pair

About "KEY"-functions:
These functions are used whenever data is to be processed that is stored in a key=value format.
They handle a single string or a list of strings to e.g. isolate a key, a value or to just retrieve the pair.


Input:
  1. KEY=VALUE pair (string)
Returns:
  1. KEY (string)
    • Anything before the = character
Description:
  • get the string to the left of the = char
  • Return the key

key_tools.inc:
function hGetKeyForValueAsString( lsList() as string, sVal as string ) as string

Retrieve the KEY for a known VALUE from a key=value pair

About "KEY"-functions:
These functions are used whenever data is to be processed that is stored in a key=value format.
They handle a single string or a list of strings to e.g. isolate a key, a value or to just retrieve the pair.


Prerequisite: List compatible to listfuncs, known VALUE for pair

Input:
  1. List of KEY=VALUE pairs (string)
  2. VALUE (string)
    • Absolute match required.
Returns:
  1. KEY (string)
Description:
  • scan through a list to find an entry that matches sKey. Return the Key.
  • Return the key from the first matching value

key_tools.inc:
function hGetKeyForValueAsInt( lsList() as string, sVal as string ) as integer

Retrieve the KEY for a known VALUE from a key=value pair

About "KEY"-functions:
These functions are used whenever data is to be processed that is stored in a key=value format.
They handle a single string or a list of strings to e.g. isolate a key, a value or to just retrieve the pair.


Prerequisite: List compatible to listfuncs, known VALUE for pair

Input:
  1. List of KEY=VALUE pairs (string)
  2. VALUE (string)
    • Absolute match required.
Returns:
  1. KEY (integer)
Description:
  • Use hgetKeyForValueAsString, convert result to integer, return it.

key_tools.inc:
function hGetIndexForKeyAsInt( lsList() as string, sKey as string ) as integer

Search a list of key=value pairs for a key and return its index

About "KEY"-functions:
These functions are used whenever data is to be processed that is stored in a key=value format.
They handle a single string or a list of strings to e.g. isolate a key, a value or to just retrieve the pair.


Prerequisite: List compatible to listfuncs, known VALUE for pair

Input:
  1. List of KEY=VALUE pairs (string)
  2. KEY to search for (string)
Returns:
  1. Index of the KEY in the list (integer)
    • 0 if not found
    • Any number > 0 and ≤ listcount( List() )
Description:
  • Scan through the list for the KEY
  • if found, perform reverse checking
  • get the index of the item
  • Return the index

key_tools.inc:
function keycompare( found as string, expected as string, sKey as string, optional cBugID as string) as boolean

Function to compare two keys with each other

Deprecated, do not use Test/sub/function documentation

listfuncs.inc

Created: Tue Jan 22 13:14:48 2008


listfuncs.inc:
function hListTestUpperBoundary( aList() as string ) as boolean

Verify that ListCount does not exceed upper boundary

About listfunctions: All listfunctions rely on a special type of array. This can be string arrays and - in some cases - numeric arrays. What makes the arrays unique is that the first item which has the index 0 contains the number of items in the list to be used, anything that is stored beyond this number is ignored. This has three consequences: 1) all listfunctions that alter an array must update the index stored in array(0) and 2) it is possible that the index point beyond ubound of the array which will most likely cause a runtime error. 3) Means that arrays may only have an upper boundary declared, all loops must start with index array(1) and must end with index array(val( array(0))
Input:
  1. List (string)
Returns:
  1. Errorstatus (boolean)
    • TRUE: Array is ok
    • FALSE: Array logic has errors
Description:
  • Determine the size of the array
  • Determine the claimed size of the array
  • Verify that val(array(0)) <= array-size

listfuncs.inc:
function hListTestLowerBoundary( aList() as string ) as boolean

Verify that the lower boundaries of an array are ok

Prerequisite: Array compatible with those from t_lists.inc About listfunctions: All listfunctions rely on a special type of array. This can be string arrays and - in some cases - numeric arrays. What makes the arrays unique is that the first item which has the index 0 contains the number of items in the list to be used, anything that is stored beyond this number is ignored. This has three consequences: 1) all listfunctions that alter an array must update the index stored in array(0) and 2) it is possible that the index point beyond ubound of the array which will most likely cause a runtime error. 3) Means that arrays may only have an upper boundary declared, all loops must start with index array(1) and must end with index array(val( array(0))
Input:
  1. List (string)
Returns:
  1. Errorstatus (boolean)
    • TRUE: Array is ok
    • FALSE: Array logic has errors
Description:
  • Verify that ubound for the array returns 0 (lower boundary)
  • Verify that val(array(0)) > 0

listfuncs.inc:
function hListDelete( aList() as string, iItemToDelete as integer ) as boolean

Delete one item from a list specified by index

Prerequisite: Array compatible with those from t_lists.inc
About listfunctions: All listfunctions rely on a special type of array. This can be string arrays and - in some cases - numeric arrays. What makes the arrays unique is that the first item which has the index 0 contains the number of items in the list to be used, anything that is stored beyond this number is ignored. This has three consequences: 1) all listfunctions that alter an array must update the index stored in array(0) and 2) it is possible that the index point beyond ubound of the array which will most likely cause a runtime error. 3) Means that arrays may only have an upper boundary declared, all loops must start with index array(1) and must end with index array(val( array(0))
Review the code, it has many unused variables
  • test array integrity: upper boundary
  • test array integrity: lower boundary
  • Get some data from the arrays to work with.
  • Move all items one up
  • Delete the last item from the list
  • Set the new listsize (one smaller than the original list)

listfuncs.inc:
function hListAppend( sNewString as string, aTargetList() as string ) as integer

Append an item to an existing list

Prerequisite: Array compatible with those from t_lists.inc About listfunctions: All listfunctions rely on a special type of array. This can be string arrays and - in some cases - numeric arrays. What makes the arrays unique is that the first item which has the index 0 contains the number of items in the list to be used, anything that is stored beyond this number is ignored. This has three consequences: 1) all listfunctions that alter an array must update the index stored in array(0) and 2) it is possible that the index point beyond ubound of the array which will most likely cause a runtime error. 3) Means that arrays may only have an upper boundary declared, all loops must start with index array(1) and must end with index array(val( array(0))

listfuncs.inc:
function hManageComparisionList( sFileIn as string, sFileOut as string, sListOut() as string ) as integer

Function to create or compare a list to a reference

Prerequisite: List of items to compare, input- and outputfilename
About listfunctions: All listfunctions rely on a special type of array. This can be string arrays and - in some cases - numeric arrays. What makes the arrays unique is that the first item which has the index 0 contains the number of items in the list to be used, anything that is stored beyond this number is ignored. This has three consequences: 1) all listfunctions that alter an array must update the index stored in array(0) and 2) it is possible that the index point beyond ubound of the array which will most likely cause a runtime error. 3) Means that arrays may only have an upper boundary declared, all loops must start with index array(1) and must end with index array(val( array(0))
BEWARE: This is a core function and used by many tests!
Please read the inline documentation for further reference

Function parameters:
  1. sFileIn = The file that contains the reference data
  2. sFileOut = The file new lists are written to in case of an error
  3. sListOut() = The list containing the newly retrieved data.
Description:
  • The name of the input file may not be empty
  • The name of the output-file may not be empty
  • the list should not claim to be empty / be empty
  • Verify that the reference file exists and is non-empty
  • Read the reference list and compare
  • In case the lists are not identical, write the new one to the local work directory
  • Return 0 if the lists are identical, 1 if not and 2-4 on any other error

listfuncs.inc:
function hListFileGetSize( sFileIn as string ) as integer

Get the number of lines from a file

Prerequisites: Path to an existing plain text file About listfunctions: All listfunctions rely on a special type of array. This can be string arrays and - in some cases - numeric arrays. What makes the arrays unique is that the first item which has the index 0 contains the number of items in the list to be used, anything that is stored beyond this number is ignored. This has three consequences: 1) all listfunctions that alter an array must update the index stored in array(0) and 2) it is possible that the index point beyond ubound of the array which will most likely cause a runtime error. 3) Means that arrays may only have an upper boundary declared, all loops must start with index array(1) and must end with index array(val( array(0))
  • Verify that the filename is non-empty
  • Verify that the file exists
  • Open the file (standard BASIC calls)
  • Read the number of lines from the file
  • Close the file
  • Return the number of lines read or -1 on error

listfuncs.inc:
function hListCompare( aListOne() as String, aListTwo() as String ) as boolean

Compare two lists with each other, where list TWO is the reference

Prerequisites: Two lists compatible with listfunctions
About listfunctions: All listfunctions rely on a special type of array. This can be string arrays and - in some cases - numeric arrays. What makes the arrays unique is that the first item which has the index 0 contains the number of items in the list to be used, anything that is stored beyond this number is ignored. This has three consequences: 1) all listfunctions that alter an array must update the index stored in array(0) and 2) it is possible that the index point beyond ubound of the array which will most likely cause a runtime error. 3) Means that arrays may only have an upper boundary declared, all loops must start with index array(1) and must end with index array(val( array(0))
Duplicates gCompare2Lists but does not print warnlogs, evaluate returncode instead
  • Create a copy of list two so we do not change the original list
  • Step through each item in list one
  • Compare it to each item in list two
  • If the entries match, delete it from the TwoOnly list
  • If there is no match, the item exists in list one only -> copy
  • List all items that exist in List One only
  • List all items that exist in List Two only

listfuncs.inc:
function hListPrependString( aList() as string, cString as string ) as boolean

Insert a string infront of each item in a list

Prerequisites: A list compatible with listfunctions
About listfunctions: All listfunctions rely on a special type of array. This can be string arrays and - in some cases - numeric arrays. What makes the arrays unique is that the first item which has the index 0 contains the number of items in the list to be used, anything that is stored beyond this number is ignored. This has three consequences: 1) all listfunctions that alter an array must update the index stored in array(0) and 2) it is possible that the index point beyond ubound of the array which will most likely cause a runtime error. 3) Means that arrays may only have an upper boundary declared, all loops must start with index array(1) and must end with index array(val( array(0))

Note that the function alters the input list. If the list contains strings of the type "MyString" the items will be changed to read "Some Text : MyString"
Input:
  1. List (string)
  2. A text to be inserted infront of every item in the list
Returns:
  1. Errorcondition (boolean)
    • The returnvalue is currently undefined
Description:
  • Cycle through the list and insert a text infront of each item

listfuncs.inc:
function hListAppendList( aBaseList() as string, aListToAppend() as string ) as integer

Append one list to another

Prerequisites: A list compatible with listfunctions
About listfunctions: All listfunctions rely on a special type of array. This can be string arrays and - in some cases - numeric arrays. What makes the arrays unique is that the first item which has the index 0 contains the number of items in the list to be used, anything that is stored beyond this number is ignored. This has three consequences: 1) all listfunctions that alter an array must update the index stored in array(0) and 2) it is possible that the index point beyond ubound of the array which will most likely cause a runtime error. 3) Means that arrays may only have an upper boundary declared, all loops must start with index array(1) and must end with index array(val( array(0))

Input:
  1. Target list (string)
  2. Source list (string)
Returns:
  1. Listsize (integer)
    • The size of the sum of both lists
    • 0 in case of error
Description:
  • Do some basic boundary checking
  • Append the list

listfuncs.inc:
function hCountMatchesInList( acItemList() as string, cSearchTerm as string ) as integer

Find out how many times a string is found in a list

Parameter(s):
  1. List to be searched (String)
    • The list may not be empty
    • Search begins at index 1
  2. Expression to search for (String)
    • Only exact matches are counted
Returns:
  1. Number of hits (Integer)
    • 0: if no matches were found
    • -1: Any error
Description:
  • Retrieve the number of items in the list
  • Walk through the list and count the hits
Test/sub/function documentation

macro_tools.inc

Created: Tue Jan 22 13:14:48 2008


macro_tools.inc:
function hInsertMacroFromFile( cMacroId ) as integer

Paste a macro (taken from a file) to the basic IDE

uses: framework/tools/input/macros.txt
Starting point: Basic IDE
Note: Overwrites any existing macros in the current module
Input:
  1. Name (ID) of the macro to be inserted (string)
    • Allowed is any string that corresponds to a section in the source file
Returns:
  1. Number of lines inserted (integer)
    • 0: Error, no lines inserted
    • > 0: Number of lines
Description:
  • Find the path to the source file
  • Determine the required array size
  • retrieve the macro from the file with ID as section
  • Delete all content from the BASIC IDE edit window
  • Insert the code into the IDE line by line

macro_tools.inc:
function hMacroOrganizerRunMacro( cMacroName as string ) as integer

Execute a macro by name

Starting point: Any document
The function runs silent
Input:
  1. Name of the macro to be run (string)
    • Any macro that can run by itself (main)
Returns:
  1. Position of the macro in the treelist (integer)
    • 0 = error
    • 1-n = position of macro
Description:
  • Go to Tools/Macros/Organize Macros/OpenOffice.org Basic
  • Find the Macro
  • Run the macro
Test/sub/function documentation

pbrowser_tools.inc

Created: Tue Jan 22 13:14:48 2008


pbrowser_tools.inc:
function hOpenPropertyBrowser() as boolean

Function to open the properties of a selected control

The function verifies that the property browser is really open and ensures that we are on the General tabpage

Input:
  1. Nothing
Returns:
  1. Errorcondition (boolean)
    • TRUE on successful open of the property browser
    • FALSE on any error
Description:
  • Open the property browser (call slot)
  • Verify that the property browser is open
  • Activate General-tabpage
  • Verify that the General-tabpage is visible

pbrowser_tools.inc:
function hClosePropertyBrowser() as boolean

A function that closes the Property-Browser

The property browser is closed by executing the slot (the slot toggles the dialog).

Input:
  1. Nothing
Returns:
  1. Errorcondition (boolean)
    • TRUE if the Property Browser has been closed
    • FALSE if the property browser is not open
    • FALSE if the property browser could not be closed
Description:
  • Verify that the property browser is open
  • Execute the ContextProperties slot
  • Verify that the property browser is closed

pbrowser_tools.inc:
function hPBSetControlName( cControl as string ) as boolean

Name a control, with limited errorhandling

This function was introduced due to a problem with the property- browser not being open fast enough or just refusing to accept input

Input:
  1. Text to be inserted in the control "NameText" (string)
Returns:
  1. Errorcondition
    • TRUE: The control name was successfully updated
    • FALSE: Control is not visible within current context
Description:
  • Test that the control "NameText" exists
  • Set the new name

pbrowser_tools.inc:
function hPBGetControlName( cControl as string ) as boolean

Verify that the expected control is open

Use hPBSetControlName( string ) to set the name and when you reopen it verify that you got the right control wit this function

Input:
  1. Name of the control (string)
Returns:
  1. Errorcondition (boolean)
    • TRUE: The control has the correct name
    • FALSE: Any other condition
Description:
  • If "NameText" exists, retrieve its text
  • Verify that the name is correct

pbrowser_tools.inc:
function hCheckPropertyPresence ( cSetting as string , iPos as integer ) as boolean

Function to determine whether a property is available for a control or not

This function takes a string (provided by controlcfg.dat) and looks for an 'x' at. a given position. If it is found it returns TRUE, FALSE if it is a '-'
Note that this function is a terrible workaround for a missing feature: In the current version of the Testtool we cannot ask which controls are present on a dialog. So this has to be kept in a list of some sort. This is especially bad for a property browser test as we need to maintain such a list for 21 controls and a total of 76 (IIRC) possible properties whereof only a small number (eight, i think) are common for all controls. The test is barely maintainable, issues have been written but there is no solution so far.


Input:
  1. Configuration string (string)
    • The string must be taken from file "controlcfg.dat"
  2. Position of the control (integer)
    • > 0 and < 74 (all possible control config items)
Returns:
  1. Status (boolean)
    • TRUE: The property should exist for the current control
    • FALSE: The property is not expected to exist for this control
Description:
  • Find the requested position in the string, set TRUE if it is an "x"

pbrowser_tools.inc:
function hSetPBTabPage( iPage as integer ) as boolean

A small helper to switch between tabpages in the property-browser

Input:
  1. Page-ID (integer)
    • 1 = General page
    • 2 = Events page
Returns:
  1. Errorcondition (boolean)
    • TRUE on success
    • FALSE on any error
Description:
  • Switch to the requested page

pbrowser_tools.inc:
function hSetLabelName( sLabelName as string ) as boolean

Name a control, with limited errorhandling

This function was introduced due to a problem with the property- browser not being open fast enough or just refusing to accept input

Input:
  1. Text to be inserted in the control "NameText" (string)
Returns:
  1. Errorcondition
    • TRUE: The control name was successfully updated
    • FALSE: Control is not visible within current context
Description:
  • Test that the control "NameText" exists
  • Set the new name
Test/sub/function documentation

performance.inc

Created: Tue Jan 22 13:14:48 2008


performance.inc:
function hWaitForObject( oControl as object, iTime as integer ) as integer

Wait for a control to get ready

Wait for a control on a toolbar to get ready for a specified amount of time. Note that this function runs silent, you have to test the return value!

Parameter(s):
  1. The control to wait for (Object)
    • Kontext must be set prior to using this function
    • The control must exist
    • This function works on most, but not all, controls
  2. Maximum time to wait in milliseconds (Integer)
    • Must be > 0
    • Must be ≤ 10000 ms (10 seconds)
Returns:
  1. Time to readiness in milliseconds(Integer)
    • -1: Control not ready within given timeframe
    • -2: Control appears not to exist
    • -≥ 0: Time to readiness
Description:
  • Verify function parameter validity
  • Verify that the control exists and wait
Test/sub/function documentation

private_environment.inc

Created: Tue Jan 22 13:14:48 2008


private_environment.inc:
function hGetPrivateHttpServer( _proxy as string, _port as string ) as boolean

Retrieve the name and port for a private http server


Function parameters:
  1. Fully qualified server name incl. domain (string)
    • The string comes without a protocol part (no http://)
  2. Server port (string)
    • Please remember limits for integer data type
Returns:
  1. Error condition (boolean)
    • "TRUE": Data was retrieved successfully
    • "FALSE": Any error
Description:
  • Get the source file
  • Retrieve the information from the datafile
  • Extract the proxy name
  • Append the domain
  • Get the port
  • Print a log

private_environment.inc:
function hGetPrivateFtpServer( _proxy as string, _port as string ) as boolean

Retrieve the name and port for a private ftp server


Function parameters:
  1. Fully qualified server name incl. domain (string)
    • The string comes without a protocol part (no ftp://)
  2. Server port (string)
    • Please remember limits for integer data type
Returns:
  1. Error condition (boolean)
    • "TRUE": Data was retrieved successfully
    • "FALSE": Any error
Description:
  • Get the source file
  • Retrieve the information from the datafile
  • Extract the proxy name
  • Append the domain
  • Get the port
  • Print a log

private_environment.inc:
function hGetPrivateSocksServer( _proxy as string, _port as string ) as boolean

Retrieve the name and port for a private socks server


Function parameters:
  1. Fully qualified server name incl. domain (string)
  2. Server port (string)
    • Please remember limits for integer data type
Returns:
  1. Error condition (boolean)
    • "TRUE": Data was retrieved successfully
    • "FALSE": Any error
Description:
  • Get the source file
  • Retrieve the information from the datafile
  • Extract the proxy name
  • Append the domain
  • Get the port
  • Print a log

private_environment.inc:
function hGetPrivateInputPath( bVerbose as boolean ) as string

Switch the private input path from ../inc/ to ../input/

This is part of the effort to allow usage of private data such as servernames, paths, login names etc. within a Local Area Network (LAN). If you have to maintain data of any sort that may not get out to the public you will want to put your data into this directory.

Input Value:
  1. Toggle verbosity (boolean)
    • "TRUE": Print path
    • "FALSE": Do not print path
Return Value:
  1. Path to the private input directory (string)
    • Function is not supposed to fail
    • Fully qualified path to the input directory including last pathseparator
Description:
  • Get the ../inc-path from global variable (assuming path is valid)
  • Append input/ (platform specific)
  • Print the resulting path to the log

private_environment.inc:
function hGetPrivateInputFile( bVerbose as boolean ) as string

Retrieve the fully qualified path to the datafile


Input:
  1. Toggle verbosity (boolean)
    • "TRUE": Print path
    • "FALSE": Do not print path
Returns:
  1. Fully qualified path to the datafile (string)
Description:
  • Append pathseparator and filename to input path
  • Print path and filename to the log
Test/sub/function documentation

scriptorganizer_tools.inc

Created: Tue Jan 22 13:14:48 2008


scriptorganizer_tools.inc:
function hCreateScriptingObject( cName as string ) as boolean

Create a new scripting object for the current module

Starting point: Script organizer is open, module selected
Input:
  1. Name of the module (string)
    • Any name the organizer can accept
Returns:
  1. Errorcondition
    • TRUE on success
    • FALSE on failure or invalid user input
Description:
  • Verify the function parameter
  • Verify that the "Create..." button exists
  • Verify that the "Create..." button is enabled
  • Click "Create..." to open the naming dialog
  • Name the new script
  • Verify that we are back on the script organizer

scriptorganizer_tools.inc:
function hRenameScriptingObject( cName as string ) as boolean

Rename the selected script

Starting point: Script organizer is open, a script is selected
Input:
  1. New name of the script
    • Any name the script organizer does accept
Returns:
  1. Errorcondition
    • TRUE on success
    • FALSE on failure or invalid user input
Description:
  • Verify the function parameter
  • Verify that the "Rename..." button exists
  • Verify that the "Rename..." button is enabled
  • Click "Rename..." to open the renaming dialog
  • Name the new script
  • Test for any messagebox, try to close it with OK
  • Verify that we are back on the script organizer

scriptorganizer_tools.inc:
function hDeleteScript( cName as string , bSuccess as boolean ) as boolean

Delete the selected script

Starting point: Script organizer is open, a script is selected
Input:
  1. Name of the script (string)
    • For debugging purpose only, the name will be used for warnlogs
    • May be an empty string (not recommended)
  2. Expected result (boolean)
    • TRUE: The script is expected to be deleted without warnings/errors
    • FALSE: The script should not be deletable
Returns:
  1. Errorcondition (boolean) - see description
    • TRUE on success (expected outcome)
    • FALSE on failure
Description:
  • Test for the possible conditions:
    1. Delete is correctly enabled (success)
    2. Delete is disabled correctly (success)
    3. Delete is enabled but should not be (failure)
    4. Delete is incorrectly disabled (failure)

scriptorganizer_tools.inc:
function hOpenScriptOrganizer( iDialog as integer ) as boolean

Open the ScriptOrganizers and verify that they are open

Starting point: Any document
Input:
  1. Dialog-ID (integer)
    • 1 = BeanShell organizer
    • 2 = JavaScript organizer
Returns:
  1. Errorcondition
    • TRUE if the expected organizer is open
    • FALSE if the expected organizer is not open
Description:
  • Call the associated slot
  • Verify that the dialog is open, return TRUE if yes

scriptorganizer_tools.inc:
function hCloseScriptOrganizer() as boolean

Close a Script Organizer (Cancel)

Starting point: Any open Script Organizer
Input:
  1. Nothing
Returns:
  1. Errorcondition (boolean)
    • TRUE if the Script Organizer was closed
    • FALSE if the Script Organizer is still open
Description:
  • Try to close the script

scriptorganizer_tools.inc:
function hOpenRunMacroDialog() as boolean

Open the "Run Macro" dialog

Starting point: Any document
Input:
  1. Nothing
Returns:
  1. Errorcondition
    • TRUE if dialog is open
    • FALSE if the Script Selector does not exist
Description:
  • Execute the ToolsMacrosRunMacro slot
  • Verify that the dialog is present
Test/sub/function documentation

security_tools.inc

Created: Tue Jan 22 13:14:48 2008


security_tools.inc:
function hSetPasswordRecommendation( bEnable as boolean ) as boolean

Toggle Tools/Options/OOo/Security: Password recommendation

Input:
  1. Mode (boolean)
    • TRUE: Switch password recommendation on
    • FALSE: Switch password recommendation off
Returns:
  1. Prior state (boolean)
    • TRUE: Password recommendation was on
    • FALSE: Password recommendation was off
Description:
  • Open Tools/Options
  • Go to the security page
  • Click on the "Options..." button
  • Retrieve the current setting for passwor recommendation
  • Set the requested state
  • Close Tools/Options

security_tools.inc:
function hOpenDigitalSignaturesDialog() as boolean

Open the Digital Signatures Dialog via File-Menu

Input:
  1. Nothing
Returns:
  1. Errorcondition (boolean)
    • TRUE: The Digital Signatures Dialog is open
    • FALSE: The Digital Signatures Dialog is not open
Description:
  • Open the file-menu
  • Select "Digital signatures..."
  • Verify that the Digital Signatures dialog is open

security_tools.inc:
function hAllowMacroExecution() as boolean

Allow macro execution on Macro Security Warning dialog

Input:
  1. Nothing
Returns:
  1. Errorcondition (boolean)
    • TRUE: Macro dialog is open, successfully clicked "Run"
    • FALSE: Dialog was not opened
Description:
  • Verify that the Macro security Warning is displayed
  • Click "Run" to allow macro execution

security_tools.inc:
function hDenyMacroExecution() as boolean

Deny macro execution on Macro Security Warning dialog

Input:
  1. Nothing
Returns:
  1. Errorcondition (boolean)
    • TRUE: Macro dialog is open, successfully clicked "Deny"
    • FALSE: Dialog was not opened
Description:
  • Verify that the Macro security Warning is displayed
  • Click "Cancel" to deny execution

security_tools.inc:
function hSwitchMacroSecurityTab( cTab as string )

Switch between Security Level and Trusted Paths

Input:
  1. The Tabpage to be activated (string). Valid options are:
    • "SecurityLevel"
    • "TrustedPaths"
Returns:
  1. Nothing
Description:
  • Switch to the given Tabpage

security_tools.inc:
function hAddTrustedPath( cPath as string ) as boolean

Add a directory to the list of trusted paths

Input:
  1. Fully qualified path to the directory (string)
Return:
  1. Errorcondition (boolean)
    • TRUE = Path was successfully added
    • FALSE = Failed to add the path
Description:
  • Open Tools/Options
  • Switch to the Security page
  • Click Macro Security
  • Switch to the Trusted Paths tab
  • Get the number of currently listed items from the list
  • Click the "Add" button
  • Enter a path to some files containing macros
  • Click "Select"
  • Verify that the item has been added to the list
  • Close the dialog
  • Close Tools/Options

security_tools.inc:
function hRemoveTrustedPath( cPath as string ) as boolean

Remove a directory from the list of trusted paths

Input:
  1. Fully qualified path to the directory (string)
Return:
  1. Errorcondition (boolean)
    • TRUE = Path was successfully added
    • FALSE = Failed to add the path
Description:
  • Open Tools/Options
  • Switch to the Security page
  • Click Macro Security
  • Switch to the Trusted Paths tab
  • Get the number of currently listed items from the list
  • Find the entry in the list
  • If it is there, delete it
  • Close the dialog
  • Close Tools/Options

security_tools.inc:
function hSecurityEnterPasswordOnSave( cPassword as string ) as boolean

Enter password when saving a document

This function enters a password into the password dialog if the " Save with password" checkbox is checked. It will automatically generate a faulty password to be entered on first try (to see whether the "Invalid password confirmation" dialog pops up, on second attempt the password is confirmed correctly and thus the document should save ok. The office should return to the document, the File Save dialog should close after save.

Parameter(s):
  1. Password to use (String)
    • Password should contain strange characters and glyphs if possible
Returns:
  1. Errorcondition (Boolean)
    • TRUE if all went well
    • FALSE on any error
Description:
  • Verify that the password dialog is present
  • Enter the password
  • Confirm with incorrect password (e.g. append a number at random)
  • Click on OK
  • There should be a warning about a faulty password confirmation
  • Close messagebox with OK
  • We should now be back on the password dialog
  • Enter the password
  • Confirm with correct password
  • Click on OK
  • Verify that the "File Save" dialog is closed after saving

security_tools.inc:
function hSecurityEnterPasswordOnLoad( cPassword as string, bValid as boolean ) as boolean

Enter a password while loading a document

Enters a valid or invalid password while loading a passworded file

Parameter(s):
  1. Password (String)
    • The password should contain special characters and glyphs
  2. Password validity (Boolean)
    • TRUE: The password is correct, the document should load
    • FALSE: The password is incorrect, the document should not load
Returns:
  1. Errorcondition (Boolean)
    • TRUE if the password protection worked as expected
    • FALSE on any error
Description:
  • Verify that the password dialog exists
  • Enter password, click OK
  • If the password was incorrect:
    • Look for a warning message
    • Close the messagebox
    • Close the Password dialog with "Cancel"
Test/sub/function documentation

signature_tools.inc

Created: Tue Jan 22 13:14:48 2008


signature_tools.inc:
function hSelectXMLSecTab( cTab as string ) as boolean

Switch between tabpages on the Ceritficates/XML-Security Tabpage

Input value(s):
  1. Identifier for the requested tabpage (string). Valid options are:
    • "GENERAL" for the general (first page)
    • "DETAILS" for the details (second page)
    • "PATH" for the certification path (third page)
Return Value:
  1. Nothing
Description:
  • Switch page
  • Set returnvalue
Test/sub/function documentation

spadmin_tools.inc

Created: Tue Jan 22 13:14:48 2008


spadmin_tools.inc:
function hGetPrinterPosition( cName as string, bWarn as boolean ) as integer

Find a printer queue in the SpAdmin list


spadmin_tools.inc:
function hDelPrinter( cPrinterName as string ) as integer

Delete a printer queue by its name in SpAdmin


spadmin_tools.inc:
function hGetSpadminPath() as string

Retrieve the path to the SpAdmin script/binary


spadmin_tools.inc:
function hShutdownOffice() as integer

Shutdown the office by closing all docs and the backing window


spadmin_tools.inc:
function hOpenSpadmin() as boolean

Execute the SpAdmin binary/Script and verify that it is open


spadmin_tools.inc:
function hWaitForSpAdmin() as boolean

Wait for SpAdmin to be loaded and displayed


spadmin_tools.inc:
function hCreateFaxDevice( cName as string ) as boolean

Open the printer creation dialog and create a fax device

  • Click on "New Printer"
  • Click on "Next..."
  • Click on "Next..."
  • Enter "(PHONE)" as queue command
  • Click on "Next..."
  • Enter a Fax-Printer Name
  • Finish the wizard by pressing OK
  • Verify that the Queue has been created in SpAdmin
Test/sub/function documentation

stringtools.inc

Created: Tue Jan 22 13:14:48 2008


stringtools.inc:
function hRemoveLineBreaks( cString as string ) as string

Remove linebreaks and tabs from a string

Used to "beautify" content of messageboxes when printed to the log

Parameter(s):
  1. Content of a messagebox as captured with .getText() (string)
Returns:
  1. A string without tabs, linebreaks and linefeed (string)
Description:
  • Walk through the string, replace linebreaks, tabs etc. with spaces

stringtools.inc:
function hCompareSubStrings( cRef as string, cSub as string ) as integer

Find substring in a reference string

Used to determine that we are on "The first doc!"

Parameter(s):
  1. Term to search for (string)
  2. Term to be searched (string)
Returns:
  1. Errorcode (integer)
    • -1: Invalid parameter(s)
    • 0: Strings do not match
    • 1: Term is exact match
    • 2: Term is a substring
Description:
  • Test function parameters
  • Test if we have a substring
  • Test if we have an exact match

stringtools.inc:
function hGetDirTreeLevel( cFullPath as string ) as integer

Count the numbers of pathseparators in a path-string

Used to find the level of current directory within the directory tree.
The function prints a warning when no pathseparators were found


Parameter(s):
  1. Path (string) with no trailing pathseparator
Returns:
  1. Number of Pathseparators within the string (integer)
    • 0 = failure
    • > 0 = level
Description:
  • Walk through the string
    • Get the next character
    • If it is a separtator, increase the counter
  • Print a warning if no separators were found

stringtools.inc:
function hGetStringFromStaticTextField( oControl as object ) as string

Get the string from a static textfield

Static textfields like those in the document properties dialog are in certain places designed in a way that the string can be selected and copied to the clipboard. This has been introduced with SRC680m212 (9156). This function uses keyboard shortcuts for "Select All" and "Copy" to get the string into the clipboard as .uno.Copy is not enabled.

Parameter(s):
  1. Name of the control (Object)
    • The object must exist in the current context
Returns:
  1. Content of the field (String)
    • Blank if string is empty
Description:
  • Verify that the object exists
  • Get the accelerator for SelectAll and Copy
  • Execute SelectAll and Copy on control
  • Get the string from the clipboard

stringtools.inc:
function hConvertStringToLong( cValue as string ) as long

Convert a stringvalue to long int

The purpose of this function is to isolate the filesize from a string of the type "1.345 Bytes" by removing the thousands-separator and the trailing unit. The result is then a filesize as long integer which then can be compared to the result from the BASIC function FileLen( FileSpec )

Parameter(s):
  1. String containing a long integer value (String)
    • No floating point values allowed
    • Numeric value must be at the beginning of the string (no leading characters/spaces)
    • Negative values are allowed
    • Leading "+" is not allowed
Returns:
  1. Value of the string as long integer (Long)
    • Thousands separator (. or ,) have been removed
    • Decimal separators (though not allowed) have been removed
Description:
  • Walk through the single chars of the string
    • Get the current character
    • Copy valid characters to temporary string, drop invalid, exit on first space or other character
  • Convert string to long integer and return to calling function
Test/sub/function documentation

tabpages.inc

Created: Tue Jan 22 13:14:48 2008


tabpages.inc:
function hDocumentInfoSelectTab( cTabPage as string ) as boolean

Switch between the tabpages in the document info dialog

The declaration of the document info dialog is not complete which enforces special treatment

Parameter(s):
  1. The name of the tabpage to be activated (String)
    • "General"
    • "Description"
    • "User"
    • "Internet"
    • "Statistics"
    • The string is case insensitive
Returns:
  1. Errorcondition (Boolean)
    • TRUE if tabpage is known and switching worked
    • FALSE on icorrect input parameter
    • FALSE on any other error
Description:
  • Kontext to the dialog
  • Select the page to switch to, context to the new page
Test/sub/function documentation

template_tools.inc

Created: Tue Jan 22 13:14:48 2008


template_tools.inc:
function hFindTemplate( sTemplateName as string ) as integer

Find a template by name in FileNewFromTemplate

Starting point: Templates and Documents dialog
Input:
  1. Name of the template to search for (string)
Returns:
  1. Index of the Template in the containing folder (integer)
    • 1 ... n : Index of the template (Position in folder)
    • 0 : No template found by given name
Description:
  • select the templates from the category list
  • run through every item in the list to find the template.
    • Select the (next) folder
    • Retrieve the number of items within the folder
    • For each item in the folder do:
      • Select the (next) item
      • Get the name of the item
      • If this is the item we are searching for, exit
    • Exit the outer loop
    • Click "Up one level"
  • Return the index of the requested template

template_tools.inc:
function hGetRefFilePath( cCategory as string, location as string) as string

Retrieve the location of the reference files for filename comparision

Input:
  1. Category (string)
    • "NEWDOCUMENTS" for New Documents
    • "TEMPLATES" for Templates
    • "SAMPLES" for Samples
  2. Location (string)
    • "TESTTOOL" to use files below gTesttoolPath
    • "LOCAL" to use files below gOfficePath/user/work
Returns:
  1. Fully qualified path to workfile (string)
Description:
  • Retrieve the location
    • For TESTTOOL
      • Prepend path within testtool-environment
      • Build a name containing langcode and .txt suffix
      • Set returnvalue
    • For LOCAL
      • Build a name containing langcode and .txt suffix
      • Set returnvalue

template_tools.inc:
function hSelectCategory( cCategory as string ) as boolean

Select a category from the left pane of the templates dialog

Requires: Templates and Documets dialog must be open
Input: Category (string):
  • NEWDOCUMENTS to select New Documents
  • TEMPLATES to select Templates
  • MYDOCUMENTS to select My Documents
  • SAMPLES to select Samples
Returns: Alwas TRUE, no errorhandling

template_tools.inc:
function hSelectFileFolder( iFolder as integer , bVerbose as boolean ) as integer

Select a folder on the templates dialog's right pane by index

Requires: Templates and Documents dialog must be open
Input:
  1. Index of the folder to be selected on the categories-pane (integer)
    • Must be > 0
  2. Turn printlog on for debugging purpose (boolean)
    • TRUE : Be verbose
    • FALSE : Run silent
Returns:
  1. Number of items in the selected folder (integer)
    • Must be > 0
Description:
  • Select the entry with the given index
  • Retrieve the name of the selected object
  • Press return
  • Get the number of items in the current folder
  • Print a comment to the log if specified
  • Return the number of items

template_tools.inc:
function hGetFileFolderName( iFolder as integer ) as string

Get the name of the currently selected folder on templates dialog

Requires: Templates and Documents dialog must be open
Input: Index of the desired folder
Returns: Name of the selected folder

template_tools.inc:
function hSelectDocumentObject( iTitle as integer , iMode as integer ) as string

Open or edit sample/template from the templates dialog

Requires: Templates and Documents dialog must be open
Input:
  1. Index of the folder to be selected on the categories-pane (integer)
  2. Mode in which to open the template (integer)
    • 0 = Do not open the object, just return its name
    • 1 = Open a new document based on the selected Template
    • 2 = edit the template
Returns:
  • The name of the selected item (string)
Description:
  • Verify function parameter iMode
  • Verify the function parameter iTitle > 0
  • Verify that the index is not too large
  • Get the title of the selected object
  • Count the number of objects in the list
  • Check if the dialog is still open
  • If yes: Try to determine if it is a new folder
  • If the file was successfully opened, handle any dialogs
  • If all initial dialogs were handled correctly, return the title

template_tools.inc:
function hIsTemplateDialogClosed() as boolean

Test whether the Templates and Documents dialog is closed after executing an object

Requires: Templates and Documents dialog must be open
Returns:
  • TRUE if the Templates and Documents dialog cannot be found
  • FALSE if the selected object was a foder (Templates and Documents still open

template_tools.inc:
function hIsObjectAFolder( iObjects as integer ) as boolean

Test whether the "Chapters" folder has been selected

E.g. the Chapters-folder belongs to a master document and must be skipped. To didentify this folder, the number of items is checked (here: 4) which should be unique (all other folders have more items)
Requires: Templates and Documents dialog must be open
Input. Number of objects in the folder (integer)
Returns: TRUE if number of items matches iObjects (boolean)
Description:
  • Compare the objectcount. If different, this is another folder
  • If the number is unchanged, we have an unknown error -> crash

template_tools.inc:
function hDeleteUserTemplates() as integer

Delete all files located in the user templates directory

Uses hDeleteFile tzo remove all files below gOfficePath\user\template
Input: Nothing
Returns: Number of deleted objects
Description:
  • Set the path to the user-templates (default location)
  • Load the list of files into an array
  • Delete each file and print the result to the log
  • Return the number of files that was found in the templates directory
Test/sub/function documentation

toolbar_tools.inc

Created: Tue Jan 22 13:14:48 2008


toolbar_tools.inc:
function hAccessStandardBar() as boolean

Verify that the Standard Bar exists

This function works for all gApplications
Input:
  1. Nothing
Returns:
  1. Errorcondition (boolean)
    • TRUE if StandardBar exists
    • FALSE if standardBar does not exist
Description:
  • Open a new document
  • Try to access the standardbar (query .exists())
  • Close the navigator
  • Close the document

toolbar_tools.inc:
function hResetStandardBar() as boolean

Reset the Standard Bar to default configuration

Input:
  1. Nothing
Returns:
  1. Errorcondition (boolean)
    • Always TRUE as no errorconditions are handled yet
Description:
  • Create a new document
  • Move the mouse on the Standardbar
  • Open the context menu on Standardbar
  • Click on 2. entry (Cutomize Toolbar)
  • Toggle to 'Toolbars' tab page.
  • Press in first section '... Toolbars' the 'toolbar'-button
  • A drop down menu will be opened.
  • Select the first enabled menu entry which should be 'Restore...'
  • Press Yes button on verification dialog.
  • Close 'Toolbars' tab page and the dialog with OK.
  • Close document.

toolbar_tools.inc:
function hStandardbarItemGetCount() as integer

Update test: Get the number of items in the StandardBar

Starting point: Any plain document
Input:
  1. Nothing
Returns:
  1. Number of items on the toolbar (integer)
    • No errorhandling is done. Beware.
Description:
  • Look for additional icons on the standardbar (through extensions)
  • Open the context menu on the Standardbar
  • Select the 1. entry
  • Count all entries ( there must be 30 entries )
  • close the context menu

toolbar_tools.inc:
function hToggleToolbarItem( iMenuPos as integer )

Update test: Toggle an icon on the Standardbar (on/off)

Starting point: Any plain document
Input:
  1. Position of the item in the menu (integer)
Returns:
  1. Nothing
Description:
  • Open the context menu of the standard bar
  • Retrieve the number of items in the menu
  • Take the number of items -3, select the entry
  • Select the provided menu position

toolbar_tools.inc:
function hStandardbarLoadUrl() as boolean

Update test: Access the url-entryfield

Starting point: Any plain document
Input:
  1. Nothing
Returns:
  1. Nothing
Description:
  • Write to URL-Filed (fails: Entryfiled is not visible)
  • add the control to the standardbar
  • verify its existence by entering some text
  • remove the control from the standardbar
  • try to modify non existing object, failure expected

toolbar_tools.inc:
function hStandardbarNewDialog()

Update test: New from Template via StandardBar

Starting point: Plain document
Input:
  1. Nothing
Returns:
  1. Nothing
Description:
  • Click on "New from Template"-button (fails, it is not visible)
  • add the control to the standardbar
  • click the button
  • handle possible dialogs (there should never be one)
  • close the templates and samples dialog
  • finally remove the button from the toolbar

toolbar_tools.inc:
function hStandardbarSaveAs()

Update test: SaveAs button on StandardBar

Starting point: Any plain document
Input:
  1. Nothing
Returns:
  1. Nothing
Description:
  • Click on SaveAs (fails, item is not visible)
  • Add the control to the standardbar
  • Click the button
  • Close the save-as dialog
  • Remove the button from the toolbar
Test/sub/function documentation

treelist_tools.inc

Created: Tue Jan 22 13:14:48 2008


treelist_tools.inc:
function hGetNodeCount( oControl as object ) as integer

Retrieve the number of visible (open) nodes from a treelist

Input:
  1. Treelist control object (Object)
    • Object must exist in current context
Returns:
  1. Number of items in treelist
    • 0 on any error
    • > 0 Number of items
Description:
  • Verify that the control exists
  • Verify that the control is enabled
  • get the number of items from the control

treelist_tools.inc:
function hSelectTopNode( oControl as object ) as boolean

Move selection to the first node in a treelist

  • Type the "Home"-key in a treelist, to select index 1
  • Verify that the top node has been selected

treelist_tools.inc:
function hSelectNextNode( oControl as object ) as integer

Move one node down in a treelist

  • Returns new position or 0 on error

treelist_tools.inc:
function hGetNodeName( oControl as object , iNode as integer ) as string

Retrieve the name of a node in a treelist specified by index

  • Returns the name of the node or empty string on error

treelist_tools.inc:
function hExpandNode( oControl as object, iNode as integer ) as integer

Expand a node in a treelist specified by index

  • Returns new nodecount or 0 on error

treelist_tools.inc:
function hExpandAllNodes( oControl as object ) as integer

Expand all nodes of treelist

  • Run through all items in the treelist, expand every node
  • Returns the number of all nodes in the treelist

treelist_tools.inc:
function hGetVisibleNodeNames( oControl as object , lsList() as string ) as integer

Retrieve the names of all nodes in a treelist

  • Expand all nodes of a treelist
  • Store all node names into an array
  • Return the number of nodes read (listcount), 0 on error

treelist_tools.inc:
function hSelectNode( oControl as object , _id as integer ) as string

Select a node in a treelist by index

  • Return the name of the selected node

treelist_tools.inc:
function hSelectNodeByName( oControl as object , _name as string ) as integer

Select a node by name in treelist (first occurrence)

  • Try to find a node by name - directly
  • If the node is not visible, expand all and search the tree
  • Returns index of requested node or 0 on failure

treelist_tools.inc:
function hSelectTheLastNode( oControl as object ) as integer

Select the (absolute) last node in a treelist

  • Expand all nodes
  • Go to the last node, select it
  • Return the number of the last node in the treelist

treelist_tools.inc:
function hVerifyNodeName( oControl as object , cName as string ) as boolean

Compare the name of the current node from a treelist to a reference string

  • Returns true on success, false on failure

treelist_tools.inc:
function hWaitForTreelist( oTreeList as object, cContext as string, iItemCount as integer ) as boolean

Wait for a treelist to get populated (java related delay)

IMPORTANT: Do not use unless absolutely necessary

Retrieve the number of items from the treelist until a specified number has been reached.


treelist_tools.inc:
function hGetListItems( oControl as object, aList() as string ) as integer

Retrieve the names of all nodes from a plain (linear) list

  • Cycle through a list, append all entries to an array
  • Returns number of items or 0 on error
Test/sub/function documentation

webtools.inc

Created: Tue Jan 22 13:14:48 2008


webtools.inc:
function hSetProxies( HTTP_Server as string, HTTP_Port as string, FTP_Server as string, FTP_Port as string, NoProxyFor as string ) as integer

Configure proxy settings via Tools/Options Internet page

Starting point is a plain document of any type
If all fields are empty The proxy will be set to "None"
Input:
  1. HTTP Server name (string)
    • As name, e.g. myProxy.com (FQDN recommended)
    • As IP, e.g. 192.168.1.254
    • Non optional parameter which may be an empty string
    • Requires HTTP Server port to be set
  2. HTTP Server port
    • e.g. 8080, 3128
    • Non optional parameter which may be an empty string
  3. FTP Server name (string)
    • As name, e.g. myProxy.com (FQDN recommended)
    • As IP, e.g. 192.168.1.254
    • Non optional parameter which may be an empty string
    • Requires FTP Server port to be set
  4. FTP Server port
    • e.g. 8080, 3128
    • Non optional parameter which may be an empty string
  5. Exclude domains (string)
    • e.g. .Sun.COM;.Germany.Sun.Com;MyServer.Sun.Com
    • Non optional parameter which may be an empty string
Returns:
  1. Errorcondition
    • 0 = Successfully set/unset proxies
    • 1 - 5 = Number of failed actions
Description:
  • Open Tools/Options
  • Go to the Proxy Settings (Internet/Proxy)
  • Select Manual Proxy (3. Item in the list)
  • Set the new values
    1. HTTP-Proxy
    2. HTTP-Port
    3. FTP-Proxy
    4. FTP-Port
    5. Exclusion list
  • Close Tools/Options
Test/sub/function documentation

window_tools.inc

Created: Tue Jan 22 13:14:48 2008


window_tools.inc:
function hMaximizeDocument() as boolean

Maximize a document window

Note: The function runs silent (no logs written)

Return Value:
  1. Errorcondition (boolean)
    • TRUE if the window claims to have been maximized
    • FALSE on invalid gApplication (with warning)
    • FALSE if the window thinks it has not been maximized
Description:
  • Maximize the documentwindow depending on gApplication
Test/sub/function documentation

wizards.inc

Created: Tue Jan 22 13:14:48 2008


wizards.inc:
function hOpenWizardWithMenu( cType as string ) as integer

Open a wizard via menu

Starting point: Any plain document
Uses: framework/tools/input/menuentries.txt
Input:
  1. Name of Wizard (string). Known Wizards are:
    • "LETTER"
    • "FAX"
    • "AGENDA"
    • "PRESENTATION"
    • "WEBPAGE"
    • "DOCCONV"
    • "EUROCONV"
    • "ADDRESS"
    • "MAILMERGE"
Returns:
  1. Errorcode (integer)
    • 0: The expected wizard is open
    • 1: No wizard is open
    • 2: The incorrect wizard is open
    • 3: The requested wizard is unknown to this function
Description:
  • find out where in the menustructure the wizards are located
  • Open the 'File' menu
  • if we are in the filemenu the wizards are below a submenu
  • try to click the menuentry where we expect the wizard
  • wait for a wizard to open, iOpen is the number of the menuitem
  • Verify that the correct wizard is open. iOpen should match iMenuPosition

wizards.inc:
function hFinishWizard( iMode as integer ) as boolean

Finish or cancel a wizard

Starting point: Any known wizard must be open
If several wizards are open at the same time the outcome is undefined
Input:
  1. Closing method (integer). Valid options are:
    • 1: Click Finish-Button
    • 2: Click Cancel-Button
    • 3: Use Accelerator for Finish-Button
Returns:
  1. Errorcode (boolean)
    • TRUE: If everything is ok
    • FALSE: On any error (including incorrect function parameters)
Description:
  • Handle possible errors when invoking this function
  • Try to close the wizard
  • Verify that no wizard is open anymore

wizards.inc:
function hGetWizardParams( cType as string, cParam as string ) as integer

Retrieve the location of a wizard in the menu

Uses: framework/tools/input/menuentries.txt
Refer to inline documentation for further information
Input:
  1. Name of Wizard (string). Valid options are:
    • "LETTER"
    • "FAX"
    • "AGENDA"
    • "PRESENTATION"
    • "WEBPAGE"
    • "DOCCONV"
    • "EUROCONV"
    • "ADDRESS"
    • "MAILMERGE"
  2. Menu Position (string). Valid options are:
    • "ID" - This is a unique id for the wizard
    • "MAIN" - Main menu position (e.g. "File"
    • "SUB" - Position below main menu
Returns:
  1. Position of a menu entry (integer)
    • 0: Invalid function parameter
    • 1-n: Position of the item in the menu
Description:
  • Lowercase all function parameters
  • Read in the section containing the waizard parameters
  • Retrieve the requested value from the section

wizards.inc:
function hWaitForWizard() as integer

Wait for any wizard to open

Uses: framework/tools/input/menuentries.txt
NOTE: Not all wizards are known to this function yet.
Input:
  1. Nothing
Returns:
  1. Unique ID of the open wizard
    • 0: In case of any error
    • 1-n: The unique ID of the currently open wizard (integer)
Description:
  • Determine the open wizard by trying wizard.exists()

wizards.inc:
function hSetTemplateSavePath( cFile as string ) as integer

Set the template save-path

Starting point: Last page on FAX-, AGENDA- or LETTERWIZARD
Input:
  1. Fully qualified path to target template name (string)
Returns:
  1. Errorcode (integer)
    • 0: No errors, path has been set correctly
    • 1: The "SaveAs"-dialog did not open
    • 2: The "SaveAs"-button could not be clicked
    • -1: Incorrect call to function
Description:
  • Validate function parameter
  • Click on the save-as button
  • Enter a filename
  • Save the file

wizards.inc:
function hHandleSaveError() as integer

Handle errors while saving a template

Starting point: Save-As dialog from last page on FAX-, AGENDA- or LETTERWIZARD
Input:
  1. Nothing
Returns:
  1. Errorcode (integer)
    • 0: No unexpected dialogs were displayed
    • 1: Unexpected Active closed by clicking YES
    • 2: Unexpected Active closed by clicking OK
Description:
  • Check for unexpected messagebox: file could not be saved
  • Close the dialog either with YES or OK

wizards.inc:
function hClickNextButton() as boolean

Click the Next-Button on some wizards

Starting point: Last page on FAX-, AGENDA- or LETTERWIZARD
Refer to inline documentation for further information
Input:
  1. Nothing
Returns:
  1. Status (boolean)
    • TRUE: Everything is ok
    • FALSE: Any error
Description:
  • Click the "Next"-button
  • Handle the "Document Creation"-dialog (Mailmerge Wizard)