[TIMOB-24080] : iOS - Paragraph style support in attributed string

apidoc/Titanium/UI/Attribute.yml

@@ -90,6 +90,15 @@ properties:
                 color: 'red'
             }
 
+        On IOS, if you use the <Titanium.UI.ATTRIBUTE_PARAGRAPH_STYLE>, the `value` must be ParagraphAttribute. 
+        E.g:
+
+            {
+                minimumLineHeight: 10.0,
+                tailIndent: 5,
+                lineBreakMode: Titanium.UI.ATTRIBUTE_LINE_BREAK_BY_WORD_WRAPPING
+            }
+
         On iOS, if you use the <Titanium.UI.ATTRIBUTE_TEXT_EFFECT>, you must use the <Titanium.UI.ATTRIBUTE_LETTERPRESS_STYLE> constant.
 
         On iOS, if you use the <Titanium.UI.ATTRIBUTE_LINE_BREAK>, you must use one of
@@ -114,3 +123,127 @@ properties:
         This specifies the range of text to apply the property to, as an array of two numbers: `[from, length]`.
     type: Array<Number>
     optional: false
+
+---
+name: ParagraphAttribute
+summary: An abstract datatype for specifying an Paragraph style attribute.
+description: |
+    Attributes are added corresponding to value to create paragraph style, 
+    which when used with attributed string will give styled text. 
+platforms: [iphone, ipad]
+since: "7.5.0"
+
+properties:
+  - name: alignment
+    summary: The text alignment of the receiver.
+    type: Number
+    constants: [ Titanium.UI.TEXT_ALIGNMENT_* ]
+
+  - name: firstLineHeadIndent
+    summary: The indentation of the first line of the receiver.
+    description: |
+      This property contains the distance (in points) from the leading margin 
+      of a text container to the beginning of the first line of paragraph. 
+      This value is always nonnegative float value or dimension string (e.g. '10px').
+    type: [Number,String]
+
+  - name: headIndent
+    summary: The indentation of the lines of lines other than the first.
+    description: |
+      This property contains the distance (in points) from the leading margin 
+      of a text container to the beginning of lines other than the first. 
+      This value is always nonnegative float value or dimension string (e.g. '10px').
+    type: [Number,String]
+
+  - name: tailIndent
+    summary: The trailing indentation of the receiver.
+    description: |
+      If positive, this value is the distance (in points) from the leading margin 
+      (for example, the left margin in left-to-right text). If 0 or negative, 
+      it is the distance (in points) from the trailing margin. This is a float value or 
+      dimension string (e.g. '10px').
+    type: [Number,String]
+
+  - name: lineBreakMode
+    summary: The mode that should be used to break lines in the receiver.
+    description: |
+      This property contains the line break mode to be used laying out the text of paragraph.
+    type: Number
+    constants: [ Titanium.UI.ATTRIBUTE_LINE_BREAK_* ]
+
+  - name: maximumLineHeight
+    summary: The maximum line height of receiver.
+    description: |
+      This property contains the maximum height in points that any line in the receiver will occupy, 
+      regardless of the font size or size of any attached graphic. This value is always nonnegative 
+      float value or dimension string (e.g. '10px'). The default value is 0. 
+      Glyphs and graphics exceeding this height will overlap neighboring lines; however, a maximum 
+      height of 0 implies no line height limit. Although this limit applies to the line itself, 
+      line spacing adds extra space between adjacent lines.
+    type: [Number,String]
+
+  - name: minimumLineHeight
+    summary: The minimum height of receiver.
+    description: |
+      This property contains the minimum height in points that any line in the receiver will occupy, 
+      regardless of the font size or size of any attached graphic. This value must be nonnegative float value 
+      or dimension string (e.g. '10px').
+      E.g. If you have set minimum height 30 and font size 10. It will make line height 30 which have 
+      smaller text size and more vertical sapcing between text. 
+    type: [Number,String]
+
+  - name: lineSpacing
+    summary: The distance in points between the bottom of one line fragment and the top of the next.
+    description: |
+      This value is always nonnegative float value or dimension string (e.g. '10px'). This value is 
+      included in the line fragment heights in the layout manager.
+    type: [Number,String]
+
+  - name: paragraphSpacingAfter
+    summary: The space after the end of the paragraph.
+    description: |
+      This property contains the space (measured in points) added at the end of the paragraph 
+      to separate it from the following paragraph. This value must be nonnegative float value or 
+      dimension string (e.g. '10px'). The space between paragraphs is determined by adding the paragraphSpacingAfter 
+      of previous paragraph and the paragraphSpacingBefore of current paragraph.
+    type: [Number,String]
+
+  - name: paragraphSpacingBefore
+    summary: The distance between the top of paragraph and the beginning of its text content.
+    description: |
+      This property contains the space (measured in points) between the top of paragraph and 
+      the beginning of its text content. This value can be float value or dimension string (e.g. '10px').
+      The default value of this property is 0.0.
+    type: [Number,String]
+
+  - name: lineHeightMultiple
+    summary: The line height multiple.
+    description: |
+      The natural line height of the receiver is multiplied by this factor (if positive) 
+      before being constrained by minimum and maximum line height. The default value of 
+      this property is 0.0, which means nothing multiplied.
+    type: Number
+
+  - name: hyphenationFactor
+    summary: The threshold of paragraph for hyphenation.
+    description: |
+      Valid values lie between 0.0 and 1.0 inclusive. The default value is 0.0. Hyphenation 
+      is attempted when the ratio of the text width (as broken without hyphenation) to the 
+      width of the line fragment is less than the hyphenation factor. When the hyphenation 
+      factor of paragraph is 0.0, the hyphenation factor of layout manager is used instead. 
+      When both are 0.0, hyphenation is disabled. This property detects the user-selected 
+      language by examining the first item in preferredLanguages.
+    type: Number
+
+  - name: allowsDefaultTighteningForTruncation
+    summary: |
+      A Boolean value indicating whether the system may tighten inter-character spacing 
+      before truncating text.
+    description: |
+      When this property is set to true, the system tries to reduce the space between characters 
+      before truncating characters. The system performs this tightening in cases where the text 
+      would not otherwise fit in the available space. The maximum amount of tightening performed 
+      by the system is dependent on the font, line width, and other factors. The default value of 
+      this property is false.
+    type: Boolean
+    osver: {ios: {min: "9.0"}}

