markdownview — u_pbt_markdownview #

← Referência dos componentes · Índice do guia

markdownview mostra um documento Markdown só de leitura, com as cores do tema: títulos, listas, tabelas, listas de tarefas, código colorido, imagens. Define o texto em is_markdown, ou o caminho de um ficheiro em is_source; uma ligação nunca navega, levanta ue_link_clicked e é a aplicação que decide. O HTML em bruto de um documento nunca é executado.

▶ Ver ao vivo — Aplicação de demonstração, mosaico Markdown viewer, com o código e esta página lado a lado.

Em resumo #

Início rápido #

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

Propriedades #

Métodos #

Eventos #

Exemplo #

Uma ajuda em linha que abre as suas ligações #

Um documento vem muitas vezes de fora: a triagem faz-se pela natureza da ligação, nunca pelo seu texto. Uma página Web ou um e-mail abrem-se no seu programa, outro documento mostra-se no mesmo componente, e um ficheiro — um .exe, um .bat — nunca é executado sem perguntar.

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

Editar Markdown: um codeeditor e um markdownview #

O visualizador mantém a posição de leitura quando o texto muda: edita-se o fim de um documento longo sem que a pré-visualização salte para o topo.

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

Um índice numa lista #

Para um ficheiro definido por is_source, preencha a lista em ue_loaded: antes, o ficheiro ainda está a ser lido.

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

Uma lista de verificação que o utilizador assinala #

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

O componente nunca reescreve o texto por si: a aplicação mantém o controlo sobre o que guarda.

Reabrir um documento onde o leitor o deixou #

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

Boas práticas #

• É um leitor, não um editor: para escrever Markdown, coloque ao lado um codeeditor em SYNTAX_MARKDOWN, ligado por uma linha no seu ue_changed (ver o exemplo); o visualizador mantém o seu lugar quando o texto muda.
• As ligações são suas: nada se abre sozinho; ue_link_clicked dá o endereço, já resolvido em relação à pasta do ficheiro, e a sua natureza (as_kind) — faça a triagem por ela, nunca pelo texto do endereço, e nunca execute um LINK_FILE sem perguntar.
• Um documento não executa nada: o HTML em bruto é mostrado tal como está escrito (ou, com ib_allow_html, apenas uma lista curta de etiquetas inertes), uma ligação javascript: continua a ser texto, uma imagem http:// é recusada, tal como uma imagem numa partilha de rede (ib_network_pictures) — um documento vindo de fora mostra-se sem risco.
• As imagens: um caminho relativo lê-se em relação à pasta do ficheiro (ou is_base_path para um texto); para uma imagem da Web, prefira https://, ou descarregue-a primeiro (restclient.of_download) e indique o seu caminho. ib_remote_pictures a false não carrega nenhuma.
• Um ficheiro lê-se em segundo plano: depois de is_source, espere por ue_loaded para ler o índice; uma âncora e uma pesquisa pedidas entretanto esperam pelo ficheiro.
• Um documento grande continua fluido: os primeiros blocos aparecem logo, o resto nos instantes seguintes; a pesquisa (no máximo 50 000 ocorrências), of_scroll_to e a impressão esperam que esteja completo.
• Da direita para a esquerda: o documento segue o sentido da aplicação (listas, citações e tabelas viram-se), um bloco de código continua da esquerda para a direita, e uma coluna que o autor alinhou (:--, --:) mantém o seu lado.

Herdado da base comum #

Estes membros existem em todos os componentes visuais — não são próprios deste. São detalhados uma só vez, nos capítulos transversais; esta tabela apenas diz onde os ler.

← Referência dos componentes · Índice do guia