Implement paragraphs (#54)

* Implement paragraphs

* Add newline before opening <p>

Author: dapetcu21

README.md

@@ -28,7 +28,7 @@ This is a <b>bold <i>italic</i></b> statement!
 The following tags are supported:
 
 | Tag     | Description                                    | Example                                     |
-|---------| ------------------------------------------------|---------------------------------------------|
+|---------|------------------------------------------------|---------------------------------------------|
 | a       | Create a "hyperlink" that generates a message  | `<a=message_id>Foobar</a>`                  |
 |         | when clicked (see `richtext.on_click`)         |                                             |
 | b       | The text should be bold                        | `<b>Foobar</b>`                             |
@@ -51,6 +51,9 @@ The following tags are supported:
 | nobr    | Prevent the text from breaking                 | `Words <nobr>inside tag</nobr> won't break` |
 | size    | Change text size, relative to default size     | `<size=2>Twice as large</size>`             |
 | spine   | Display spine model                            | `<spine=scene:anim/>`                       |
+| p       | Adds extra spacing below the line where this   | `<p>A paragraph</p>\nSome other text`       |
+|         | tag ends. Adds a newline before its opening    | `<p=2.5>This has 2.5 lines of spacing<p>`   |
+|         | tag if it doesn't already exist.               |                                             |
 
 ### Line breaks
 Note that there is no need for the HTML `<br/>` tag since line breaks (i.e. `\n`) are parsed and presented by the system. Note that a single `<br>` (ie without a closing or empty tag) isn't supported (even though most browsers accept it).
@@ -150,6 +153,7 @@ The `settings` table can contain the following values:
 * `outline` (vector4) - The default outline color of text. Will be transparent if not specified.
 * `align` (hash) - One of `richtext.ALIGN_LEFT`, `richtext.ALIGN_CENTER`, `richtext.ALIGN_RIGHT` and `richtext.ALIGN_JUSTIFY`. Defaults to `richtext.ALIGN_LEFT`. Defines how the words of a line of text are positioned in relation the provided `position`. Width must be specified for `richtext.ALIGN_JUSTIFY`.
 * `line_spacing` (number) - Value to multiply line height with. Set to a value lower than 1.0 to reduce space between lines and a value higher than 1.0 to increase space between lines. Defaults to 1.0.
+* `paragraph_spacing` (number) - Space to leave after lines with where `<p>` tags end. Relative to the line height. Defaults to 0.5 lines.
 * `image_pixel_grid_snap` (boolean) - Set to true to position image on full pixels (positions rounded to nearest integer) to avoid effects of anti-aliasing. Defaults to false.
 * `combine_words` (boolean) - Set to true to combine words with the same style on a line into a single node. This is useful for very long texts where the maximum number of nodes would exceed the limit set in the GUI. The disadvantage is that any per word operations will not work since the words have been combined.
 

example/example.gui_script

@@ -17,6 +17,12 @@ local function create_long_text_example()
 	return richtext.create(sherlock, "Roboto-Regular", settings)
 end
 
+local function create_paragraph_example()
+	local settings = { position = vmath.vector3(10, 1075, 0), width = 600 }
+	local text = "<p>This is some rather long text that wraps around and has 0.5 lines of space after its last line.</p>\n<p=2.5>This one has 2.5 lines of space.</p>\nThis is just regular text."
+	return richtext.create(text, "Roboto-Regular", settings)
+end
+
 local function create_complex_example()
 	local settings = {
 		fonts = {
@@ -301,6 +307,7 @@ function init(self)
 		{ name = "OVERLAPPING", fn = create_overlapping_tags_example },
 		{ name = "HTML ENTITIES", fn = create_html_entities_example },
 		{ name = "FADE IN", fn = create_fade_in_example },
+		{ name = "PARAGRAPHS", fn = create_paragraph_example },
 	}
 
 	self.back = gui.get_node("back/bg")

richtext/parse.lua

@@ -37,6 +37,8 @@ local function parse_tag(tag, params)
 		}
 	elseif tag == "nobr" then
 		settings.nobr = true
+	elseif tag == "p" then
+		settings.paragraph = tonumber(params) or true
 	end
 
 	return settings
@@ -189,6 +191,18 @@ function M.parse(text, default_settings)
 			if not found then print(("Found end tag '%s' without matching start tag"):format(name)) end
 		end
 
+		if name == "p" then
+			local last_word = all_words[#all_words]
+			if last_word then
+				if not is_endtag then
+					last_word.linebreak = true
+				end
+				if is_endtag or is_empty then
+					last_word.paragraph_end = true
+				end
+			end
+		end
+
 		-- parse text after the tag on the next iteration
 		text = after_tag
 	end

richtext/richtext.lua

@@ -323,6 +323,7 @@ function M.create(text, font, settings)
 	settings.outline = settings.outline or V4_ZERO
 	settings.position = settings.position or V3_ZERO
 	settings.line_spacing = settings.line_spacing or 1
+	settings.paragraph_spacing = settings.paragraph_spacing or 0.5
 	settings.image_pixel_grid_snap = settings.image_pixel_grid_snap or false
 	settings.combine_words = settings.combine_words or false
 	if settings.align == M.ALIGN_JUSTIFY and not settings.width then
@@ -347,6 +348,7 @@ function M.create(text, font, settings)
 	local line_words = {}
 	local line_width = 0
 	local line_height = 0
+	local paragraph_spacing = 0
 	local position = vmath.vector3(settings.position)
 	local word_count = #words
 	for i = 1, word_count do
@@ -387,9 +389,10 @@ function M.create(text, font, settings)
 
 			-- update text metrics
 			text_metrics.width = math.max(text_metrics.width, line_width)
-			text_metrics.height = text_metrics.height + (line_height * settings.line_spacing)
+			text_metrics.height = text_metrics.height + (line_height * settings.line_spacing) + paragraph_spacing
 			line_width = word_metrics.total_width
 			line_height = word_metrics.height
+			paragraph_spacing = 0
 		else
 			-- the word fits on the line, add it and update text metrics
 			if combined_metrics then
@@ -418,6 +421,16 @@ function M.create(text, font, settings)
 			word.delete = true
 		end
 
+		if word.paragraph_end then
+			local paragraph = word.paragraph
+			if paragraph then
+				paragraph_spacing = math.max(
+					paragraph_spacing,
+					line_height * (paragraph == true and settings.paragraph_spacing or paragraph)
+				)
+			end
+		end
+
 		-- handle line break
 		if word.linebreak then
 			-- position all words on the line up until the linebreak
@@ -426,9 +439,10 @@ function M.create(text, font, settings)
 			position_words(line_words, line_width, line_height, position, settings)
 
 			-- update text metrics
-			text_metrics.height = text_metrics.height + (line_height * settings.line_spacing)
+			text_metrics.height = text_metrics.height + (line_height * settings.line_spacing) + paragraph_spacing
 			line_height = word_metrics.height
 			line_width = 0
+			paragraph_spacing = 0
 		end
 	end