apidoc/Titanium/UI/UI.yml

@@ -340,6 +340,18 @@ properties:
     osver: {ios: {min: "6.0"}}
     permission: read-only
 
+  - name: ATTRIBUTE_PARAGRAPH_STYLE
+    summary: |
+        Use with <Attribute.type> to manages the behaviour of string set.
+    description: |
+        Use <ParagraphAttribute> for the 'value' property in the attribute dictionary.
+        Range for this should be whole string.
+        See <Attribute> for more information on type modes.
+    type: Number
+    platforms: [iphone, ipad]
+    since: "7.5.0"
+    permission: read-only
+
   - name: ATTRIBUTE_STROKE_WIDTH
     summary: |
         Use with <Attribute.type> to specify the width of the stroke text.
@@ -480,6 +492,9 @@ properties:
     permission: read-only
 
   - name: ATTRIBUTE_LINE_BREAK
+    deprecated:
+        since: "7.5.0"
+        notes: Use <Titanium.UI.ATTRIBUTE_PARAGRAPH_STYLE.lineBreakMode> instead.  
     summary: |
         Use with <Attribute.type> to wrap and truncate the text.
     description: |

iphone/Classes/TiUIAttributedStringProxy.h

@@ -37,12 +37,12 @@ typedef enum {
   AttributeNameStrikethroughColor,
   AttributeNameObliqueness,
   AttributeNameExpansion,
-  AttributeNameLineBreak
+  AttributeNameLineBreak, // deprecated
 } AttributeName;
 
 #pragma mark - Not exposed to JS. Internal Use Only.
 @property (nonatomic, readonly) NSMutableAttributedString *attributedString;
 @property (nonatomic, readonly) NSMutableDictionary *urls;
 @end
 
