markdownview — u_pbt_markdownview #

← Component reference · Guide contents

markdownview shows a Markdown document, read-only, at the colours of the theme: headings, lists, tables, task lists, coloured code, pictures. You set the text in is_markdown, or the path of a file in is_source; a link never navigates, it raises ue_link_clicked and the application decides. The raw HTML of a document is never run.

▶ See it live — Demo application, Markdown viewer tile, with the code and this page side by side.

At a glance #

Quick start #

// Show a Markdown file : its pictures and relative links are read against its folder
uo_md.is_source = "C:\Acme\Help\guide.md"

// ... or any text the application has
uo_md.is_markdown = "# Release notes~n~n- [x] Orders~n- [ ] Invoices"

// ue_link_clicked : the viewer never navigates, the application decides where to open as_url

Properties #

Methods #

Events #

Example #

An online help that opens its links #

A document often comes from elsewhere: sort by the kind of the link, never by its text. A web page or a mail opens in its program, another document shows in the same component, and a file — an .exe, a .bat — is never run without asking.

// ue_link_clicked of uo_md : the viewer never navigates, the application decides by the kind
choose case as_kind
	case u_pbt_markdownview.LINK_WEB, u_pbt_markdownview.LINK_MAIL

		// A web page, a mail : their program
		ShellExecuteW(0, "open", as_url, "", "", 1)
	case u_pbt_markdownview.LINK_DOCUMENT

		// Another page of the help : in this viewer
		uo_md.is_source = as_url
	case else

		// A file of the disk or of the network : never run without asking
		MessageBox("Link", "This link leads to a file : " + as_url)
end choose

Editing Markdown: a codeeditor and a markdownview #

The viewer keeps its reading position when the text changes: you edit the end of a long document and the preview does not jump to the top.

// Local variables
string ls_notes

// The notes of the customer, in Markdown
ls_notes = "# Notes~n~n- [ ] Call back on Monday"

// The editor colours Markdown ; the viewer shows the page
uo_editor.is_syntax = u_pbt_codeeditor.SYNTAX_MARKDOWN
uo_editor.is_text = ls_notes
uo_md.is_markdown = ls_notes

// ue_changed of uo_editor : the whole recipe
uo_md.is_markdown = uo_editor.is_text

A table of contents in a list #

For a file set by is_source, fill the list in ue_loaded: before it, the file is still being read.

// Local variables
string ls_titles[], ls_anchors[]
long ll_levels[], ll_i

// ue_loaded of uo_md : one line per heading, indented by its level
lb_toc.Reset()
for ll_i = 1 to uo_md.of_toc(/*titles*/ ls_titles, /*levels*/ ll_levels, /*anchors*/ ls_anchors)
	lb_toc.AddItem(Fill(" ", (ll_levels[ll_i] - 1) * 3) + ls_titles[ll_i])
next

// Local variables
string ls_titles[], ls_anchors[]
long ll_levels[]

// SelectionChanged of lb_toc : bring that heading to the top
uo_md.of_toc(/*titles*/ ls_titles, /*levels*/ ll_levels, /*anchors*/ ls_anchors)
uo_md.of_scroll_to(/*anchor*/ ls_anchors[index])

A check-list the user ticks #

// Local variables
string ls_text
long ll_at, ll_n

// The user may tick the boxes of the text
uo_md.ib_tasks_editable = true

// ue_task_toggled of uo_md : the start of line al_line of the text
ls_text = uo_md.is_markdown
ll_at = 1
for ll_n = 2 to al_line
	ll_at = Pos(ls_text, "~n", ll_at) + 1
next

// Its box, the first "[" of the line, becomes [x] or [ ]
ll_at = Pos(ls_text, "[", ll_at)
if ab_checked then
	ls_text = Replace(ls_text, ll_at, 3, "[x]")
else
	ls_text = Replace(ls_text, ll_at, 3, "[ ]")
end if

// The text set back : the view keeps its place
uo_md.is_markdown = ls_text

The component never rewrites the text itself: the application keeps control of what it saves.

Reopening a document where the reader left it #

// Before closing the window : remember the place in the guide
SetProfileString("acme.ini", "help", "position", uo_md.is_position)

// When the guide is shown again : the place is taken once the file is on screen
uo_md.is_source = "C:\Acme\Help\guide.md"
uo_md.is_position = ProfileString("acme.ini", "help", "position", "")

Good practice #

• It is a reader, not an editor: to write Markdown, put a codeeditor in SYNTAX_MARKDOWN beside it, linked by one line in its ue_changed (see the example); the viewer keeps its place when the text changes.
• Links are yours: nothing opens by itself; ue_link_clicked gives the address, already resolved against the folder of the file, and its kind (as_kind) — sort by it, never by the text of the address, and never run a LINK_FILE without asking.
• A document runs nothing: raw HTML is displayed as written (or, with ib_allow_html, only a short list of inert tags), a javascript: link stays text, an http:// picture is refused, and so is a picture on a network share (ib_network_pictures) — a document from elsewhere is shown safely.
• Pictures: a relative path is read against the folder of the file (or is_base_path for a text); for a picture from the Web, prefer https://, or download it first (restclient.of_download) and give its path. ib_remote_pictures false loads none.
• A file is read in the background: after is_source, wait for ue_loaded to read the table of contents; an anchor and a search asked meanwhile wait for the file.
• A large document stays smooth: the first blocks appear at once, the rest in the following moments; the search (50,000 occurrences at most), of_scroll_to and printing wait until it is whole.
• Right to left: the document follows the direction of the application (lists, quotes and tables turn round), a code block stays left to right, and a column the author aligned (:--, --:) keeps its side.

Inherited from the common base #

These members exist on every visual component — they are not specific to this one. They are detailed once, in the transverse chapters; this table only says where to read them.

← Component reference · Guide contents