Class: HTMLDocumentView

• Inheritance
• Description
• Class protocol
  • defaults
  • startup
  • startup-basic
• Instance protocol
  • accessing
  • button actions
  • change & update
  • defaults
  • focus control
  • initialization & release
• Examples

Inheritance:

   Object
   |
   +--GraphicsMedium
      |
      +--DisplaySurface
         |
         +--SimpleView
            |
            +--View
               |
               +--HTMLDocumentFrame
                  |
                  +--HTMLDocumentView

Package:

stx:libhtml

Category:

System-Documentation

Version:

rev: 1.240 date: 2023/11/11 15:28:08

user: stefan

file: HTMLDocumentView.st directory: libhtml

module: stx stc-classLibrary: libhtml

Description:

displays HTML documents.

Can be used as a widget or 
(using startup-protocol found in the class protocol) as a topView.

Please read the documentation in HTMLDocumentPainter for its limitations.

If you want to include an html-view in your UI application,
and want embedded anchor links which call back into your application,
use the following scheme:
    1) set the htmlVIew's linkActionPerformer (in your postBuild:-method)
    2) generate anchors of the form:
        <A action='doIt: linkActionPerformer doSomething'>
or, alternatively, create anchors of the form:
        <A action='doIt: self application doSomething'>

DO NOT add private protocol to this class or the superclass (as was done with quickFix)

copyright
COPYRIGHT (c) 1995 by Claus Gittinger
             All Rights Reserved

This software is furnished under a license and may be used
only in accordance with the terms of that license and with the
inclusion of the above copyright notice.   This software may not
be provided or otherwise made available to, or used by, any
other person.  No title to or ownership of the software is
hereby transferred.

Class protocol:

 defaultIcon

return the browsers default window icon

 fullButtonSpec

