testautomation/framework/tools/includes/help_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: help_tools.inc,v $
  10 '*
  11 '* $Revision: 1.1 $
  12 '*
  13 '* last change: $Author: jsi $ $Date: 2008-06-16 12:19:06 $
  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 : Replacements for routines in t_lists.inc adds some
  37 '*
  38 '\******************************************************************************
  39
  40 function hOpenHelp() as boolean
  41
  42     '///<h3>Function to open the Help Browser</h3>
  43     '///<u>Input</u>:
  44     '///<ol>
  45     '///+<li>Nothing</li>
  46     '///</ol>
  47
  48     '///<u>Returns</u>:
  49     '///<ol>
  50     '///+<li>Errorcondition (boolean)</li>
  51     '///<ul>
  52     '///+<li>TRUE if the help is open</li>
  53     '///+<li>FALSE if the help did not open</li>
  54     '///</ul>
  55     '///</ol>
  56
  57     '///<u>Description</u>:
  58     '///<ul>
  59     const CFN = "hOpenHelp::"
  60
  61     dim iTry as integer
  62     dim brc as boolean
  63         brc = false
  64
  65     printlog( CFN & "Enter" )
  66
  67     '///+<li>Open the help Browser using the slot</li>
  68     try
  69         HelpContents
  70     catch
  71         printlog( CFN & "Failed to open help, slot failed" )
  72         hOpenHelp() = false
  73         exit function
  74     endcatch
  75
  76     '///+<li>Verify that the help is indeed open (max 10 sec.)</li>
  77     Kontext "StarOfficeHelp"
  78     for iTry = 1 to 10
  79
  80         if ( StarOfficeHelp.exists() ) then
  81             brc = true
  82             exit for
  83         endif
  84
  85         sleep( 1 )
  86
  87     next iTry
  88
  89     '///+<li>Print a status to the log, return TRUE or FALSE</li>
  90     if ( brc ) then
  91         printlog( CFN & "Exit: Help is open" )
  92     else
  93         printlog( CFN & "Exit: Help is not open" )
  94         kontext "Active"
  95         if ( Active.exists( 2 ) ) then
  96             printlog( "Msgbox: " & Active.getText()
  97             Active.ok()
  98         endif
  99     endif
 100
 101     '///</ul>
 102     hOpenHelp() = brc
 103
 104 end function
 105
 106 '*******************************************************************************
 107
 108 function hCloseHelp() as boolean
 109
 110     '///<h3>Function to close the Help Browser</h3>
 111     '///<u>Input</u>:
 112     '///<ol>
 113     '///+<li>Nothing</li>
 114     '///</ol>
 115
 116     '///<u>Returns</u>:
 117     '///<ol>
 118     '///+<li>Errorcondition (boolean)</li>
 119     '///<ul>
 120     '///+<li>TRUE if the help is closed</li>
 121     '///+<li>FALSE if the help did not close</li>
 122     '///</ul>
 123     '///</ol>
 124
 125     '///<u>Description</u>:
 126     '///<ul>
 127     const CFN = "hCloseHelp::"
 128     dim brc as boolean
 129
 130     printlog( CFN & "Enter" )
 131
 132     '///+<li>Verify that the Help Browser is Open</li>
 133     kontext "StarOfficeHelp"
 134     if ( not StarOfficeHelp.exists() ) then
 135         printlog( CFN & "Help is not open" )
 136         hCloseHelp() = false
 137         exit function
 138     endif
 139
 140     '///+<li>Close the Help Browser by typing CTRL+F4</li>
 141     StarOfficeHelp.typeKeys( "<MOD1 F4>" )
 142
 143     '///+<li>Verify that the Help Browser is not open (anymore)</li>
 144     kontext "StarOfficeHelp"
 145     if ( StarOfficeHelp.exists() ) then
 146         printlog( CFN & "Exit: Help is still open" )
 147         brc = false
 148     else
 149         printlog( CFN & "Exit: Help has been closed" )
 150         brc = true
 151     endif
 152
 153     '///+<li>Return TRUE or FALSE</li>
 154     '///</ul>
 155     hCloseHelp() = brc
 156
 157 end function
 158
 159 '******************************************************************************
 160
 161 function hSelectHelpTab( cTab as string ) as boolean
 162
 163     '///<h3>Select a tab on the help dialog by name</h3>
 164     '///<u>Input</u>:
 165     '///<ol>
 166     '///+<li>The tab to open (string)</li>
 167     '///<ul>
 168     '///+<li>&quot;content&quot; for the contents tab</li>
 169     '///+<li>&quot;index&quot; for the index tab</li>
 170     '///+<li>&quot;find&quot; for the find tab</li>
 171     '///+<li>&quot;bookmarks&quot; for the bookmarks tab</li>
 172     '///</ul>
 173     '///</ol>
 174
 175     '///<u>Returns</u>:
 176     '///<ol>
 177     '///+<li>Errorcondition (boolean)</li>
 178     '///<ul>
 179     '///+<li>TRUE if the requested tabpage is open</li>
 180     '///+<li>FALSE if the requested tabpage did not open</li>
 181     '///</ul>
 182     '///</ol>
 183
 184     '///<u>Description</u>:
 185     '///<ul>
 186     const CFN = "hSelectHelpTab::"
 187
 188     dim brc as boolean
 189         brc = false
 190
 191     dim cTabName as string
 192         cTabName = lcase( cTab )
 193
 194     kontext "StarOfficeHelp"
 195
 196     printlog( CFN & "Enter" )
 197
 198     '///+<li>Select the requested Tabpage, verify that it is open</li>
 199     select case cTabName
 200     case "content"       : TabControl.setPage( ContentPage )
 201                            if ( SearchContent.isVisible() ) then
 202                                brc = true
 203                            endif
 204     case "index"         : TabControl.setPage( IndexPage )
 205                            if ( SearchIndex.isVisible() ) then
 206                                brc = true
 207                            endif
 208     case "find"          : TabControl.setPage( FindPage )
 209                            if ( SearchFind.isVisible() ) then
 210                                brc = true
 211                            endif
 212     case "bookmarks"     : TabControl.setPage( BookmarksPage )
 213                            if ( Bookmarks.isVisible() ) then
 214                                brc = true
 215                            endif
 216     case else
 217         printlog( CFN & "Invalid parameter passed to function: " & cTab )
 218         printlog( CFN & "Valid are: content, index, find, bookmarks" )
 219         brc = false
 220     end select
 221
 222     '///+<li>Print a comment to the log</li>
 223     if ( brc ) then
 224         printlog( CFN & "Exit: Selected Tabpage: " & cTab )
 225     endif
 226
 227     '///+<li>Return TRUE or FALSE</li>
 228     hSelectHelpTab() = brc
 229
 230     '///</ul>
 231 end function
 232
 233 '*******************************************************************************
 234
 235 function hUseBookmarksContextMenu( cAction as string ) as boolean
 236
 237     '///<h3>handle the bookmarks context menu in Help Browser</h3>
 238     '///<u>Input</u>:
 239     '///<ol>
 240     '///+<li>The context item to execute (string)</li>
 241     '///<ul>
 242     '///+<li>&quot;show&quot;</li>
 243     '///+<li>&quot;rename&quot;</li>
 244     '///+<li>&quot;delete&quot;</li>
 245     '///</ul>
 246     '///</ol>
 247
 248     '///<u>Returns</u>:
 249     '///<ol>
 250     '///+<li>Errorcondition (boolean)</li>
 251     '///<ul>
 252     '///+<li>TRUE on success</li>
 253     '///+<li>FALSE on any other error</li>
 254     '///</ul>
 255     '///</ol>
 256
 257     '///<u>Description</u>:
 258     '///<ul>
 259     const CFN = "hUseBookmarksContextMenu::"
 260     dim cSelection as string
 261     dim iActionPos as integer
 262
 263     printlog( CFN & "Enter" )
 264
 265     '///+<li>Verify that we are on the Bookmarks Page</li>
 266     Kontext "BookmarksPage"
 267     if ( not BookmarksPage.exists() ) then
 268         printlog( CFN & "BookmarksPage is not open" )
 269         hUseBookmarksContextMenu() = false
 270         exit function
 271     endif
 272
 273     '///+<li>Find the index of the requested entry</li>
 274     cSelection = lcase( cAction )
 275     select case cSelection
 276     case "show"       : iActionPos = 1
 277     case "rename"     : iActionPos = 2
 278     case "delete"     : iActionPos = 3
 279     case else         : iActionPos = 0
 280     end select
 281
 282     '///+<li>If action is unsuported, return false and exit the function</li>
 283     if ( iActionPos = 0 ) then
 284         printlog( CFN & "Invalid action passed to function" )
 285         hUseBookmarksContextMenu() = false
 286         exit function
 287     endif
 288
 289     '///+<li>Open the context menu and select the requested index</li>
 290     kontext "Bookmarks"
 291     Bookmarks.openContextMenu()
 292     printlog( CFN & "Exit: Opening item: " & MenuGetItemText( iActionPos ) )
 293     MenuSelect( iActionPos )
 294
 295     '///+<li>Return TRUE if all went well so far</li>
 296     hUseBookmarksContextMenu() = true
 297
 298     '///</ul>
 299
 300 end function
 301
 302 '*******************************************************************************
 303
 304 function hHelpGetAboutItemCount() as integer
 305
 306     '///<h3>Get the number of applications listed in the Help ListBox</h3>
 307
 308     '///<u>Input</u>:
 309     '///<ol>
 310     '///+<li>Nothing</li>
 311     '///</ol>
 312
 313     '///<u>Returns</u>:
 314     '///<ol>
 315     '///+<li>Number of applications listed (integer)</li>
 316     '///<ul>
 317     '///+<li>The default is 7</li>
 318     '///</ul>
 319     '///</ol
 320
 321     '///<u>Description</u>:
 322     '///<ul>
 323
 324     const I_ABOUT_ITEMS = 8
 325     const CFN = "hHelpGetAboutItemCount::"
 326
 327     dim iItem as integer
 328     dim cItemName as string
 329     dim iAboutItems as integer
 330     dim brc as boolean
 331
 332     printlog( CFN & "Enter" )
 333
 334     '///+<li>Open Help</li>
 335     brc = hOpenHelp()
 336     if ( not brc ) then
 337         qaerrorlog( CFN & "Help not open, aborting" )
 338         hHelpGetAboutItemCount() = 0
 339         exit function
 340     endif
 341
 342     hSelectHelpTab( "index" )
 343     Kontext "IndexPage"
 344
 345     '///+<li>get the number of applications from the drop down box</li>
 346     iAboutItems = HelpAbout.getItemCount()
 347     if ( iAboutItems <> I_ABOUT_ITEMS ) then
 348         warnlog( "The list of topics is incomplete:" )
 349     endif
 350
 351     '///+<li>Print the list of items to the log</li>
 352     printlog( CFN & "Items listed in Application Listbox (HelpAbout)" )
 353     for iItem = 1 to iAboutItems
 354         cItemName = HelpAbout.getItemText( iItem )
 355         printlog( "     " & cItemName )
 356     next iItem
 357
 358     '///+<li>close help</li>
 359     hCloseHelp()
 360     '///</ul>
 361
 362     printlog( CFN & "Exit with item count = " & iAboutItems )
 363     hHelpGetAboutItemCount() = iAboutItems
 364
 365 end function
 366
 367 '*******************************************************************************
 368
 369 function hHelpGetSearchIndexItemCount() as integer
 370
 371     '///<h3>Get the number of items in the Help Search Index</h3>
 372     '///<i>Starting point: Help / Index page</i><br>
 373     '///<i>Note: Workaround for incorrect value returned by .getItemCount()</i><br>
 374
 375     '///<u>Input</u>:
 376     '///<ol>
 377     '///+<li>Nothing</li>
 378     '///</ol>
 379
 380     '///<u>Returns</u>:
 381     '///<ol>
 382     '///+<li>Number of items in the list (integer)</li>
 383     '///</ol>
 384
 385     '///<u>Description</u>:
 386     '///<ul>
 387
 388     const CFN = "hHelpGetSearchIndexItemCount:"
 389
 390     dim iItem as integer
 391     printlog( CFN & "Enter" )
 392
 393     '///+<li>Run through the list and count the items, break on error</li>
 394     for iItem = 1 to 10000
 395
 396         try
 397             SearchIndex.select( iItem )
 398         catch
 399             iItem = iItem - 1
 400             exit for
 401         endcatch
 402
 403     next iItem
 404
 405     printlog( CFN & "Exit with item count = " & iItem )
 406     hHelpGetSearchIndexItemCount() = iItem
 407     '///</ul>
 408
 409 end function
 410
 411 '*******************************************************************************
 412
 413 function hGetHelpContentHeader( iLength as integer ) as string
 414
 415
 416     '///<h3>Get the header of the content in the help browser</h3>
 417     '///<i>This is the first line of the content page, truncated (if desired)</i><br><br>
 418
 419     '///<u>Parameter(s):</u><br>
 420     '///<ol>
 421     '///+<li>Length of the requested string (Integer)</li>
 422     '///<ul>
 423     '///+<li>The max length of the string to be returned</li>
 424     '///+<li>&le; 0 = do not truncate</li>
 425     '///</ul>
 426     '///</ol>
 427
 428
 429     '///<u>Returns:</u><br>
 430     '///<ol>
 431     '///+<li>Header (String)</li>
 432     '///<ul>
 433     '///+<li>A string containing the content header</li>
 434     '///+<li>The header is the first line of the content page</li>
 435     '///</ul>
 436     '///</ol>
 437
 438     const CFN = "hGetHelpContentHeader::"
 439     printlog( CFN & "Enter with option (iLength): " & iLength )
 440     dim cHeaderString as string
 441
 442     '///<u>Description:</u>
 443     '///<ul>
 444     '///+<li>Maximize the help viewer (required to avoid cut off strings)</li>
 445     kontext "HelpContent"
 446     'StarOfficeHelp.maximize()
 447
 448     '///+<li>Go to the top left position in the help browser</li>
 449     HelpContent.typeKeys( "<MOD1 HOME>" )
 450
 451     '///+<li>Mark the entire line - note that this ends at the linebreak</li>
 452     HelpContent.typeKeys( "<SHIFT END>" )
 453
 454     '///+<li>Copy the string to the clipboard</li>
 455     EditCopy
 456
 457     '///+<li>Assign the string to a variable</li>
 458     cHeaderString = getClipboardText
 459
 460     '///+<li>Truncate string</li>
 461     if ( iLength > 0 ) then
 462         if ( len( cHeaderString ) > iLength ) then
 463             cHeaderString = left( cHeaderString, iLength )
 464         endif
 465     endif
 466     '///</ul>
 467
 468     printlog( CFN & "Exit: " & cHeaderString )
 469     hGetHelpContentHeader() = cHeaderString
 470
 471 end function