MarkdownHelp.Avalonia 0.1.0-alpha.6

MarkdownHelp.Avalonia

Avalonia 애플리케이션에서 같은 Markdown 문서를 본문, 툴팁, 별도 도움말 창으로 표시하는 재사용 라이브러리다.

제공 기능

• 문자열, 파일, avares:// 리소스에서 Markdown 읽기
• 문서 기준 상대경로 이미지 표시
• PNG 파일을 거치지 않고 공통 Skia vector frame을 직접 그리는 MarkdownHelpView
• 다른 프레임워크와 같은 SetFrame/SetZoom 계약으로 사용할 수 있는 SkiaMarkdownCanvas
• 포인터 진입·스크롤·크기 조절이 가능한 지연 로딩 MarkdownHelpToolTip
• 소유 창을 지정할 수 있는 MarkdownHelpWindow
• 번호 표식과 Markdown 설명을 제공하는 MarkdownGuideOverlay
• 첫 실행 상태를 메모리 또는 JSON 파일에 저장하는 IMarkdownGuideStateStore

가이드의 탐색·완료 저장·카드 배치는 MarkdownHelp.Core에 있고 Avalonia, WPF, WinUI, Uno 오버레이가 같은 IMarkdownGuideOverlay 계약을 구현한다.

사용 예

using MarkdownHelp.Avalonia;

var source = MarkdownHelpSource.FromResource(
    "avares://YourApp/Help/settings.md");

MarkdownHelpToolTip.Attach(infoButton, source);
MarkdownHelpWindow.Show(source, "설정 도움말", ownerWindow);

renderer를 직접 소유하는 reader에서는 frame 기반 API를 사용할 수 있다.

using var renderer = new MarkdownHelp.Skia.SkiaMarkdownRenderer();
var canvas = new SkiaMarkdownCanvas();
canvas.SetFrame(renderer.CreateFrame(markdown, 900), zoom: 1);
canvas.SetZoom(1.5f);

프로그램 시작 안내

왜 필요한가

MarkdownHelpToolTip은 한 컨트롤의 짧은 설명에 적합하고, MarkdownHelpWindow는 사용자가 찾아서 읽는 긴 설명서에 적합하다. 하지만 처음 보는 화면에서는 어느 컨트롤부터 어떤 순서로 확인해야 하는지 알기 어렵다. 별도 설명서의 캡처 화면은 실제 UI가 바뀌면 위치 설명도 낡는다.

MarkdownGuideOverlay는 실행 중인 화면의 실제 컨트롤을 기준으로 다음 정보를 한 화면에 묶는다.

• 반투명 막과 강조 테두리로 현재 대상을 구분한다.
• 번호 표식으로 전체 순서와 현재 단계를 보여준다.
• 각 단계의 Markdown 문서로 목록, 표, 주의문과 이미지를 표시한다.
• 이전·다음·완료와 키보드 방향키·Enter·Escape를 지원한다.
• 첫 실행 완료 상태를 저장해 매번 작업을 방해하지 않으면서, 사용자가 원할 때는 다시 열 수 있다.

따라서 최초 실행 안내, 새 기능 소개, 여러 설정을 순서대로 확인해야 하는 화면에 적합하다. 한 단추의 의미만 설명하면 되는 경우에는 오버레이보다 툴팁이 단순하다.

구성 요소

적용 방법

대상 컨트롤과 오버레이는 같은 화면 트리에 있어야 한다. 오버레이를 루트 Grid의 마지막 자식으로 추가하면 기존 화면 위에 표시된다.

var stateFilePath = Path.Combine(
    Environment.GetFolderPath(Environment.SpecialFolder.LocalApplicationData),
    "MarkdownHelp.Avalonia.GuideDemo",
    "guide-state.json");
var store = new JsonFileMarkdownGuideStateStore(stateFilePath);

var guide = new MarkdownGuideOverlay(
[
    new MarkdownGuideStep(
        inlineViewButton,
        "화면 안에서 읽으세요",
        MarkdownHelpSource.FromResource(
            "avares://MarkdownHelp.Avalonia.GuideDemo/Help/inline-view.md"),
        "본문 보기를 누릅니다."),
    new MarkdownGuideStep(
        tooltipButton,
        "필요할 때 펼쳐 보세요",
        MarkdownHelpSource.FromResource(
            "avares://MarkdownHelp.Avalonia.GuideDemo/Help/tooltip.md"),
        "툴팁 보기를 누릅니다.")
]);

