Class: Text

• Inheritance
• Description
• Class protocol
  • emphasis constants
  • emphasis helper
  • initialization
  • instance creation
• Instance protocol
  • accessing
  • comparing
  • converting
  • copying
  • copying-private
  • displaying
  • emphasis
  • enumerating
  • inspecting
  • printing & storing
  • private-accessing
  • queries
  • replacing
• Examples

Inheritance:

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

Package:

stx:libbasic2

Category:

Collections-Text

Version:

rev: 1.177 date: 2024/04/12 18:05:08

user: stefan

file: Text.st directory: libbasic2

module: stx stc-classLibrary: libbasic2

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.

copyright
COPYRIGHT (c) 1996 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:

 backgroundColorEmphasis

 boldEmphasis

 colorEmphasis

 etchColorEmphasis

 foregroundColorEmphasis

 italicEmphasis

 overlineEmphasis

 reverseEmphasis

 strikeoutEmphasis

 subscriptEmphasis

 superscriptEmphasis

 underlineEmphasis

 underwaveEmphasis

 actionBlockFromEmphasis: emphasis

 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)

 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

 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)

 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)

 initialize

initialize the class

Usage example(s):

Text initialize

 fromString: aString

create a Text instance, for the characters in aString,
without emphasis.

Usage example(s):

Text fromString:'hello'

 new

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

Usage example(s):

Text new

 new: size

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

 string: aString

create a Text instance, for the characters in aString,
without emphasis.

Usage example(s):

Text string:'hello'

 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))

 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)

 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)))

 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))

 string: aString runs: aRun

create a Text instance, for the characters in aString,
which are individually emphasized as described by attributeCollection.

 uninitializedNew: size

for compatibility only

 writeStreamClass

the type of stream used in writeStream

Instance protocol:

 at: characterIndex

return the plain character at characterIndex

 at: characterIndex put: aCharacter

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

 byteAt: characterIndex

return the plain character at characterIndex

 byteAt: characterIndex put: aCharacter

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

 = aStringOrText

compare the receiver and the argument, ignoring emphasis

Usage example(s):

'hello' asText = 'hello' 'hello' asText = 'hello' asText 'hello' asText allBold = 'hello'

 hash

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

 asFilename

return a Filename with pathname taken from the receiver

 asHtmlDocumentForRequest: request
( an extension from the stx:goodies/webServer/comanche package )

(self runs values) with: (self runs runs) do:

 asPlainString

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

 asSingleByteString

'hello world' asUnicodeString asText asSingleByteString

 asStringWithBitsPerCharacterAtLeast: numRequiredBitsPerCharacter

'hello world' allBold asStringWithBitsPerCharacterAtLeast:16

 asText

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

 , 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)

 concatenateFromString: aString

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

 copyFrom: start to: stop

return the subcollection starting at index start, anInteger and ending
at stop, anInteger.

 postCopy

|t|

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

 displayOn: aGCOrView x: x0 y: yBase opaque: opaqueWanted

display the receiver on a GC.
This is one of the ugliest pieces of code...

 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

 allBold

make all characters bold

Usage example(s):

(Text string:'hello') allBold Transcript showCR: ('hello' allBold)

 allBoldOverline

make all characters bold and overline

 allItalic

make all characters italic

Usage example(s):

(Text string:'hello') allItalic Transcript showCR: ('hello' allItalic)

 allNonBold

make all characters non-bold

Usage example(s):

(Text string:'hello') allBold allNonBold

 allOverline

make all characters overline

Usage example(s):

Transcript showCR: ('hello' asText allOverline)

 allStrikedOut

strikeOut all characters

Usage example(s):

Transcript showCR: ('hello' allStrikedOut)

 allUnderlined

underline all characters

Usage example(s):

Transcript showCR:('hello' allUnderlined)

 allUnderwaved

underwave all characters

Usage example(s):

Transcript showCR:('hello' asText allUnderwaved)

 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')

 changeColorEmphasis: aSymbol

change the color of all characters

Usage example(s):

Transcript showCR: ((('hello' asText colorizeAllWith:(Color red)), ' World' allBold) changeColorEmphasis:#lightened) Transcript showCR: (('hello' asText colorizeAllWith:(Color black)) changeColorEmphasis:#lightened)

 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')

 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))

 emphasis

return the emphasis

Usage example(s):