-#endif
+#endif

iphone/Classes/TiUIAttributedStringProxy.m

@@ -1,6 +1,6 @@
 /**
  * Appcelerator Titanium Mobile
- * Copyright (c) 2015 by Appcelerator, Inc. All Rights Reserved.
+ * Copyright (c) 2015-2018 by Appcelerator, Inc. All Rights Reserved.
  * Licensed under the terms of the Apache Public License
  * Please see the LICENSE included with this distribution for details.
  */
@@ -77,8 +77,43 @@ - (void)addAttribute:(id)args
     break;
 
   case AttributeNameParagraphStyle:
+    ENSURE_DICT(value);
     attrName = NSParagraphStyleAttributeName;
-    errorMessage = @"ATTRIBUTE_PARAGRAPH_STYLE not yet supported";
+    NSMutableParagraphStyle *paragraphStyle = [[[NSMutableParagraphStyle alloc] init] autorelease];
+
+    for (NSString *key in value) {
+      id objectValue = [value objectForKey:key];
+      if ([key isEqualToString:@"alignment"]) {
+        paragraphStyle.alignment = [[TiUtils numberFromObject:objectValue] unsignedIntegerValue];
+      } else if ([key isEqual:@"firstLineHeadIndent"]) {
+        paragraphStyle.firstLineHeadIndent = [TiUtils dimensionValue:objectValue].value;
+      } else if ([key isEqual:@"headIndent"]) {
+        paragraphStyle.headIndent = [TiUtils dimensionValue:objectValue].value;
+      } else if ([key isEqual:@"tailIndent"]) {
+        paragraphStyle.tailIndent = [TiUtils dimensionValue:objectValue].value;
+      } else if ([key isEqual:@"lineBreakMode"]) {
+        paragraphStyle.lineBreakMode = [[TiUtils numberFromObject:objectValue] unsignedIntegerValue];
+      } else if ([key isEqualToString:@"maximumLineHeight"]) {
+        paragraphStyle.maximumLineHeight = [TiUtils dimensionValue:objectValue].value;
+      } else if ([key isEqualToString:@"minimumLineHeight"]) {
+        paragraphStyle.minimumLineHeight = [TiUtils dimensionValue:objectValue].value;
+      } else if ([key isEqualToString:@"lineSpacing"]) {
+        paragraphStyle.lineSpacing = [TiUtils dimensionValue:objectValue].value;
+      } else if ([key isEqualToString:@"paragraphSpacingAfter"]) {
+        paragraphStyle.paragraphSpacing = [TiUtils dimensionValue:objectValue].value;
+      } else if ([key isEqualToString:@"paragraphSpacingBefore"]) {
+        paragraphStyle.paragraphSpacingBefore = [TiUtils dimensionValue:objectValue].value;
+      } else if ([key isEqualToString:@"lineHeightMultiple"]) {
+        paragraphStyle.lineHeightMultiple = [TiUtils floatValue:objectValue];
+      } else if ([key isEqualToString:@"hyphenationFactor"]) {
+        paragraphStyle.hyphenationFactor = (float)[TiUtils floatValue:objectValue];
+      } else if ([TiUtils isIOS9OrGreater] && [key isEqualToString:@"allowsDefaultTighteningForTruncation"]) {
+        paragraphStyle.allowsDefaultTighteningForTruncation = [TiUtils boolValue:objectValue];
+      } else {
+        DebugLog(@"[WARN] Ti.UI.ATTRIBUTE_PARAGRAPH_STYLE - Unsupported property %@", key);
+      }
+    }
+    attrValue = paragraphStyle;
     break;
 
   case AttributeNameForegroundColor:
@@ -178,11 +213,12 @@ - (void)addAttribute:(id)args
     break;
 
   case AttributeNameLineBreak:
+    DEPRECATED_REPLACED(@"UI.ATTRIBUTE_LINE_BREAK", @"UI.ATTRIBUTE_PARAGRAPH_STYLE.lineBreakMode", @"7.5.0");
     attrName = NSParagraphStyleAttributeName;