rootGrid.Children.Add(guide);
window.Opened += (_, _) => guide.ShowOnce("markdown-help-guide:v1", store);
replayButton.Click += (_, _) => guide.Show();
resetButton.Click += (_, _) => store.Reset("markdown-help-guide:v1");

적용 순서는 다음과 같다.

1. 각 대상에 대응하는 Markdown 문서를 리소스나 파일로 준비한다.
2. 대상 컨트롤과 문서를 MarkdownGuideStep으로 묶는다.
3. 만든 MarkdownGuideOverlay를 루트 Grid의 마지막 자식으로 추가한다.
4. 창의 Opened에서 ShowOnce를 호출한다. 이 시점에는 대상 배치가 끝나 표식 좌표를 계산할 수 있다.
5. 도움말 메뉴나 설정 화면의 다시 보기 단추에서 Show()를 호출한다.

첫 실행과 다시 보기 정책

• ShowOnce(key, store)는 저장소에 키가 없을 때만 열리고, 실제로 열었으면 true를 반환한다.
• 완료, 안내 닫기, Escape는 해당 키를 본 상태로 기록한다.
• Show()는 저장 상태를 검사하지 않으므로 언제든 수동으로 다시 볼 수 있다.
• Reset(key)은 저장된 상태를 지운다. 다음 ShowOnce 또는 다음 실행부터 안내가 다시 열린다.
• 안내 내용이 크게 바뀌어 기존 사용자에게 다시 보여야 할 때는 markdown-help-guide:v2처럼 키 버전을 올린다.

배치와 문서 길이

기본 카드 높이는 MarkdownGuideOverlay.DefaultCardHeight인 500px이다. Markdown 본문만 남은 영역에서 스크롤되므로 단계별 문서 길이가 달라도 이전·다음·완료 버튼 위치는 움직이지 않는다. 카드 높이를 바꿔야 하면 표시 전에 guide.GuideCard.Height를 설정한다.

안내 카드는 현재 대상의 반대편을 우선하고 화면 경계를 벗어나지 않도록 공통 배치 로직으로 조정한다. 기본 높이를 사용할 때는 카드와 상하 여백을 위해 콘텐츠 영역 높이 548px 이상을 권장한다. 대상은 오버레이와 같은 시각 트리에 연결되어 있고 화면에 배치된 Control이어야 표식 좌표를 계산할 수 있다.

시험

파일 상태를 남기지 않는 시험에는 InMemoryMarkdownGuideStateStore를 사용한다. 포함된 시험은 최초 한 번 표시, 닫은 상태 기록, 수동 다시 보기, 단계 이동, JSON 재시작 보존, 단계별 문서 길이가 달라도 탐색 버튼 Y좌표가 같은지를 확인한다. 전체 동작은 별도 예제에서 바로 볼 수 있다.

dotnet run --project examples/MarkdownHelp.Avalonia.GuideDemo

0.1.0-alpha.4부터 Markdown.Avalonia.Tight를 사용하지 않는다. MarkdownHelp.Skia가 만든 MarkdownRenderFrame을 Avalonia의 backend-owned SKCanvas에 직접 재생한다. 기본 폰트는 패키지에 포함되고 제품 렌더링 중 PNG나 임시 파일을 만들지 않는다.

0.1.0-alpha.5부터 frame 기반 SetFrame/SetZoom API를 공개해 WPF, WinUI, Uno adapter와 같은 IMarkdownFrameCanvas 계약으로 구성할 수 있다. frame 수명과 확대·논리 크기는 네 adapter가 모두 MarkdownCanvasSession으로 관리한다. 기존 Markdown 생성자와 MarkdownHelpView API는 유지한다.

이 변경으로 MarkdownHelpView.Viewer 형식은 MarkdownScrollViewer에서 SkiaMarkdownCanvas로 바뀌었다. 원문 확인은 MarkdownHelpView.Markdown, 최신 layout 진단은 Viewer.Frame을 사용한다. 링크 활성화, 부분 선택, 구조화된 접근성 tree는 정식 버전 전 남은 범위이므로 현재 패키지는 계속 alpha로 배포한다.

전체 예제는 공개 저장소의 examples 폴더에서 확인할 수 있다. 저장소 루트에서 다음 명령으로 실행한다.

dotnet run --project examples/MarkdownHelp.Avalonia.Demo
dotnet run --project examples/MarkdownHelp.Avalonia.GuideDemo