markdownview — u_pbt_markdownview #

← Référence des composants · Sommaire du guide

markdownview affiche un document Markdown en lecture seule, aux couleurs du thème : titres, listes, tableaux, listes de tâches, code coloré, images. Vous posez le texte dans is_markdown, ou le chemin d'un fichier dans is_source ; un lien ne navigue jamais, il lève ue_link_clicked et c'est l'application qui décide. Le HTML brut d'un document n'est jamais exécuté.

▶ Le voir en vrai — Application de démonstration, tuile Markdown viewer, avec le code et cette page côte à côte.

En bref #

Démarrage rapide #

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

Propriétés #

Méthodes #

Événements #

Exemple #

Une aide en ligne qui ouvre ses liens #

Un document vient souvent d'ailleurs : le tri se fait sur la nature du lien, jamais sur son texte. Une page Web ou un courriel s'ouvrent dans leur programme, un autre document s'affiche dans le même composant, et un fichier — un .exe, un .bat — n'est jamais lancé sans demander.

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

Éditer du Markdown : un codeeditor et un markdownview #

Le visualiseur garde sa position de lecture quand le texte change : on édite la fin d'un long document sans que l'aperçu remonte en haut.

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

Une table des matières dans une liste #

Pour un fichier posé par is_source, remplissez la liste dans ue_loaded : avant, le fichier est encore en lecture.

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

Une liste de contrôle que l'utilisateur coche #

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

Le composant ne réécrit jamais le texte lui-même : l'application garde la main sur ce qu'elle enregistre.

Rouvrir un document là où le lecteur l'a laissé #

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

Bonnes pratiques #

• C'est un lecteur, pas un éditeur : pour écrire du Markdown, un codeeditor en SYNTAX_MARKDOWN à côté, relié par une ligne dans son ue_changed (voir l'exemple) ; le visualiseur garde sa place quand le texte change.
• Les liens sont à vous : rien ne s'ouvre tout seul ; ue_link_clicked donne l'adresse, déjà résolue contre le dossier du fichier, et sa nature (as_kind) — triez sur elle, jamais sur le texte de l'adresse, et ne lancez jamais un LINK_FILE sans demander.
• Un document n'exécute rien : le HTML brut s'affiche tel qu'écrit (ou, avec ib_allow_html, seulement une courte liste de balises inertes), un lien javascript: reste du texte, une image http:// est refusée, une image d'un partage réseau aussi (ib_network_pictures) — un document venu d'ailleurs se montre sans risque.
• Les images : un chemin relatif se lit contre le dossier du fichier (ou is_base_path pour un texte) ; pour une image du Web, préférez https://, ou téléchargez-la d'abord (restclient.of_download) et donnez son chemin. ib_remote_pictures à false n'en charge aucune.
• Un fichier se lit en arrière-plan : après is_source, attendez ue_loaded pour lire la table des matières ; une ancre et une recherche demandées entre-temps attendent le fichier.
• Un gros document reste fluide : les premiers blocs s'affichent tout de suite, le reste dans les instants qui suivent ; la recherche (50 000 occurrences au plus), of_scroll_to et l'impression attendent qu'il soit entier.
• De droite à gauche : le document suit le sens de l'application (listes, citations et tableaux se retournent), un bloc de code reste de gauche à droite, et une colonne que l'auteur a alignée (:--, --:) garde son côté.

Hérité du socle commun #

Ces membres existent sur tous les composants visuels — ils ne sont pas propres à celui-ci. Ils sont détaillés une seule fois, dans les chapitres transverses ; cette table dit seulement où les lire.

← Référence des composants · Sommaire du guide