Streams

When placing text in a box, you probably don't want to have to calculate how the text will wrap around a box yourself. For this you'll use streams. Streams define a flow object where content is placed side by side (left to right) and when a line is finished, the next line is started and content is continued to be placed in there. Streams support bidirectional writing and the inclusion of graphic objects with text, floating togather.

Most of the times you will just place text, even just a single item:

{	"pages": [
		{
			"width": 595,
			"height": 842,
			"boxes": [
						{
							"bottom":10,
							"left":10,
							"width":200,
							"height":200,
							"stream":{
										"items": [
											{
												"type":"text",
												"text":["so i\n was writing this text,"," and it had several items"],
												"options": {
                                						                        "fontSource": "arial",
													"size":40, 
													"color":"blue"
												}

											}
										]						
									}

						}
			]
		}
	]
}

The stream definition here simply places the text wrapping around a box of 200X200.

The items array may contain multiple elements. This makes sense as you may want to change the text style, which you can do by having multiple text items.

Consider the next example:

{
	"pages": [
		{
			"width": 595,
			"height": 842,
			"boxes": [
						{
							"bottom":10,
							"left":10,
							"width":200,
							"height":200,
							"stream":{
										"items": [
											{
												"type":"text",
												"text":["text and then an image"],
												"options": {
						                                                       "fontSource": "arial",
													"size":10,
													"color":"green"
												}

											},	
											{
												"type": "image",
												"source": "img4",
												"transformation": [0.1,0,0,0.1,0,0]
											},											
											{
												"type":"text",
												"text":["and it all worked very well"],
												"options": {
						                                                       "fontSource": "arial",
													"size":30,
													"color":"green"
												}

											}
										]
									}

						}
			]
		}
	]
}

The stream content has 3 elements - text in green using arial font at size of 10. Then an image, Then more text, this time at size of 30. The contents will flow in the box size by side, as one would expect.

Leading

One optional property of the stream object handles the line spacing. By default the line baseline is placed at 1.2 times the largest height/font size in the line. You can set a different multiplier by providing a leading property with the measure that you want.

Direction

If you want right-to-left composition direction, set the direction property of the stream to rtl. Bidirectional text is supported, and conforms to the direction setting in the same manner as any other known bidirectional text implementation. This means that you can safely anticipate what will be shown by comparing with any existing application.

Notes about the composition of the stream box

The following combines note about how the text flows:

• Default is left to right direction, top to bottom. if you want to change from left-to-right to right-to-left that use 'direction'
• text items are broken to words, spaces and newlines and so may wrap within the same item. Other element types are never broken.
• newlines are either \r, \n or ,\r\n. All treated in the same manner and mean to break line on the spot.
• spaces that happen to be in the beginning of a line are ignored.
• inline boxes can be used but must have width and height properties defining their measures.
• streams may not be used as sub elements of a stream (but it is perfectly ok to have an item that is a box and in it a stream).
• you would normally place width and height on the box to define its boundaries. If you don't want to have a bottom limit to the wrapping of the text don`t define a height in which case the placement would use bottom as its top and will go down from there.
• when placing streams with no height definition, and you want to place a box below them, then it becomes useful to use the top property in that lower box with the id of the box containing the stream. This way, whatever the height for the stream will be finally, the lower box could be placed in accordance. To learn more about placing boxes top using another box read here.
• bidirectional placement is supported. When using direction with the value of rtl the ordering of items will be right to left, and any left to right text will be placed in accordance to the known BIDI algorithm rules, which are implemented in any application.