('hardcopy' #menu_printPage )

 helpFileFor: helpFilePath

given a relataive path in the helpFile hierarchy,
find the file's absolute path - first trying the current language,
if not found, try an english version

 helpViewButtonSpec

 open

open a documentView on the ST/X top page.
Returns the htmlView.

Usage example(s):

self open

 openDocumentation: aFilename

 openFull

open a full documentation view on the top documentation page.
Returns the htmlView.
The actual page displayed depends on the language setting;
i.e. it is 'doc/online/<language>/TOP.html'.

Usage example(s):

self openFull

Usage example(s):

Language := #de. self openFull

Usage example(s):

Language := #en. self openFull

 openFullOnDocumentationFile: relativePath

open a full documentation view on a file, given its relative
path in the documentation hierachy.
The actual page displayed depends on the language setting;
i.e. it is 'doc/online/<language>/relativePath'.
If the file is not found, a warnBox is shown and nil is returned;
otherwise, the htmlView is returned.

Usage example(s):

self openFullOnDocumentationFile:'TOP.html' self openFullOnDocumentationFile:'programming/TOP.html' self openFullOnDocumentationFile:'tools/uipainter/TOP.html#ADDINGMENUBAR' self openFullOnDocumentationFile:'foobar'

Usage example(s):

Language := #de. self openFullOnDocumentationFile:'TOP.html'

Usage example(s):

Language := #en. self openFullOnDocumentationFile:'TOP.html'

 openFullOnDocumentationFile: relativePath searchIn: pathesOrNil

open a full documentation view on a file, given its relative
path in the documentation hierachy.
UserPreferences >> useSmalltalkDocumentViewer controls if the
document is shown by the internal HTML viewer, or a real browser.
The actual page displayed depends on the language setting;
i.e. it is 'doc/online/<language>/relativePath'.
If the file is not found, a warnBox is shown and nil is returned;
otherwise, the htmlView is returned.

Usage example(s):

UserPreferences current useSmalltalkDocumentViewer:true. self openFullOnDocumentationFile:'programming/TOP.html'. UserPreferences current useSmalltalkDocumentViewer:false. self openFullOnDocumentationFile:'programming/TOP.html'. UserPreferences current useSmalltalkDocumentViewer:nil. self openFullOnDocumentationFile:'programming/TOP.html'

Usage example(s):

self openFullOnDocumentationFile:'TOP.html' self openFullOnDocumentationFile:'programming/TOP.html' self openFullOnDocumentationFile:'tools/uipainter/TOP.html#ADDINGMENUBAR' self openFullOnDocumentationFile:'foobar'

Usage example(s):

Language := #de. self openFullOnDocumentationFile:'TOP.html'

Usage example(s):

Language := #en. self openFullOnDocumentationFile:'TOP.html'

 openFullOnFile: aDocumentName

open a full documentation view on a file, given its pathName.
Returns the htmlView.

Usage example(s):

self openFullOnFile:'../../doc/online/english/TOP.html' self openFullOnFile:'http://localhost:8001/' self openFullOnFile:nil self openFullOnFile:'http://www.exept.de'

 openFullOnFile: aDocumentName extent: extent title: title

open a full documentation view with extent and title,
on a file, given its pathName. Returns the htmlView.
Add a standard button panel.

 openFullOnFile: aDocumentName extent: extent title: title uriDisplay: uriDisplay infoDisplay: infoDisplay

open a full documentation view with extent and title,
on a file, given its pathName. Returns the htmlView.
Add a standard button panel.

 openFullOnFile: aDocumentName text: htmlText top: topDirectory extent: extent title: title buttonSpec: buttonSpec info: info

open a full documentation view with extent and title,
on a file, given its pathName. Returns the htmlView.
The buttonSpec argument specifies which buttons should be added to
the panel - for a help viewer, only a subset of the complete set
is usually passed.

 openFullOnFile: aDocumentName text: htmlText top: topDirectory extent: extent title: title buttonSpec: buttonSpec uriDisplay: showUri infoDisplay: showInfo

open a full documentation view with extent and title,
on a file, given its pathName. Returns the htmlView.
The buttonSpec argument specifies which buttons should be added to
the panel - for a help viewer, only a subset of the complete set
is usually passed.

 openFullOnHelpFile: relativePath

open a full documentationView as helpView (not all buttons are
present) on relativePath, which is the path relative to the
doc/online/help directory. If aRelativePath ends in '.html',
that filename is taken; otherwise, it is interpreted as a directory
name and a file named 'TOP.html' is tried there.
If the file does not exist, a warnBox is shown and nil is returned;
otherwise, the htmlView is returned.

Usage example(s):

self openFullOnHelpFile:'Launcher/compilerSettings.html'

Usage example(s):

Language := #de. self openFullOnHelpFile:'Launcher/compilerSettings.html'

Usage example(s):

Language := #en. self openFullOnHelpFile:'Launcher/compilerSettings.html'

 openFullOnText: htmlText

open a full documentation view on some html-text.
Returns the htmlView.

Usage example(s):

self openFullOnText:' chapter 1 sub chapter 1.1 chapter 2 sub chapter 2.1 sub chapter 2.2 sub chapter 2.3 '

 openFullOnText: htmlText inDirectory: topDirectory

open a full documentation view on some html-text.
For file-HREFS, use aTopDirectory as starting point.
Returns the htmlView.

Usage example(s):

self openFullOnText:' chapter 1 sub chapter 1.1 chapter 2 sub chapter 2.1 sub chapter 2.2 sub chapter 2.3 '

 openFullOnText: htmlText top: topDirectory extent: extent title: title

open a full documentation view with extent and title,
on a file, given its pathName. Returns the htmlView.
Add a standard button panel.

 openFullOnURL: anURL

open a full documentation view on an url, given its pathName.
Returns the htmlView.

Usage example(s):

self openFullOnURL:'http://www.exept.de' self openFullOnURL:'http://localhost:8080/' self openFullOnURL:'http://localhost:80/' self openFullOnURL:'http://wvnvaxa.wvnet.edu/vmswww/bmp.html' self openFullOnURL:'http://www.w3.org/Graphics/PNG/inline-alpha.html' self openFullOnURL:'http://www.schaik.com/pngsuite/pngsuite_bas_png.html' self openFullOnURL:'http://www.schaik.com/pngsuite/pngsuite_trn_png.html' self openFullOnURL:'http://www.schaik.com/pngsuite/pngsuite.html'

 openOn: aDocumentName

open a full sized documentationView on aDocumentName.
Return the htmlView.

Usage example(s):

self openOn:'../../doc/online/english/TOP.html' self openOn:'http://pxd.me/dompdf/www/test/image_bmp.html'

 openOnFile: aDocumentName

open a small documentationView on aDocumentName.
Return the htmlView.

Usage example(s):

self openOnFile:'../../doc/online/english/TOP.html'

 openOnText: aString

open a small documentationView on some html-text.
Return the htmlView.

Usage example(s):

HTMLDocumentView openOnText:' Hello world ' HTMLDocumentView openFullOnText:' Hello world '

 pathOfDocumentationFile: relativePath searchIn: pathesOrNil

given a relative path in the documentation hierachy
(i.e. xxx in 'stx/doc/online/english/xxx'),
return either the full path of a documentation file,
or nil if it does not exist.
The actual path depends on the language setting;
i.e. it is 'doc/online/<language>/relativePath'.
If the file is not found in the language, english is tried as fallback.

Usage example(s):

self pathOfDocumentationFile:'TOP.html' searchIn:nil self pathOfDocumentationFile:'programming/TOP.html' searchIn:nil self pathOfDocumentationFile:'tools/uipainter/TOP.html#ADDINGMENUBAR' searchIn:nil self pathOfDocumentationFile:'foobar' searchIn:nil

Usage example(s):

Language := #de. self pathOfDocumentationFile:'TOP.html' searchIn:nil

Usage example(s):

Language := #en. self pathOfDocumentationFile:'TOP.html' searchIn:nil

 new_openFullOnFile: aFilenameOrString anchor: localAnchor text: htmlText top: topDirectory extent: extent title: title buttonSpec: buttonSpec uriDisplay: showUri infoDisplay: showInfo

open a full documentation view with extent and title,
on a file, given its pathName. Returns the htmlView.
The buttonSpec argument specifies which buttons should be added to
the panel - for a help viewer, only a subset of the complete set
is usually passed.

 old_openFullOnFile: aFilenameOrString anchor: localAnchor text: htmlText top: topDirectory extent: extent title: title buttonSpec: buttonSpec uriDisplay: showUri infoDisplay: showInfo

open a full documentation view with extent and title,
on a file, given its pathName. Returns the htmlView.
The buttonSpec argument specifies which buttons should be added to
the panel - for a help viewer, only a subset of the complete set
is usually passed.

 openFullOnFile: aFilenameOrString anchor: localAnchor text: htmlText top: topDirectory extent: extent title: title buttonSpec: buttonSpec uriDisplay: showUri infoDisplay: showInfo

backward compatibility entry

Instance protocol:

 heightOfContentsDependsOnWidth

yes, I rearrange the text depending on the width,
and therefore, it is a bad idea to hide/show scrollbars dynamically

 helpDocumentPath: aPathNameString

allow change of the document which is displayed by the
views help button

 linkButtonPanel: aView

 scrollWhenUpdating

return the scroll behavior, when I get a new text
via the model.
Possible returnValues are:
#keep / nil -> no change
#endOfText -> scroll to the end
#beginOfText -> scroll to the top
The default is #beginOfText.
This is useful for synchronized text+htmlText,
where new text comes from editing

 scrollWhenUpdating: aSymbolOrNil

define how to scroll, when I get a new text
via the model.
Allowed arguments are:
#keep / nil -> no change
#endOfText -> scroll to the end
#beginOfText -> scroll to the top
The default is #beginOfText.
This is useful for synchronized text+htmlText,
where new text comes from editing

 currentDocumentSource

 fileBrowserOnPageSource

open a file browser on the html file.
But only iff the text being shown comes from a file

 fileNameOfPageSource

return the filename of the html file.
But only iff the text being shown comes from a file;
otherwise return nil

 menu_back

 menu_help

 menu_home

 menu_print

 menu_printPage

postscript

 menu_quit

 menu_reload

self sensor ctrlDown ifTrue:[

 menu_settings

group add:(box addCheckBox:(resources string:'tiny font') on:nil) toggleView.

 menu_source

 showPageSource

 updateFromModel

 helpDocumentName

 wantsFocusWithPointerEnter

views which like to take the keyboard focus
when the pointer enters can do so by redefining this
to return true

 destroy

(comment from inherited method)
unmap & destroy - make me invisible, destroy subviews then
make me unknown to the device

 initialize

(comment from inherited method)
no - never use dithered colors for the background

 realize

(comment from inherited method)
realize - make visible;
realizing is done very late (after layout is fixed) to avoid
visible rearranging of windows on the screen

Examples:

  HTMLDocumentView openOn:'../../doc/online/english/TOP.html'

  HTMLDocumentView openOn:'../../doc/online/english/getstart/tut_3.html#REDEFINING_PRINT'

  HTMLDocumentView openOn:'.'

  |top v document|

  top := StandardSystemView extent:200@500.
  v := HVScrollableView for:HTMLDocumentView miniScrollerH:true in:top.
  v origin:0.0@ 0.0 corner:1.0@1.0.
  top openAndWaitUntilVisible.

  v homeDocument:'../../doc/online/english/TOP.html'.

  |top v document|

  top := StandardSystemView extent:200@500.
  v := HVScrollableView for:HTMLDocumentView miniScrollerH:true in:top.
  v origin:0.0@ 0.0 corner:1.0@1.0.
  top openAndWait.

  v homeDocument:'test.html'.

   |top panel list bottom htmlView|

   top := StandardSystemView new.
   top extent:(Display extent // 2).

   panel := VariableVerticalPanel origin:0.0@0.0 corner:1.0@1.0 in:top.

   list := ScrollableView for:FileSelectionList origin:0.0@0.0 corner:1.0@0.25 in:panel.
   list directory:'../../doc/online/english'.
   list action:[:arg |
                      htmlView setTopDirectoryName:(list directory pathName).
                      htmlView showFileDocument:(list selectedPathname)
               ].
   list matchBlock:[:name | '*.html' match:name].

   bottom := View origin:0.0@0.25 corner:1.0@1.0 in:panel.
   htmlView := HTMLDocumentView
                      onFile:'../../doc/online/english/TOP.html'
                      in:bottom.

   top open

   HTMLDocumentView
       openFullOnText:'
<html>
<body>
<h1>chapter 1</h1>
<h2>sub chapter 1.1</h2>
<h1>chapter 2</h1>
<h2>sub chapter 2.1</h2>
<h2>sub chapter 2.2</h2>
<h2>sub chapter 2.3</h2>
</body>
</html>
'

   |top panel list bottom htmlView|

   top := StandardSystemView new.
   top extent:(Display extent // 2).

   panel := VariableVerticalPanel origin:0.0@0.0 corner:1.0@1.0 in:top.

   list := ScrollableView for:FileSelectionList origin:0.0@0.0 corner:1.0@0.25 in:panel.
   list directory:'../../doc/online/english'.
   list action:[:arg |
                      htmlView setTopDirectoryName:(list directory pathName).
                      htmlView showFileDocument:(list selectedPathname)
               ].
   list matchBlock:[:name | '*.html' match:name].

   bottom := View origin:0.0@0.25 corner:1.0@1.0 in:panel.
   htmlView := HTMLDocumentView
                      onText:'
<html>
<body>
<h1>chapter 1</h1>
<h2>sub chapter 1.1</h2>
<h1>chapter 2</h1>
<h2>sub chapter 2.1</h2>
<h2>sub chapter 2.2</h2>
<h2>sub chapter 2.3</h2>
</body>
</html>
'
                      in:bottom.

   top open

   HTMLDocumentView
       openFullOnText:'
<html>
<body>
aaa <b>bbb</b> ccc <i>ddd</i> eee <u>fff</u> ggg
</body>
</html>
'

   HTMLDocumentView
       openFullOnText: '
<html>
<body>
000 111 222
<br>
aaa <b>bbb</b> ccc <img SRC=''/Users/exept/cg_work/stx/doc/online/icons/stx.gif''>ddd</i> eee <u>fff</u> ggg
<br>111 222 333
<br>444
</body>
</html>
'

   HTMLDocumentView
       openFullOnText: '
<html>
<head>
<style>
h1 {color:red;}
p {color:blue;}
</style>
</head>
<body>

<h1>A heading</h1>
<p>A paragraph.</p>

</body>
</html>
'