(Text string:'hello') allBold emphasis 'hello' emphasis

 emphasis: emArray

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

Usage example(s):

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

 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)

 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)

 emphasisAt: characterIndex

return the emphasis at some index

Usage example(s):

(Text string:'hello') allBold emphasisAt:2

 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

 emphasisAt: characterIndex put: emphasis

change the emphasis at some index. return the receiver

Usage example(s):

(Text string:'hello') allBold emphasisAt:2 put:#italic

 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

 emphasisCollection

return the emphasis

 emphasisFrom: startIndex add: newEmphasis

add to the emphasis from the given startIndex to the end.
Return the (modified) receiver

Usage example(s):

(Text string:'hello') emphasisFrom:2 add:#bold Transcript showCR:((Text string:'hello') emphasisFrom:2 add:#bold)

 emphasisFrom: start to: stop add: newEmphasis

add to the emphasis within some range.
Return the (modified) 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)

 emphasisFrom: start to: stop remove: anEmphasis

remove from the emphasis within some range.
Return the (modified) 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)

 emphasisTo: endIndex add: newEmphasis

add to the emphasis from 1 to the given endIndex.
Return the (modified) receiver

Usage example(s):

(Text string:'hello') allBold emphasisTo:3 add:#italic Transcript showCR:((Text string:'hello') emphasisTo:3 add:#italic)

 emphasizeAllWith: newEmphasis

change the emphasis of all characters.
Return the (modified) receiver

Usage example(s):

(Text string:'hello') allBold emphasizeAllWith:#italic

 emphasizeFrom: start to: stop with: emphasis

change the emphasis of a range of characters.
Return the receiver

Usage example(s):

(Text string:'hello world') emphasizeFrom:1 to:5 with:#bold; emphasizeFrom:7 to:11 with:#italic

 strikeoutAll

strikeout all characters

Usage example(s):

Transcript showCR: ('hello' asText strikeoutAll)

 withoutAnyColorEmphasis

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

 withoutBackgroundColorEmphasis

return a copy with bg-color emphasis removed

 withoutEmphasis

return my underlying plain string

 withoutEmphasis: emphasisToRemove

return a copy with a particular emphasis removed

 withoutForegroundColorEmphasis

return a copy with fg-color emphasis removed

 withEmphasisFrom: start to: stop do: aTwoArgBlock

enumerate characters and emphasis into aTwoArgBlock

 inspector2TabText
( an extension from the stx:libtool package )

 inspectorExtraAttributes
( an extension from the stx:libtool package )

extra (pseudo instvar) entries to be shown in an inspector.

 displayOn: aGCOrStream

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

 displayString

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

 printOn: aStream

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

 storeOn: aStream

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

 emphasisCollection: emphasisCollection

set the string and emphasis collection.
The emphasis collection contains per-character information.

 runs

 setRuns: anArrayOrRunArray

 setString: aString setRuns: anArrayOrRunArray

 string: aString emphasis: emphasis

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

Usage example(s):

|t| t := Text new string:'hello' emphasis:#bold. t emphasisAt:2.

 string: aString emphasisCollection: emphasisCollection

set the string and emphasis collection.
The emphasis collection contains per-character information.

 bitsPerCharacter

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

 emphasisAtX: pointX on: aGCOrView

return the emphasis at a given x-coordinate, or nil if there is none.
Does not care for multiline strings (i.e. only works for single line strings)

 encoding

(comment from inherited method)
return the strings encoding, as a symbol.
Here, by default, we assume unicode-encoding.
Notice, that ISO-8859-1 is a true subset of unicode,
and that singleByteStrings are therefore both unicode AND
8859-1 encoded.

 hasChangeOfEmphasis

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

 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.

 heightOn: aGC

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

 indexOf: aCharacter startingAt: index

search aCharacters index in the underlying string

 isPlainString

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

 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.

 isText

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

 occurrencesOf: aCharacter

count & return the number of occurrences of aCharacter in the
underlying string

 size

return the number of characters in the underlying string

 string

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

 stringSpecies

(comment from inherited method)
return the underlying strings bitsPerCharacter
(i.e. is it a regular String or a TwoByteString)

 widthFrom: startIndex to: endIndex on: aGC

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

 widthOn: aGC

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

 replaceFrom: startArg to: stopArg 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:

  |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.

  Dialog information:'hello'

  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))