testautomation/framework/tools/includes/template_tools.inc

   1 'encoding UTF-8  Do not remove or change this line!
   2 '**************************************************************************
   3 '* DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
   4 '*
   5 '* Copyright 2008 by Sun Microsystems, Inc.
   6 '*
   7 '* OpenOffice.org - a multi-platform office productivity suite
   8 '*
   9 '* $RCSfile: template_tools.inc,v $
  10 '*
  11 '* $Revision: 1.2 $
  12 '*
  13 '* last change: $Author: vg $ $Date: 2008-08-18 12:06:22 $
  14 '*
  15 '* This file is part of OpenOffice.org.
  16 '*
  17 '* OpenOffice.org is free software: you can redistribute it and/or modify
  18 '* it under the terms of the GNU Lesser General Public License version 3
  19 '* only, as published by the Free Software Foundation.
  20 '*
  21 '* OpenOffice.org is distributed in the hope that it will be useful,
  22 '* but WITHOUT ANY WARRANTY; without even the implied warranty of
  23 '* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  24 '* GNU Lesser General Public License version 3 for more details
  25 '* (a copy is included in the LICENSE file that accompanied this code).
  26 '*
  27 '* You should have received a copy of the GNU Lesser General Public License
  28 '* version 3 along with OpenOffice.org.  If not, see
  29 '* <http://www.openoffice.org/license.html>
  30 '* for a copy of the LGPLv3 License.
  31 '*
  32 '/******************************************************************************
  33 '*
  34 '*  owner : joerg.skottke@sun.com
  35 '*
  36 '*  short description : Helper functions to ease usage of templates
  37 '*
  38 '\******************************************************************************
  39
  40 function hFindTemplate( sTemplateName as string ) as integer
  41
  42     '///<H3>Find a template by name in FileNewFromTemplate</H3>
  43     '///<i>Starting point: Templates and Documents dialog</i><br>
  44     '///<u>Input</u>:
  45     '///<ol>
  46     '///+<li> Name of the template to search for (string)</li>
  47     '///</ol>
  48     '///<u>Returns</u>:
  49     '///<ol>
  50     '///+<li> Index of the Template in the containing folder (integer)</li>
  51     '///<ul>
  52     '///+<li>1 ... n : Index of the template (Position in folder)</li>
  53     '///+<li>0 : No template found by given name</li>
  54     '///</ul>
  55     '///</ol>
  56     '///<u>Description</u>:
  57     '///<ul>
  58     const CFN = "hFindTemplate::"
  59
  60     dim brc as boolean
  61         brc = false
  62     dim irc as integer
  63         irc = 0
  64
  65     dim iObjectFolder as integer
  66     dim iObjectFolders as integer
  67
  68     dim iItemCount as integer
  69     dim iCurrentItem as integer
  70     dim cCurrentItem as string
  71
  72     '///+<li>select the templates from the category list</li>
  73     hSelectCategory( "TEMPLATES" )
  74
  75     '///+<li>run through every item in the list to find the template.</li>
  76     ' NOTE: If the name of the template is not unique, the function will find
  77     '       the first occurrence
  78     ' NOTE: As we do not know the name of "My Templates" (it is localized) we
  79     '       need to search all folders..
  80     iObjectFolders = FileList.getItemCount()
  81
  82     '///<ul>
  83     for iObjectFolder = 1 to iObjectFolders
  84
  85         '///+<li>Select the (next) folder</li>
  86         hSelectFileFolder( iObjectFolder , true )
  87
  88         '///+<li>Retrieve the number of items within the folder</li>
  89         iItemCount = FileList.getItemCount()
  90
  91         '///+<li>For each item in the folder do:</li>
  92         '///<ul>
  93         for iCurrentItem = 1 to iItemCount
  94
  95             '///+<li>Select the (next) item</li>
  96             FileList.select( iCurrentItem )
  97
  98             '///+<li>Get the name of the item</li>
  99             cCurrentItem = FileList.getSelText()
 100
 101             '///+<li>If this is the item we are searching for, exit</li>
 102             if ( cCurrentItem = sTemplateName ) then
 103                 irc = iCurrentItem : if ( irc = 0 ) then irc = 1 ' strange hack
 104                 brc = true
 105                 exit for
 106             endif
 107
 108         next iCurrentItem
 109         '///</ul>
 110
 111         '///+<li>Exit the outer loop</li>
 112         if ( brc ) then
 113             exit for
 114         endif
 115
 116         '///+<li>Click &quot;Up one level&quot;</li>
 117         UpOneLevel.click()
 118
 119     next iObjectFolder
 120     '///</ul>
 121
 122     if ( brc ) then
 123         printlog( CFN & "Template found: " & cCurrentItem )
 124     else
 125         printlog( CFN & "Template could not be found." )
 126     endif
 127
 128     '///+<li>Return the index of the requested template</li>
 129     hFindTemplate() = irc
 130     '///</ul>
 131
 132 end function
 133
 134 '*******************************************************************************
 135
 136 function hGetRefFilePath( cCategory as string, location as string) as string
 137
 138     '///<h3>Retrieve the location of the reference files for filename comparision</h3>
 139     '///<u>Input</u>:
 140     '///<ol>
 141     '///+<li>Category (string)</li>
 142     '///<ul>
 143     '///+<li>&quot;NEWDOCUMENTS&quot; for New Documents</li>
 144     '///+<li>&quot;TEMPLATES&quot; for Templates</li>
 145     '///+<li>&quot;SAMPLES&quot; for Samples</li>
 146     '///</ul>
 147     '///+<li>Location (string)</li>
 148     '///<ul>
 149     '///+<li>&quot;TESTTOOL&quot; to use files below gTesttoolPath</li>
 150     '///+<li>&quot;LOCAL&quot; to use files below gOfficePath/user/work</li>
 151     '///</ul>
 152     '///</ol>
 153     '///<u>Returns</u>:
 154     '///<ol>
 155     '///+<li>Fully qualified path to workfile (string)</li>
 156     '///</ol>
 157
 158     '///<u>Description</u>:
 159     '///<ul>
 160
 161     dim cFile as string
 162
 163     cCategory = ucase( cCategory )
 164
 165     '///+<li>Retrieve the location</li>
 166     '///<ul>
 167     '///+<li>For TESTTOOL</li>
 168     '///<ul>
 169     if ( ucase( location ) = "TESTTOOL" ) then
 170
 171         '///+<li>Prepend path within testtool-environment</li>
 172         cFile = "framework\update\input\templdoc\" & gProductName
 173
 174         '///+<li>Build a name containing langcode and .txt suffix</li>
 175         if ( cCategory = "NEWDOCUMENTS" ) then
 176             cFile = cFile & "\new_" & iSprache & ".txt"
 177         elseif ( cCategory  = "TEMPLATES" ) then
 178             cFile = cFile & "\tem_" & iSprache & ".txt"
 179         elseif ( cCategory = "SAMPLES" ) then
 180             cFile = cFile & "\sam_" & iSprache & ".txt"
 181         else
 182             warnlog( "Invalid category passed to hGetRefFilePath" )
 183         endif
 184
 185         '///+<li>Set returnvalue</li>
 186         hGetRefFilePath() = convertpath( gTesttoolPath & cFile )
 187
 188     '///</ul>
 189     '///+<li>For LOCAL</li>
 190     '///<ul>
 191     elseif ( ucase( location ) = "LOCAL" ) then
 192
 193         '///+<li>Build a name containing langcode and .txt suffix</li>
 194         if ( cCategory = "NEWDOCUMENTS" ) then
 195             cFile = "new_" & iSprache & ".txt"
 196         elseif ( cCategory = "TEMPLATES" ) then
 197             cFile = "tem_" & iSprache & ".txt"
 198         elseif ( cCategory = "SAMPLES" ) then
 199             cFile = "sam_" & iSprache & ".txt"
 200         else
 201             warnlog( "Invalid category passed to hGetRefFilePath" )
 202         endif
 203
 204         '///+<li>Set returnvalue</li>
 205         hGetRefFilePath() = convertpath( hGetWorkPath() & cFile )
 206
 207     end if
 208     '///</ul>
 209     '///</ul>
 210     '///</ul>
 211
 212 end function
 213
 214 '*******************************************************************************
 215
 216 function hSelectCategory( cCategory as string ) as boolean
 217
 218     '///<h3>Select a category from the left pane of the templates dialog</h3>
 219     '///<i>Requires: Templates and Documets dialog must be open</i><br>
 220     '///<u>Input</u>: Category (string):
 221     '///<ul>
 222     '///+<li>NEWDOCUMENTS to select New Documents</li>
 223     '///+<li>TEMPLATES to select Templates</li>
 224     '///+<li>MYDOCUMENTS to select My Documents</li>
 225     '///+<li>SAMPLES to select Samples</li>
 226     '///</ul>
 227     '///<u>Returns</u>: Alwas TRUE, no errorhandling
 228
 229     Kontext "TemplateAndDocuments"
 230     Category.typeKeys( "<HOME>" )
 231     wait( 500 )
 232
 233     if ( UCASE( cCategory ) = "NEWDOCUMENTS" ) then
 234     ' do nothing, the selection should be on this item
 235
 236     elseif ( UCASE( cCategory ) = "TEMPLATES" ) then
 237         Category.typeKeys( "<DOWN>" )
 238
 239     elseif ( UCASE( cCategory ) = "MYDOCUMENTS" ) then
 240         Category.typeKeys( "<DOWN>" )
 241         Category.typeKeys( "<DOWN>" )
 242
 243     elseif ( UCASE( cCategory ) = "SAMPLES" ) then
 244         Category.typeKeys( "<DOWN>" )
 245         Category.typeKeys( "<DOWN>" )
 246         Category.typeKeys( "<DOWN>" )
 247     endif
 248
 249     hSelectCategory() = true
 250
 251 end function
 252
 253 '***************************************************************************
 254
 255 function hSelectFileFolder( iFolder as integer , bVerbose as boolean  ) as integer
 256
 257     '///<h3>Select a folder on the templates dialog's right pane by index</h3>
 258     '///<i>Requires: Templates and Documents dialog must be open</i><br>
 259     '///<u>Input</u>:
 260     '///<ol>
 261     '///+<li>Index of the folder to be selected on the categories-pane (integer)</li>
 262     '///<ul>
 263     '///+<li>Must be > 0</li>
 264     '///</ul>
 265     '///+<li>Turn printlog on for debugging purpose (boolean)</li>
 266     '///<ul>
 267     '///+<li>TRUE : Be verbose</li>
 268     '///+<li>FALSE : Run silent</li>
 269     '///</ul>
 270     '///</ol>
 271     '///<u>Returns</u>:
 272     '///<ol>
 273     '///+<li>Number of items in the selected folder (integer)</li>
 274     '///<ul>
 275     '///+<li>Must be > 0</li>
 276     '///</ul>
 277     '///</ol>
 278
 279     '///<u>Description</u>:
 280     '///<ul>
 281     dim iItems as integer
 282     dim cFolder as string
 283
 284     Kontext "TemplateAndDocuments"
 285
 286     '///+<li>Select the entry with the given index</li>
 287     FileList.select( iFolder )
 288
 289     '///+<li>Retrieve the name of the selected object</li>
 290     cFolder = FileList.getText()
 291
 292     '///+<li>Press return</li>
 293     FileList.typeKeys( "<return>" )
 294     wait( 500 )
 295
 296     '///+<li>Get the number of items in the current folder</li>
 297     iItems = FileList.getItemCount()
 298
 299     '///+<li>Print a comment to the log if specified</li>
 300     if ( bVerbose ) then
 301         printlog( " * " & cFolder & " contains " & iItems & " items." )
 302     endif
 303
 304     '///+<li>Return the number of items</li>
 305     hSelectFileFolder() = iItems
 306     '///</ul>
 307
 308 end function
 309
 310 '*******************************************************************************
 311
 312 function hGetFileFolderName( iFolder as integer ) as string
 313
 314     '///<h3>Get the name of the currently selected folder on templates dialog</h3>
 315     '///<i>Requires: Templates and Documents dialog must be open</i><br>
 316     '///<u>Input</u>: Index of the desired folder<br>
 317     '///<u>Returns</u>: Name of the selected folder
 318
 319     Kontext "TemplateAndDocuments"
 320     FileList.select( iFolder )
 321     WaitSlot()
 322     hGetFileFolderName() = FileList.getText()
 323     WaitSlot()
 324
 325 end function
 326
 327 '*******************************************************************************
 328
 329 function hSelectDocumentObject( iTitle as integer , iMode as integer ) as string
 330
 331     const CFN = "hSelectDocumentObject::"
 332
 333     '///<h3>Open or edit sample/template from the templates dialog</h3>
 334     '///<i>Requires: Templates and Documents dialog must be open</i><br>
 335     '///<u>Input</u>:
 336     '///<ol>
 337     '///+<li>Index of the folder to be selected on the categories-pane (integer)</li>
 338     '///+<li>Mode in which to open the template (integer)</li>
 339     '///<ul>
 340     '///+<li>0 = Do not open the object, just return its name</li>
 341     '///+<li>1 = Open a new document based on the selected Template</li>
 342     '///+<li>2 = edit the template</li>
 343     '///</ul>
 344     '///</ol>
 345     '///<u>Returns</u>:
 346     '///<ul>
 347     '///+<li>The name of the selected item (string)</li>
 348     '///</ul>
 349     '///<u>Description</u>:
 350     '///<ul>
 351     '///+<li>Verify function parameter iMode</li>
 352
 353     if ( ( iMode < 0 ) or ( iMode > 2 ) ) then
 354         warnlog( CFN & "Invalid function parameter iMode: " & iMode )
 355         hSelectDocumentObject() = ""
 356         exit function
 357     endif
 358
 359     dim cTitle as string
 360     dim brc as boolean
 361     dim iObjectCount as integer
 362
 363     Kontext "TemplateAndDocuments"
 364     '///+<li>Verify the function parameter iTitle > 0</li>
 365     if ( iTitle < 1 ) then
 366         warnlog( CFN & "Invalid function parameter iTitle: " & iTitle )
 367         hSelectDocumentObject() = ""
 368         exit function
 369     endif
 370
 371     '///+<li>Verify that the index is not too large</li>
 372     if ( iTitle > FileList.getItemCount() ) then
 373         warnlog( CFN & "Invalid function parameter iTitle: " & iTitle )
 374         hSelectDocumentObject() = ""
 375         exit function
 376     endif
 377
 378     '///+<li>Get the title of the selected object</li>
 379     cTitle = hGetFileFolderName( iTitle )
 380
 381     '///+<li>Count the number of objects in the list</li>
 382     iObjectCount = FileList.getItemCount()
 383     printlog( CFN & "Title: " & cTitle )
 384
 385     select case iMode
 386     case 0 ' do not load the document, return the title and exit the function
 387         hSelectDocumentObject() = cTitle
 388         exit function
 389     case 1 ' open new document based on the template
 390         WaitSlot()
 391         kontext "TemplateAndDocuments"
 392         FileList.typeKeys( "<return>" )
 393         WaitSlot( 5000 )
 394
 395         try
 396             kontext "TemplateAndDocuments"
 397             if ( TemplateAndDocuments.exists() ) then
 398                 '///+<li>If yes: Try to determine if it is a new folder</li>
 399                 brc = hIsObjectAFolder( iObjectCount )
 400
 401                 if ( brc ) then
 402                     hSelectDocumentObject() = "Folder"
 403                     exit function
 404                 endif
 405
 406             endif
 407         catch
 408         endcatch
 409
 410         hFileWait()
 411         hHandleActivesOnLoad( 2, false )
 412         hHandleInitialDialogs()
 413
 414     end select
 415
 416
 417     '///+<li>If all initial dialogs were handled correctly, return the title</li>
 418     if ( brc ) then
 419         hSelectDocumentObject() = cTitle
 420     else
 421         hSelectDocumentObject() = ""
 422     endif
 423     '///</ul>
 424
 425 end function
 426
 427 '*******************************************************************************
 428
 429 function hIsTemplateDialogClosed() as boolean
 430
 431     const CFN = "hIsTemplateDialogClosed::"
 432     '///<h3>Test whether the Templates and Documents dialog is closed after executing an object</h3>
 433     '///<i>Requires: Templates and Documents dialog must be open</i><br>
 434     '///<u>Returns</u>:
 435     '///<ul>
 436     '///+<li>TRUE if the Templates and Documents dialog cannot be found</li>
 437     '///+<li>FALSE if the selected object was a foder (Templates and Documents still open</li>
 438     '///</ul>
 439
 440     dim iTry as integer : iTry = 0
 441
 442
 443     if ( WaitSlot( 2000 ) = WSFinished ) then
 444         kontext "TemplateAndDocuments"
 445         try
 446             if ( TemplateAndDocuments.exists() ) then
 447                 printlog( CFN & "Dialog still open. Maybe we opened a folder" )
 448                 hIsTemplateDialogClosed() = false
 449                 exit function
 450             else
 451                 printlog( CFN & "Regular object. Dialog is closed" )
 452                 hIsTemplateDialogClosed() = true
 453                 exit function
 454             endif
 455         catch
 456             warnlog( "Failure to query Templates and Documents dialog" )
 457             hIsTemplateDialogClosed() = true
 458         endcatch
 459     else
 460         warnlog( "Slot not finished within 2000 msec" )
 461         hIsTemplateDialogClosed() = true
 462     endif
 463
 464 end function
 465
 466 '*******************************************************************************
 467
 468 function hIsObjectAFolder( iObjects as integer ) as boolean
 469
 470     '///<h3>Test whether the &quot;Chapters&quot; folder has been selected</h3>
 471     '///<i>E.g. the Chapters-folder belongs to a master document and must be skipped.
 472     '///+ To didentify this folder, the number of items is checked (here: 4) which
 473     '///+ should be unique (all other folders have more items)</i><br>
 474     '///<i>Requires: Templates and Documents dialog must be open</i><br>
 475     '///<u>Input</u>. Number of objects in the folder (integer)<br>
 476     '///<u>Returns</u>: TRUE if number of items matches iObjects (boolean)<br>
 477     '///<u>Description</u>:
 478     '///<ul>
 479
 480     ' NOTE: This function should only handle one folder called "Chapters"
 481     '       below "Text Documents". We do not want to load the chapters
 482     '       separately, they are a part of a Master-Document and will be
 483     '       loaded at another time.
 484     '       To find out whether we are in a new folder or not, the number
 485     '       of objects in the parent folder is compared to the number in the
 486     '       current. This is a hack with a good probability to work.
 487
 488     const CFN = "hIsObjectAFolder::"
 489     dim iCurrentObjects as integer
 490
 491     if ( iObjects < 1 ) then
 492         warnlog( CFN & "Invalid Objectcount passed to function: " & iObjects )
 493         warnlog( CFN & "Defaulting to 1 -> outcome is undefined" )
 494         iObjects = 1
 495     endif
 496
 497     kontext "TemplateAndDocuments"
 498     '///+<li>Compare the objectcount. If different, this is another folder</li>
 499     '///+<li>If the number is unchanged, we have an unknown error -> crash</li>
 500     iCurrentObjects = Filelist.getItemCount()
 501
 502     if ( iCurrentObjects <> iObjects ) then
 503         printlog( CFN & "Object appears to be a folder with " & iCurrentObjects & " items" )
 504         hIsObjectAFolder() = true
 505     else
 506         warnlog( CFN & "Unknown error: Objectcount is unchanged" )
 507         hIsObjectAFolder() = false
 508     endif
 509
 510     '///</ul>
 511
 512 end function
 513
 514 '*******************************************************************************
 515
 516 function hDeleteUserTemplates() as integer
 517
 518     ' Recommendation: Use outside of testcase
 519
 520     '///<h3>Delete all files located in the user templates directory</h3>
 521     '///<i>Uses hDeleteFile tzo remove all files below gOfficePath\user\template</i><br>
 522     '///<u>Input</u>: Nothing<br>
 523     '///<u>Returns</u>: Number of deleted objects<br>
 524     '///<u>Description</u>:
 525     '///<ul>
 526
 527     const CFN = "hDeleteUserTemplates::"
 528
 529     dim iFileCount as integer
 530     dim aFileList( 200 ) as string
 531     dim sPath as string
 532     dim iCounter as integer
 533
 534     '///+<li>Set the path to the user-templates (default location)</li>
 535     sPath = convertpath( gOfficePath & "user\template" )
 536
 537     '///+<li>Load the list of files into an array</li>
 538     iFileCount = GetFileList( sPath, "*.*", aFileList() )
 539     printlog( CFN & "Found " & iFileCount & " file(s)." )
 540
 541     '///+<li>Delete each file and print the result to the log</li>
 542     for iCounter = 1 to iFileCount
 543
 544         hDeleteFile( aFileList( iCounter ) )
 545
 546     next iCounter
 547
 548     '///+<li>Return the number of files that was found in the templates directory</li>
 549     hDeleteUserTemplates() = iFileCount
 550
 551     '///</ul>
 552
 553 end function