What is it?
A widget that allows formatting within longer pieces of text:
How do I use it?
Go to the Layout tool and click on the RichText tab in the widget panel on the left. Remember that clicking on the 'i' button will give you some more information on the widget.
Drag the icon from the widget panel onto the page canvas.
It's now ready to use. You can change it's size, position, background colour and other properties using the property panel to the right of the Layout tool.
To enter formatted text, click on the Settings tab in the property panel.
You can now type into the text input box on that tab, using markdown characters to format particular words or phrases. You will see the effects of your changes in the widget on the page canvas when you hit Return or move the focus out of the input box. Here are some useful markdown commands:
- For headings, use # characters at the start of the line. Use one # for the largest heading, ## for one size down, ### for two sizes down, and so on.
- For bold text, surround the words with two asterisks. For example, **this text is bold**
- For italic, surround the words with one asterisk. For example, *this text will appear in italics*
- To make a bullet-pointed list, put each item on its own line and put a hyphen (minus symbol '-') with a space either side at the start of the line. For example
- First item
- Second item
- Third item
- To make a numbered list, put each item on its own line and put a number followed by a period at the beginning of each line. For example,
1. First item
2. Second item
3. Third item
(Note that it doesn't actually matter which numbers you use, the list will always start with 1 and increment normally.)
- To create paragraphs, just leave blank lines between your text
- To force a new line without a new paragraph, add two or more spaces to the end of a line
If you want to force multiple line breaks, add the text <br> . Single line breaks can be inserted by leaving blank lines in the editor using the return key, but multiple blank lines will be converted to a single line break.
- To indent text, precede each line (or paragraph) with >. For example, >this text will be indented
- To include a horizontal line, place three or more hyphens preceded by a space on a line by themselves.
For more detail on markdown, see the markdown syntax definition. Note, however, that you will not be able to include hyperlinks in a RichText widget.
What if the text is too long to fit?
If the text doesn't fit into the size of the RichText widget you can make the widget bigger by grabbing the little resize handle in the bottom right hand corner of the widget and stretching it. If that still isn't enough or you don't want to make the RichText widget bigger you can make it scrollable. This means that the text within the RichText Widget will actually scroll under the users finger so that they can read all of it even if it doesn't fit. If you use this option then make sure that your design makes it obvious to your users that there is more text that can be reached, for example by sizing it so that the last line is cut off half way.
To make a RichText widget scrollable use the property panel to the right of the Layout tool. Click on the Settings tab in the property panel and then at the bottom click on the box next to the word "scroll".
Note: If you use this option then after you have scrolled, the text in the box won't be laid out exactly the same as on the device anymore. We are working on this and will have a fix in a future release.
What properties does it have?
Most of the RichText widget's properties are shared with other widgets and allow you to control its size, position, whether it has a border etc. You can always see the full list by clicking on the 'i' button on the RichText tab in the widget panel, as shown above. The only properties that are specific to the RichText widget is the text input box on the Settings tab as described in the previous section and the scroll option also described above.
How can I use it in code?
- set the widget x-position using ui.myRichText.x(23);.
- change the font colour with ui.myRichText.fontColor("blue");
You can also create and display an TextInput widget on a page completely in code, this time using an anonymous function to handle the user's input. e.g.
var w = new af.RichText();
w.text("#Example\nThis RichText widget was created *in code*");
Note the use of "\n" in the text passed into the widget to specify a new line. Full documentation for coding with an TextInput widget can be found in the AppFurnace code API Documentation.