eXept Software AG Logo

Smalltalk/X Webserver

Documentation of class 'Text':

Home

Documentation
www.exept.de
Everywhere
for:
[back]

Class: Text


Inheritance:

   Object
   |
   +--Collection
      |
      +--SequenceableCollection
         |
         +--ArrayedCollection
            |
            +--UninterpretedBytes
               |
               +--CharacterArray
                  |
                  +--Text

Package:
stx:libbasic2
Category:
Collections-Text
Version:
rev: 1.154 date: 2018/02/02 00:05:00
user: cg
file: Text.st directory: libbasic2
module: stx stc-classLibrary: libbasic2
Author:
Claus Gittinger

Description:


Texts add emphasis information to a string.

Texts and strings should behave interchanchably to the outside
world, except that texts keep per-character emphasis information.
(strings return nil when asked for an element's emphasis).
Use #string, to get a text's underlying plain string without any emphasis
information.

Currently, the following attributes are supported:
    #bold
    #italic
    #underline
    #underwave
    #strikeout
    (#color -> aColor)
    (#backgroundColor -> aColor)
    (#underlineColor -> aColor)
    (#strikeoutColor -> aColor)

Attributes may be combined (pass an array of above) as emphasis.
See examples.

This class is a hack and may need some massage.


Related information:

    CharacterArray
    String
    RunArray

Class protocol:

emphasis constants
o  backgroundColorEmphasis

o  boldEmphasis

o  colorEmphasis

o  etchColorEmphasis

o  foregroundColorEmphasis

o  italicEmphasis

o  overlineEmphasis

o  reverseEmphasis

o  strikeoutEmphasis

o  subscriptEmphasis

o  superscriptEmphasis

o  underlineEmphasis

o  underwaveEmphasis

emphasis helper
o  addEmphasis: e1 to: e2
merge two emphasis's into one
usage example(s):
     Text addEmphasis:#bold to:#bold           
     Text addEmphasis:#bold to:#italic         
     Text addEmphasis:#bold to:#(italic strikeout)   
     Text addEmphasis:#italic to:#(italic strikeout) 
     Text addEmphasis:#(italic strikeout) to:#bold  
     Text addEmphasis:#(italic strikeout) to:#italic 
     Text addEmphasis:#(italic strikeout) to:#(bold underline) 
     Text addEmphasis:(#color->Color red) to:#(bold underline) 

o  emphasis: e1 includes: e2
return true, if e1 includes e2.
e2 should be a single emphasis.
usage example(s):
     Text emphasis:#bold includes:#bold           
     Text emphasis:#bold includes:#italic         
     Text emphasis:#(italic strikeout) includes:#bold  
     Text emphasis:#(italic strikeout) includes:#italic 
     Text emphasis:(#color->Color red) includes:#color 

o  extractEmphasis: key from: e
if key is included in the emphasis, e then return the key.
Otherwise, if a n association with that key is included, return the value.
Otherwise, return nil.
usage example(s):
     Text extractEmphasis:#bold  from:#bold           
     Text extractEmphasis:#bold  from:#italic           
     Text extractEmphasis:#bold  from:#(italic strikeout)           
     Text extractEmphasis:#bold  from:#(italic bold)           
     Text extractEmphasis:#color  from:(#color->Color red)           
     Text extractEmphasis:#color  from:(#foo->Color red)           

o  removeEmphasis: emToRemove from: empArg
remove an emphasis; if it was not in empArg, do nothing
usage example(s):
     Text removeEmphasis:#bold from:#bold           
     Text removeEmphasis:#bold from:#italic         
     Text removeEmphasis:#bold from:#(italic strikeout)    
     Text removeEmphasis:#bold from:#(italic bold strikeout)    
     Text removeEmphasis:#italic from:#(italic strikeout) 
     Text removeEmphasis:#(italic strikeout) from:#bold  
     Text removeEmphasis:#(italic strikeout) from:#italic  
     Text removeEmphasis:#(italic strikeout) from:#(bold underline) 
     Text removeEmphasis:#(italic strikeout bold) from:#(bold underline) 
     Text removeEmphasis:#(italic strikeout bold underline) from:#(bold underline) 
     Text removeEmphasis:(#color->Color red) from:#(bold underline) 
     Text removeEmphasis:(#color->Color red) from:(#color->Color red) 
     Text removeEmphasis:#color from:(#color->Color red)   
     Text removeEmphasis:#color from:(#backgroundColor->Color red)      
     Text removeEmphasis:#color from:(Array with:#bold with:#underline with:#color->Color red) 

initialization
o  initialize
initialize the class
usage example(s):
     Text initialize

instance creation
o  fromString: aString
create a Text instance, for the characters in aString,
without emphasis.
usage example(s):
     Text fromString:'hello'

o  new
create a new empty Text instance.
Redefined for string-protocol compatibility
usage example(s):
Text new

o  new: size
create a new empty Text instance.
Redefined for string-protocol compatibility

o  string: aString
create a Text instance, for the characters in aString,
without emphasis.
usage example(s):
     Text string:'hello'

o  string: aString color: aColor
create a Text instance, for the characters in aString,
which are colored as aColor (only the foregroundColor is affected).
This is a shortCut for creating an emphasis of (#color->aColor)
usage example(s):
     Dialog
        information:(Text string:'hello' color:(Color red))

o  string: aString emphasis: attribute
create a Text instance, for the characters in aString,
which are emphasized as described by attribute.
usage example(s):
     Text string:'hello' emphasis:#bold

     Dialog
        information:(Text string:'hello' emphasis:#bold)

     Dialog
        information:(Text string:'hello' emphasis:#italic)

     Dialog
        information:(Text string:'hello' emphasis:#underline)

     Dialog
        information:(Text string:'hello' emphasis:#strikeout)

o  string: aString emphasisCollection: attributeCollection
create a Text instance, for the characters in aString,
which are individually emphasized as described by attributeCollection.
usage example(s):
     Text 
        string:'hello' 
        emphasisCollection:#(#bold #bold #italic #italic #italic)

     Dialog
        information:(Text 
                        string:'hello' 
                        emphasisCollection:#(#bold #bold #italic #italic #(#underline italic)))

o  string: aString foregroundColor: fgColor backgroundColor: bgColor
create a Text instance, for the characters in aString,
which are colored in fgColor on bgColor.
This is a shortCut for creating an emphasis of
#( #color->fgColor) (#backgroundColor->bgColor)
usage example(s):
     Dialog
        information:(Text string:'hello' 
                          foregroundColor:(Color red)
                          backgroundColor:(Color yellow))

o  string: aString runs: aRun
create a Text instance, for the characters in aString,
which are individually emphasized as described by attributeCollection.

o  uninitializedNew: size
for compatibility only

o  writeStreamClass
the type of stream used in writeStream


Instance protocol:

accessing
o  at: characterIndex
return the plain character at characterIndex

o  at: characterIndex put: aCharacter
change the character at characterIndex to be aCharacter.
The emphasis (if any) of that character remains unchanged.

o  byteAt: characterIndex
return the plain character at characterIndex

o  byteAt: characterIndex put: aCharacter
change the character at characterIndex to be aCharacter.
The emphasis (if any) of that character remains unchanged.

comparing
o  = aStringOrText
compare the receiver and the argument, ignoring emphasis
usage example(s):
     'hello' asText = 'hello'        
     'hello' asText = 'hello' asText 
     'hello' asText allBold = 'hello' 

o  hash
return a suitable hashcode (req'd since = is redefined)

converting
o  asHtmlDocumentForRequest: request
( an extension from the stx:goodies/webServer/comanche package )
(self runs values) with: (self runs runs) do:

o  asSingleByteString
'hello world' asUnicodeString asText asSingleByteString

o  asText
return a Text-object (string with emphasis) from myself.
I am already a text object.

copying
o  , aStringOrText
concatenate the receiver's characters with the argument's characters,
and return string or text object containing those characters.
If either the receiver or the argument contains emphasis information,
a text object will be returned.
Otherwise, a string (i.e. without emphasis) is returned.
usage example(s):
     ('hello' asText allBold) , ' world'    
     'hello' allBold,' world'    
     'hello' allBold,' world' allItalic    
     'hello' allBold,123,'world' allItalic    
     'hello' , (' world' asText allBold)
     'hello' , ' world'
     'hello',123,' world'
     ('hello' asText allBold) , (' world' asText allBold)

o  concatenateFromString: aString
return the concatenation of aString and myself.
This may be a Text (if I have emphasis) or a string (if not).

o  copyFrom: start to: stop
return the subcollection starting at index start, anInteger and ending
at stop, anInteger.

o  postCopy
|t|

t := 'hello' emphasizeAllWith:#bold.
t inspect. t copy inspect.
t emphasisAllRemove:#bold.

displaying
o  displayOn: aGCOrView x: x0 y: yBase opaque: opaqueWanted
display the receiver on a GC.
This is one of the ugliest pieces of code...

emphasis
o  actionForAll: aBlock
change the actionBlock of all characters.
Some widgets use this like a href if clicked onto the text.
usage example(s):
transcript ignores this...
     Transcript showCR:
        ((Text string:'hello - click on me') actionForAll:[Transcript flash]) 
usage example(s):
labels also...
     Label new
        label: ((Text string:'hello - click on me') actionForAll:[Transcript flash]);
        open

o  allBold
make all characters bold
usage example(s):
     (Text string:'hello') allBold
     Transcript showCR: ('hello' allBold)   

o  allBoldOverline
make all characters bold and overline

o  allItalic
make all characters italic
usage example(s):
     (Text string:'hello') allItalic
     Transcript showCR: ('hello' allItalic)   

o  allNonBold
make all characters non-bold
usage example(s):
     (Text string:'hello') allBold allNonBold

o  allOverline
make all characters overline
usage example(s):
     Transcript showCR: ('hello' asText allOverline)   

o  allStrikedOut
strikeOut all characters
usage example(s):
     Transcript showCR: ('hello' allStrikedOut)   

o  allUnderlined
underline all characters
usage example(s):
     Transcript showCR:('hello' allUnderlined) 

o  allUnderwaved
underwave all characters
usage example(s):
     Transcript showCR:('hello' asText allUnderwaved) 

o  backgroundColorizeAllWith: aColor
change the bg-color of all characters
usage example(s):
     Transcript showCR:
        ((Text string:'hello') backgroundColorizeAllWith:(Color red)) 

     Transcript showCR:
        ('hello' allBold backgroundColorizeAllWith:(Color red)) 

     Transcript showCR:
        ('hello' asText backgroundColorizeAllWith:(Color red)) 

     Transcript showCR:
        ('hello ' , ('red' allBold backgroundColorizeAllWith:(Color red)) , ' world')

o  colorizeAllWith: aColor
change the color of all characters
usage example(s):
     Transcript showCR:
        ((Text string:'hello') colorizeAllWith:(Color red)) 

     Transcript showCR:
        ('hello' colorizeAllWith:(Color red)) 

     Transcript showCR:
        ('hello' allBold colorizeAllWith:(Color red)) 

     Transcript showCR:
        ('hello' asText colorizeAllWith:(Color red)) 

     Transcript showCR:
        ('hello ' , ('red' allBold colorizeAllWith:(Color red)) , ' world')

o  colorizeAllWith: fgColor on: bgColor
change the color and bg-color of all characters
usage example(s):
     Transcript showCR:
        ((Text string:'hello') colorizeAllWith:(Color blue) on:(Color yellow)) 

o  emphasis
return the emphasis
usage example(s):
     (Text string:'hello') allBold emphasis 
     'hello' emphasis   

o  emphasis: emArray
(Text string:'hello') emphasis:#(italic bold italic bold bold)

o  emphasisAllAdd: newEmphasis
add to the emphasis to all characters. return the receiver
usage example(s):
     (Text string:'hello') allBold 
        emphasisAllAdd:#italic

     Transcript show:((Text string:'hello') allBold 
                        emphasisAllAdd:#italic)

o  emphasisAllRemove: anEmphasis
remove the emphasis from all characters. return the receiver
usage example(s):
     ((Text string:'hello') emphasizeAllWith:#(bold italic))
        emphasisAllRemove:#italic

     ((Text string:'hello') emphasizeAllWith:(Array with:#color->Color red
                                                    with:#italic))
        emphasisAllRemove:#italic

     ((Text string:'hello') emphasizeAllWith:(Array with:#color->Color red
                                                    with:#italic))
        emphasisAllRemove:#color

     Transcript show:(((Text string:'hello') emphasizeAllWith:#(bold italic)) 
                        emphasisAllRemove:#italic)

o  emphasisAt: characterIndex
return the emphasis at some index
usage example(s):
     (Text string:'hello') allBold emphasisAt:2 

o  emphasisAt: characterIndex add: newEmphasis
add to the emphasis at some index. return the receiver
usage example(s):
     (Text string:'hello') allBold emphasisAt:2 add:#italic

o  emphasisAt: characterIndex put: emphasis
change the emphasis at some index. return the receiver
usage example(s):
     (Text string:'hello') allBold emphasisAt:2 put:#italic

o  emphasisAt: characterIndex remove: emphasisToRemove
remove from the emphasis at some index. return the receiver
usage example(s):
     (Text string:'hello') 
        allBold emphasisAt:2 remove:#bold

     (Text string:'hello' emphasis:#(bold italic)) 
        emphasisAt:2 remove:#bold

o  emphasisCollection
return the emphasis

o  emphasisFrom: start to: stop add: newEmphasis
add to the emphasis within some range. return the receiver
usage example(s):
     (Text string:'hello') allBold 
        emphasisFrom:2 to:4 add:#italic

     Transcript showCR:((Text string:'hello') allBold 
                            emphasisFrom:2 to:4 add:#italic)

o  emphasisFrom: start to: stop remove: anEmphasis
remove from the emphasis within some range. return the receiver
usage example(s):
     (Text string:'hello') allBold 
        emphasisFrom:2 to:4 remove:#bold

     Transcript showCR:((Text string:'hello') allBold 
                            emphasisFrom:2 to:4 remove:#bold)

o  emphasiseFrom: start to: stop with: newEmphasis
set to the emphasis within some range. return the receiver
usage example(s):
     (Text string:'hello') allBold 
        emphasiseFrom:2 to:4 with:#italic

     Transcript showCR:((Text string:'hello') allBold 
                            emphasiseFrom:2 to:4 with:#italic)

o  emphasizeAllWith: emphasis
change the emphasis of all characters
usage example(s):
     (Text string:'hello') allBold emphasizeAllWith:#italic 

o  emphasizeFrom: start count: count with: emphasis
change the emphasis of a range of characters, given startIndex and count.
usage example(s):
     (Text string:'hello world') 
        emphasizeFrom:1 count:5 with:#bold;
        emphasizeFrom:7 count:5 with:#italic

o  emphasizeFrom: start to: stop with: emphasis
change the emphasis of a range of characters
usage example(s):
     (Text string:'hello world') 
        emphasizeFrom:1 to:5 with:#bold;
        emphasizeFrom:7 to:11 with:#italic

o  emphasizeFrom: start with: emphasis
change the emphasis of some characters upTo the end
usage example(s):
     (Text string:'hello world') 
        emphasizeFrom:1 count:5 with:#bold;
        emphasizeFrom:7 with:#italic

o  strikeoutAll
strikeout all characters
usage example(s):
     Transcript showCR:
        ('hello' asText strikeoutAll) 

o  withoutAnyColorEmphasis
return a copy with color emphasis removed (fg and bg)

o  withoutBackgroundColorEmphasis
return a copy with bg-color emphasis removed

o  withoutEmphasis
return my underlying plain string

o  withoutEmphasis: emphasisToRemove
return a copy with a particular emphasis removed

o  withoutForegroundColorEmphasis
return a copy with fg-color emphasis removed

inspecting
o  inspector2TabText
( an extension from the stx:libtool package )

o  inspectorExtraAttributes
( an extension from the stx:libtool package )
extra (pseudo instvar) entries to be shown in an inspector.

printing & storing
o  displayOn: aGCOrStream
append a printed representation from which the receiver can be reconstructed
to aStream.

o  displayString
return a string used when displaying the receiver in a view.

o  printOn: aStream
print the receiver's characters (including emphasis) on aStream.
Notice, that some streams simply ignore the emphasis

o  storeOn: aStream
append a printed representation from which the receiver can be reconstructed
to aStream.

private-accessing
o  emphasisCollection: emphasisCollection
set the string and emphasis collection.
The emphasis collection contains per-character information.

o  runs

o  setRuns: anArrayOrRunArray

o  setString: aString setRuns: anArrayOrRunArray

o  string: aString emphasis: emphasis
set the string and emphasis. The emphasis is applied to all characters.

o  string: aString emphasisCollection: emphasisCollection
set the string and emphasis collection.
The emphasis collection contains per-character information.

queries
o  bitsPerCharacter
return the number of bits I (my underlying string) require for storage.
(i.e. is it a regular String or a TwoByteString)

o  emphasisAtPoint: aPoint on: aGCOrView
return the emphasis at a given point, or nil if there is none

o  encoding

o  hasChangeOfEmphasis
return true, if the receiver contains non-empty emphasis information
i.e. any non-normal (=emphasized) characters

o  hasEmphasis: emphasis
return true, if the receiver contains given emphasis
usage example(s):
        'Hello' asText allBold hasEmphasis: #bold.
        'Hello' asText allBold allUnderlined hasEmphasis: #bold.
        'Hello' asText allBold allUnderlined hasEmphasis: #italic.                              
        ('Hello' asText allBold allUnderlined , ' World' asText allItalic) hasEmphasis: #italic.

o  heightOn: aGC
return the number of device units, required on aGC's device

o  indexOf: aCharacter startingAt: index
search aCharacters index in the underlying string

o  isPlainString
return true, if the receiver is a plain string - without attributes;
false is returned here.

o  isSingleByteCollection
return true, if the receiver has access methods for bytes;
i.e. #at: and #at:put: accesses a byte and are equivalent to #byteAt: and byteAt:put:
and #replaceFrom:to: is equivalent to #replaceBytesFrom:to:.
false is returned here since #replaceBytesFrom:to: is not implemented in Text.
- the method is redefined from UninterpretedBytes.

o  isText
return true if this is a Text object - always true here

o  occurrencesOf: aCharacter
count & return the number of occurrences of aCharacter in the
underlying string

o  size
return the number of characters in the underlying string

o  string
return the receiver without any emphasis information
i.e. the underlying string.

o  widthFrom: startIndex to: endIndex on: aGC
return the number of device units, required on aGC's device

o  widthOn: aGC
return the number of device units, required on aGC's device

replacing
o  replaceFrom: start to: stop with: aCollection startingAt: startIndex
replace a range of characters, from another string or text object.
The corresponding characters' emphasis information is also copied.
Return the receiver.
usage example(s):
     ((Text string:'hello') allBold emphasisAt:2 put:#italic)
        replaceFrom:1 to:3 with:'HEL' startingAt:1

     ((Text string:'hello') allBold emphasisAt:2 put:#italic)
        replaceFrom:1 to:3 with:#($H $E $L) startingAt:1


Examples:


In a textView:
  |t v|

  t := 'The quick brown fox jumps over the lazy dog' asText.
  t emphasizeFrom:(t findString:'quick')
    count:5 with:#bold.

  t emphasizeFrom:(t findString:'brown')
    count:9 with:(Array with:#color->(Color name:'brown')
                                                   with:#bold).
  t emphasizeFrom:(t findString:'lazy')
    count:4 with:(Array with:#color->(Color red)
                                                    with:#italic).
  t emphasizeFrom:(t findString:'dog')
    count:3 with:#underline.

  v := HVScrollableView for:EditTextView.
  v contents:t.

  v width:450.
  v open.
  |t v|

  t := 'a',('1' emphasizeAllWith:#subscript),'x',('3' emphasizeAllWith:#superscript)
       ,'a',('2' emphasizeAllWith:#subscript),'x',('2' emphasizeAllWith:#superscript)
       ,'a',('3' emphasizeAllWith:#subscript),'x',('n' emphasizeAllWith:#superscript).

  Dialog information:t.
plain string (for comparison):
  Dialog information:'hello'
emphasized strings as dialog titles:
  Dialog
      information:((Text string:'hello') allBold)
  Dialog
      information:(Text string:'hello' emphasis:#italic)
  Dialog
      information:(Text string:'hello' emphasis:#(underline))
  Dialog
      information:(Text string:'hello' emphasis:#(underwave))
  Dialog
      information:(Text string:'hello' emphasis:#(bold underline))
  Dialog
      information:(Text string:'hello'
               emphasis:(Array with:#bold
                               with:#strikeout
                               with:(#color->Color red)))
  Dialog
      information:(Text string:'hello'
               emphasis:(Array with:(#color->Color black)
                               with:#underwave
                               with:(#underlineColor->Color red)))
  Dialog
      information:(Text string:'hello'
               emphasis:(Array with:#bold
                               with:#strikeout
                               with:(#color->Color red)
                               with:(#backgroundColor->Color yellow)))
  Dialog
      information:(Text string:'hello' color:(Color red))


ST/X 7.1.0.0; WebServer 1.663 at exept.de:8081; Mon, 20 May 2019 23:17:27 GMT