4712-Text-Core-package-documentation-and-test

src/NECompletion/NECMenuMorph.class.st

@@ -50,7 +50,7 @@ NECMenuMorph class >> convertToSHSymbol: aSymbol [
 
 { #category : #'help text' }
 NECMenuMorph class >> explanationAttributes [
-	^{TextIndent spaceUsed; tabs: 2}
+	^{TextIndent tabs: 2}
 ]
 
 { #category : #'help text' }
@@ -229,7 +229,7 @@ NECMenuMorph class >> shortcut: aString text: secondString on: aTextStream [
 
 { #category : #'help text' }
 NECMenuMorph class >> shortcutAttributes [
-	^ {TextIndent spaceUsed; tabs: 1. TextEmphasis italic }
+	^ {TextIndent  tabs: 1. TextEmphasis italic }
 ]
 
 { #category : #'preferences-fonts' }

src/SUnit-Core/HashAndEqualsTestCase.class.st

@@ -21,15 +21,15 @@ HashAndEqualsTestCase >> setUp [
 
 { #category : #tests }
 HashAndEqualsTestCase >> testEquality [
-	"Check that TextFontChanges report equality correctly"
+	"Check that TextAttribute subclasses report equality correctly"
 	prototypes
 		do: [:p | self
 				should: [(EqualityTester with: p) result]] 
 ]
 
 { #category : #tests }
 HashAndEqualsTestCase >> testHash [
-	"test that TextFontChanges hash correctly"
+	"Check TextAttribute subclasses with equality method hash correctly"
 	prototypes do: [:p |
 		self should: [(HashTester with: p) result]] 
 ]

src/Text-Core/Text.class.st

@@ -587,7 +587,7 @@ Text >> string [
 	^string
 ]
 
-{ #category : #attributes }
+{ #category : #testing }
 Text >> unembellished [ 
 	"Return true if the only emphases are the default font and bold"
 	| font1 bold |

src/Text-Core/TextAction.class.st

@@ -1,5 +1,28 @@
 "
-A sepcific text attribute to run actions on a text
+I attach a bloc of code to a portion of text. The bloc is executed when the user clic on this portion of text.
+
+---- exemple 1 -----
+| stream |
+stream := TextStream on: (Text new: 100).
+stream 
+	nextPutAll:  'Start a ';
+	withAttributes: {TextEmphasis underlined. TextAction new actOnClickBlock: [Smalltalk tools browser open ]}
+	do: [ stream nextPutAll: 'browser' ].
+TextMorph new 
+	newContents: stream contents;
+	openInWindow .
+---- exemple 2 -----
+| stream |
+stream := TextStream on: (Text new: 100).
+stream 
+	withAttributes: {TextAction new actOnClickBlock: [:attr :event :textMorph :parag :editor | 		
+		textMorph owner color: Color white.
+		parag rightFlush.
+		editor flash]}
+	do: [ stream nextPutAll: 'Change me' ].
+TextMorph new 
+	newContents: stream contents;
+	openInWindow .
 "
 Class {
 	#name : #TextAction,
@@ -31,7 +54,6 @@ TextAction class >> initialize [
 { #category : #evaluating }
 TextAction >> actOnClick: anEvent for: anObject in: paragraph editor: editor [
 	"sent when a user clicks on a piece of text to which I am applied in an editor"
-
 	"may be self is included in the event or an Object. "
 	^ actOnClickBlock valueWithEnoughArguments: (Array with: self with: anEvent with: anObject with: paragraph with: editor)
 ]
@@ -67,27 +89,24 @@ Click Here<3+4>
 	(b1 < b2) & (b1 > 0) ifFalse: ["only one part"
 		param := self validate: aString.
 		param ifNil: [ ^{ nil. nil } ].
-		^ Array with: param with: (param size = 0 ifTrue: [nil] ifFalse: [param])].
+		^ Array with: param with: (param ifEmpty: [nil] ifNotEmpty: [param])].
 	"Two parts"
 	trim := aString trimBoth.
 	(trim at: 1) == $< 
 		ifTrue: [(trim last) == $>
 			ifTrue: ["only instructions" 
 				param := self validate: (aString copyFrom: b1+1 to: b2-1).
-				show := param size = 0 ifTrue: [nil] ifFalse: [param]]
+				show := param ifEmpty: [nil] ifNotEmpty: [param]]
 			ifFalse: ["at the front"
 				param := self validate: (aString copyFrom: b1+1 to: b2-1).
-				show := param size = 0 ifTrue: [nil] 
-						ifFalse: [aString copyFrom: b2+1 to: aString size]]]
+				show := param ifEmpty: [nil] ifNotEmpty: [aString copyFrom: b2+1 to: aString size]]]
 		ifFalse: [(trim last) == $>
 			ifTrue: ["at the end"
 				param := self validate: (aString copyFrom: b1+1 to: b2-1).
-				show := param size = 0 ifTrue: [nil] 
-						ifFalse: [aString copyFrom: 1 to: b1-1]]
+				show := param ifEmpty: [nil] ifNotEmpty: [aString copyFrom: 1 to: b1-1]]
 			ifFalse: ["Illegal -- <> has text on both sides"
 				show := nil]].
 	^ Array with: param with: show
-
 ]
 
 { #category : #testing }

src/Text-Core/TextAlignment.class.st

@@ -1,16 +1,28 @@
 "
 I'm a Text attribute that tells how content should be aligned.
 
+----- exemple 1 ---------------
 TextMorph new 
-  newContents: (Text streamContents: [:aStream| 
-										aStream
- 											nextPutAll: 'Left flush' asText; 
-											cr;
-											nextPutAll: ('Centered' asText addAttribute: TextAlignment centered); 
- 											cr;
-											nextPutAll: ('Right flush' asText addAttribute: TextAlignment rightFlush); 
- 											cr ]);
-  openInWindowLabeled: 'TextAlignment demo'
+	newContents: (Text streamContents: [:aStream| 
+		aStream
+			nextPutAll: 'Left flush' asText; 
+			cr;
+			nextPutAll: ('Centered' asText addAttribute: TextAlignment centered); 
+ 			cr;
+			nextPutAll: ('Right flush' asText addAttribute: TextAlignment rightFlush); 
+ 			cr ]);
+  	openInWindowLabeled: 'TextAlignment demo'
+----- exemple 2 ---------------
+| stream |
+stream := TextStream on: (Text new: 100).
+stream 
+	nextPutAll:  'Pharo';	cr;
+	withAttribute: TextAlignment centered do:  [stream nextPutAll: 'is' ];  cr;
+	withAttribute: TextAlignment rightFlush  do: [ stream nextPutAll: 'cool ']; cr;
+	withAttribute: TextAlignment justified  do: [ stream nextPutAll: 'because it is both an interactive programming enviornment and a reflexive programming language.' ].
+TextMorph new 
+	newContents: stream contents;
+	openInWindow .
 "
 Class {
 	#name : #TextAlignment,

src/Text-Core/TextAttribute.class.st

@@ -1,6 +1,19 @@
 "
-Tells a piece of text to be a certain way.
-
+I am an abstract class to represent a text attribute, the way a portion of text is graphically represented.
+My sub-classes specify these representations:
+- colouring (TextColor), 
+- bold, italic, underlined, 
+- narrow, strike out (TextEmphasis), 
+- alignment (TextAlignment),
+- indentation (TextIndent),
+- font change (TextFontChange),
+- kerning (TextKern),
+- url and related action (TextAction hierarchy).
+- morph (TextAnchor)
+
+My instances are stored in the Text instance runs variable (a RunArray).
+
+------------8<-----------------------------------------------------------------------------------------
 Select text, press Command-6, choose a attribute.  If selected text is of the form 
 	Hi There<Smalltalk beep>
 the part in angle brackets is saved for action, and the Hi There appears in the paragraph.  If selection has no angle brackets, use the whole thing as both the text and the action.

src/Text-Core/TextColor.class.st

@@ -99,6 +99,7 @@ TextColor >> color: aColor [
 
 { #category : #scanning }
 TextColor >> dominates: other [
+"Only one color attribute on a same portion of text."
 	^ other class == self class
 ]
 

src/Text-Core/TextDoIt.class.st

@@ -1,5 +1,17 @@
 "
-A doIt action on a text. When the text is clicked the text is seen as source code and evaluated
+A doIt action on a text. When the text is clicked the text is seen as source code and evaluated (Not really true as both 
+the portion of text and its DoIt attribute need to hold the same string)
+
+| stream |
+stream := TextStream on: (Text new: 100).
+stream 
+	withAttribute: (TextDoIt evalString: 'Smalltalk tools browser open')
+	do: [ stream nextPutAll: 'Some action...' ].
+TextMorph new 
+	newContents: stream contents;
+	openInWindow .
+
+
 "
 Class {
 	#name : #TextDoIt,

src/Text-Core/TextEmphasis.class.st

@@ -87,7 +87,7 @@ TextEmphasis >> dominates: other [
 		and: [emphasisCode = other emphasisCode]
 ]
 
-{ #category : #styling }
+{ #category : #accessing }
 TextEmphasis >> emphasisCode [
 	^ emphasisCode
 ]
@@ -128,7 +128,7 @@ TextEmphasis >> turnOff [
 	setMode := false
 ]
 
-{ #category : #styling }
+{ #category : #accessing }
 TextEmphasis >> value [
 	"a synonym for empahasisCode, to make me polymorphic with Numbers"
 

src/Text-Core/TextFontChange.class.st

@@ -1,5 +1,6 @@
 "
-A TextFontChange encodes a font change applicable over a given range of text.  The font number is interpreted relative to the textStyle governing display of this text.
+A TextFontChange encodes a font change applicable over a given range of text.  
+The font number is interpreted relative to the textStyle governing display of this text.
 "
 Class {
 	#name : #TextFontChange,

src/Text-Core/TextFontReference.class.st

@@ -1,5 +1,17 @@
 "
-A TextFontReference encodes a font change applicable over a given range of text.  The font reference is absolute:  unlike a TextFontChange, it is independent of the textStyle governing display of this text.
+A TextFontReference encodes a font change applicable over a given range of text.  
+The font reference is absolute:  unlike a TextFontChange, it is independent of the textStyle governing display of this text.
+
+-----exemple--------
+| stream |
+stream := TextStream on: (Text new: 100).
+stream 
+	nextPutAll: 'Small is ';
+	withAttribute: (TextFontReference toFont: (LogicalFont familyName: 'Source Sans Pro' pointSize: 8) )
+	do: [ stream nextPutAll: 'cool' ].
+TextMorph new 
+	newContents: stream contents;
+	openInWindow
 "
 Class {
 	#name : #TextFontReference,

src/Text-Core/TextIndent.class.st

@@ -1,5 +1,16 @@
 "
-create a hanging indent. 
+An attribute to indent text at the left.
+
+------exemple------
+| stream |
+stream := TextStream on: (Text new: 100).
+stream 
+	withAttribute: (TextIndent tabs: 1) do: [ stream nextPutAll: 'Pharo is cool'];
+	cr;
+	withAttribute: (TextIndent tabs: 2) do: [stream nextPutAll: 'Smalltalk is cool'].
+TextMorph new 
+	newContents: stream contents;
+	openInWindow.
 "
 Class {
 	#name : #TextIndent,

src/Text-Core/TextKern.class.st

@@ -1,5 +1,17 @@
 "
 A TextKern encodes a kerning change applicable over a given range of text.  Positive values of kern spread letters out, negative kern will cause them to overlap more.  Note that kerns other than 0 will display somewhat slower, as kerning is not yet supported in the text scanning primitive. 
+
+-----exemple-------
+| stream |
+stream := TextStream on: (Text new: 100).
+stream 
+	withAttribute: (TextKern  kern: 1) do: [ stream nextPutAll: 'Pharo is cool'];
+	cr;
+	nextPutAll: 'Pharo is cool'; cr;
+	withAttribute: (TextKern kern: -1) do: [stream nextPutAll: 'Pharo is cool'].
+TextMorph new 
+	newContents: stream contents;
+	openInWindow.
 "
 Class {
 	#name : #TextKern,

src/Text-Core/TextLink.class.st

@@ -94,8 +94,7 @@ TextLink >> validate: specString [
 
 	| list first mid last |
 	list := specString findTokens: ' 	.|'.
-	list isEmpty
-		ifTrue: [ ^ nil ].
+	list ifEmpty: [ ^ nil ].
 	last := list last.
 	last first isUppercase
 		ifTrue: [ 

src/Text-Core/TextPrintIt.class.st

@@ -1,5 +1,14 @@
 "
-A ""Print It"" action on a text. When the text is clicked the text is seen as source code and evaluated. After that the result is printed
+A ""Print It"" action on a text. When the text is clicked the text is seen as source code and evaluated (see comment on parent). After that the result is printed in pop up message.
+
+| stream |
+stream := TextStream on: (Text new: 100).
+stream 
+	withAttribute: (TextPrintIt evalString: '-1 arcCos')
+	do: [ stream nextPutAll: '-1 arcCos' ].
+TextMorph new 
+	newContents: stream contents;
+	openInWindow.
 "
 Class {
 	#name : #TextPrintIt,

src/Text-Core/TextStream.class.st

@@ -42,6 +42,7 @@ TextStream >> nextPutAll: aCollection [
 
 { #category : #private }
 TextStream >> withAttribute: att do: strmBlock [
+"Add text to the stream with a block and apply its text attribute"
 	| pos1 val |
 	pos1 := self position.
 	val := strmBlock value.
@@ -51,6 +52,7 @@ TextStream >> withAttribute: att do: strmBlock [
 
 { #category : #private }
 TextStream >> withAttributes: attributes do: streamBlock [ 
+"Add text to the stream with a block and apply its text attributes (in collection)"
 	| pos1 val |
 	pos1 := self position.
 	val := streamBlock value.