-    NSMutableParagraphStyle *paragraphStyle = [[[NSMutableParagraphStyle alloc] init] autorelease];
+    NSMutableParagraphStyle *paragraphStyleObject = [[[NSMutableParagraphStyle alloc] init] autorelease];
     NSNumber *num = [TiUtils numberFromObject:value];
-    [paragraphStyle setLineBreakMode:[num unsignedIntegerValue]];
-    attrValue = paragraphStyle;
+    [paragraphStyleObject setLineBreakMode:[num unsignedIntegerValue]];
+    attrValue = paragraphStyleObject;
     break;
   }
   if (errorMessage != nil) {
@@ -280,4 +316,4 @@ - (void)setAttributes:(id)args
 
 @end
 
-#endif
+#endif

iphone/Classes/UIModule.m

@@ -529,7 +529,7 @@ - (NSNumber *)convertUnits:(id)args
 MAKE_SYSTEM_PROP(ATTRIBUTE_STRIKETHROUGH_COLOR, AttributeNameStrikethroughColor);
 MAKE_SYSTEM_PROP(ATTRIBUTE_OBLIQUENESS, AttributeNameObliqueness);
 MAKE_SYSTEM_PROP(ATTRIBUTE_EXPANSION, AttributeNameExpansion);
-MAKE_SYSTEM_PROP(ATTRIBUTE_LINE_BREAK, AttributeNameLineBreak);
+MAKE_SYSTEM_PROP(ATTRIBUTE_LINE_BREAK, AttributeNameLineBreak); // deprecated
 
 - (NSNumber *)ATTRIBUTE_UNDERLINE_STYLE_NONE
 {

tests/Resources/ti.ui.attributedstring.addontest.js

@@ -0,0 +1,65 @@
+/*
+ * Appcelerator Titanium Mobile
+ * Copyright (c) 2011-Present by Appcelerator, Inc. All Rights Reserved.
+ * Licensed under the terms of the Apache Public License
+ * Please see the LICENSE included with this distribution for details.
+ */
+/* eslint-env mocha */
+/* global Ti */
+/* eslint no-unused-expressions: "off" */
+'use strict';
+var should = require('./utilities/assertions');
+
+describe('Titanium.UI.AttributedString', function () {
+
+	it.ios('Ti.UI.AttributedString', function () {
+		should(Ti.UI.AttributedString).not.be.undefined;
+	});
+
+	it.ios('apiName', function () {
+		var attributedString = Ti.UI.createAttributedString({
+			text: 'abc'
+		});
+		should(attributedString).have.readOnlyProperty('apiName').which.is.a.String;
+		should(attributedString.apiName).be.eql('Ti.UI.AttributedString');
+	});
+
+	it.ios('createAttributedString', function () {
+		var attributedString = Ti.UI.createAttributedString({
+			text: 'abc'
+		});
+
+		should(attributedString).be.a.Object;
+		should(attributedString.text).be.a.String;
+		should(attributedString.text).be.eql('abc');
+	});
+
+	it.ios('attributes', function () {
+		var str = 'Lorem ipsum dolor sit amet.';
+		var attributedString = Ti.UI.createAttributedString({
+			text: str,
+			attributes: [ {
+				type: Ti.UI.ATTRIBUTE_PARAGRAPH_STYLE,
+				value: {
+					alignment: Ti.UI.ATTRIBUTE_TEXT_ALIGNMENT_JUSTIFIED,
+					minimumLineHeight: 40,
+					headIndent: 5,
+					lineSpacing: 5
+				},
+				range: [ 0, str.length ]
+			} ]
+		});
+
+		should(attributedString.text).be.eql(str);
+		should(attributedString.attributes.length).be.eql(1);
+
+		attributedString.addAttribute({
+			type: Ti.UI.ATTRIBUTE_FONT,
+			value: {
+				fontSize: 16
+			},
+			range: [ 0, str.length ]
+		});
+		should(attributedString.attributes.length).be.eql(2);
+	});
+});