Rich documents API

Three components for text that is more than a label: a Markdown document, a line of mixed styles, and an expandable tree. All three are drawn as native Android text, with no WebView, and the Previewer draws them the same way.

This page lists their exact arguments. Rich text, Markdown and trees explains when to use which, with longer examples.

markdown

markdown(source, id=None, screen=None, parent=None, selectable=True)

Argument	Meaning
source	the Markdown text, as a string
selectable	lets the person select and copy the text; on by default
id, screen, parent	as for any component

It understands headings from # to ######, *italic*, **bold**, ~~struck~~, links, inline code and fenced code blocks, quotes, numbered and bulleted lists, checkboxes (- [ ] and - [x]) and dividers (---).

from apkpy_lib import Screen, markdown, run

notes = Screen(id="notes", scroll=True)

markdown("""# Field notes

Water the **basil** before nine, and check the [forecast](https://example.com).

- [x] Seeds ordered
- [ ] Trellis for the beans

> Tomatoes like the warm wall.
""", screen=notes)

run(notes)

rich_text

rich_text(spans, id=None, screen=None, parent=None, selectable=True)

spans is a list. Each item is a string, for plain text, or a dictionary:

Key	Meaning
text	the words of the span
bold, italic, underline, strike, code	True turns the style on
color	a colour such as "#2563EB"
size	the text size, a whole number from 8 to 72
link	an address opened when the span is tapped

rich_text([
    "Your order ",
    {"text": "#4821", "code": True},
    " ships ",
    {"text": "tomorrow", "bold": True, "color": "#15803D"},
    ". ",
    {"text": "Track it", "link": "https://example.com/track/4821", "underline": True},
], screen=orders)

A sentence with one bold word, a price in another colour, or a link in the middle of a line is one rich_text, not three labels side by side: it wraps as one paragraph.

tree_view

tree_view(nodes, id=None, screen=None, parent=None, expand_depth=1, row_height=58)

nodes is a list. Each node is a string, for a leaf with only a title, or a dictionary:

Key	Meaning
title	the row's text
subtitle	a quieter second line
children	a list of nodes under this one
expanded	True or False to choose whether this node starts open
key	a stable name for the node; by default its position, such as "0.2.1"

Argument	Meaning
expand_depth	how many levels start open, from 0 to 12; a node's own expanded wins
row_height	the height of each row, from 48 to 96

tree_view([
    {"title": "Kitchen", "children": [
        {"title": "Fridge", "subtitle": "Milk, eggs, butter"},
        {"title": "Pantry", "children": ["Rice", "Lentils", "Oats"]},
    ]},
    {"title": "Garage", "expanded": False, "children": ["Paint", "Bike pump"]},
], expand_depth=1, screen=storage_screen)

A tap on a node with children opens or closes it. A tree can be up to 24 levels deep.

On Android the tree is a RecyclerView that holds only the visible rows, so a tree with thousands of nodes and most branches closed costs no more than the rows on the screen.

Build a complete example in Native knowledge app.