markdownview — u_pbt_markdownview #

← Komponentenreferenz · Inhalt des Handbuchs

markdownview zeigt ein Markdown-Dokument schreibgeschützt in den Farben des Themas: Überschriften, Listen, Tabellen, Aufgabenlisten, farbiger Code, Bilder. Sie setzen den Text in is_markdown oder den Pfad einer Datei in is_source; ein Link navigiert nie, er löst ue_link_clicked aus und die Anwendung entscheidet. Rohes HTML eines Dokuments wird nie ausgeführt.

▶ Live sehen — Demoanwendung, Kachel Markdown viewer, mit dem Code und dieser Seite nebeneinander.

Auf einen Blick #

Schnellstart #

// 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

Eigenschaften #

Methoden #

Ereignisse #

Beispiel #

Eine Online-Hilfe, die ihre Links öffnet #

Ein Dokument kommt oft von woanders: Sortieren Sie nach der Art des Links, nie nach seinem Text. Eine Webseite oder eine E-Mail öffnet sich in ihrem Programm, ein anderes Dokument erscheint in derselben Komponente, und eine Datei — eine .exe, eine .bat — wird nie ohne Rückfrage gestartet.

// 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

Markdown bearbeiten: ein codeeditor und ein markdownview #

Der Viewer behält seine Leseposition, wenn sich der Text ändert: Sie bearbeiten das Ende eines langen Dokuments, ohne dass die Vorschau nach oben springt.

// 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

Ein Inhaltsverzeichnis in einer Liste #

Bei einer mit is_source gesetzten Datei füllen Sie die Liste in ue_loaded: vorher wird die Datei noch gelesen.

// 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])

Eine Checkliste, die der Benutzer abhakt #

// 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

Die Komponente schreibt den Text nie selbst um: die Anwendung behält die Kontrolle über das, was sie speichert.

Ein Dokument dort wieder öffnen, wo der Leser aufgehört hat #

// 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", "")

Bewährte Praxis #

• Ein Leser, kein Editor: Um Markdown zu schreiben, daneben ein codeeditor in SYNTAX_MARKDOWN, verbunden durch eine Zeile in seinem ue_changed (siehe Beispiel); der Viewer behält seine Position, wenn sich der Text ändert.
• Die Links gehören Ihnen: Nichts öffnet sich von selbst; ue_link_clicked liefert die Adresse, bereits gegen den Ordner der Datei aufgelöst, und ihre Art (as_kind) — sortieren Sie danach, nie nach dem Text der Adresse, und starten Sie einen LINK_FILE nie ohne Rückfrage.
• Ein Dokument führt nichts aus: rohes HTML wird so angezeigt, wie es geschrieben ist (oder, mit ib_allow_html, nur eine kurze Liste harmloser Tags), ein javascript:-Link bleibt Text, ein http://-Bild wird abgelehnt, ebenso ein Bild auf einer Netzwerkfreigabe (ib_network_pictures) — ein Dokument von anderswo wird gefahrlos gezeigt.
• Bilder: ein relativer Pfad wird gegen den Ordner der Datei gelesen (oder is_base_path für einen Text); für ein Bild aus dem Web lieber https://, oder es zuerst herunterladen (restclient.of_download) und seinen Pfad angeben. ib_remote_pictures auf false lädt keines.
• Eine Datei wird im Hintergrund gelesen: nach is_source auf ue_loaded warten, um das Inhaltsverzeichnis zu lesen; ein Anker und eine Suche, die inzwischen verlangt werden, warten auf die Datei.
• Ein großes Dokument bleibt flüssig: die ersten Blöcke erscheinen sofort, der Rest in den folgenden Augenblicken; die Suche (höchstens 50.000 Vorkommen), of_scroll_to und der Druck warten, bis es vollständig ist.
• Von rechts nach links: das Dokument folgt der Richtung der Anwendung (Listen, Zitate und Tabellen drehen sich um), ein Codeblock bleibt von links nach rechts, und eine vom Autor ausgerichtete Spalte (:--, --:) behält ihre Seite.

Vom gemeinsamen Sockel geerbt #

Diese Mitglieder gibt es bei jeder visuellen Komponente — sie sind nicht dieser eigen. Sie werden einmal in den übergreifenden Kapiteln beschrieben; diese Tabelle sagt nur, wo man sie liest.

← Komponentenreferenz · Inhalt des Handbuchs