Skip to content
This repository was archived by the owner on Nov 7, 2026. It is now read-only.
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
16 changes: 10 additions & 6 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -43,7 +43,7 @@ The same text has four forms, and only the first two are meant to be edited by h
|---|---|---|
| **FieldWorks Markdown** (`*.fw.md`) | People, AI agents, files and diffs; Pandoc reads it the same way | Yes |
| **Record file** | A whole FieldWorks record: a YAML frame whose rich values are FieldWorks Markdown ([record files](docs/formats/record-files.md)) | Yes |
| **`Document`, `Paragraph`, `Run`** | The editor's model in memory: per run the text, writing system and property bag; per paragraph the host's key | No: the playground's "Model (debug)" tab dumps it |
| **`Document`, `Paragraph`, `Run`** | The editor's model in memory: per run the text, writing system and property bag; per paragraph the host's key | No: the playground's developer mode dumps it in its "Model (debug)" tab |
| **liblcm `ITsString`** | FieldWorks' storage; the LCModel adapter maps it to and from the run model | No |

**An agent's edit** is a text edit. Change the gloss and mark a vernacular word:
Expand All @@ -55,7 +55,7 @@ The same text has four forms, and only the first two are meant to be edited by h

The reader checks it: a malformed span or an unknown writing system is a finding with a line, a column and, where one exists, the exact
fix ([findings](docs/formats/findings.md)), and nothing is applied while there is an error. The host applies the rest as one undo step. In
the playground, edit the Markdown tab and press Apply; `MarkdownTabTests` makes this very edit.
the playground, edit the Markdown beside the field and press Apply; `MarkdownTabTests` makes this very edit.

## Why it's different

Expand Down Expand Up @@ -107,9 +107,13 @@ run winforms48 # WinForms form: TextBox, playground, TextBox (FieldWorks' sha
run desktop10 --scenario "Inline picture (ORC)"
```

`run.cmd` and `run.ps1` build the host and start it. The playground opens ready-made scenarios (bidi, Indic and Thai shaping, NFD, inline pictures, unknown properties, spelling, the
environment box, long documents). Beside the field, the Markdown tab shows the field as FieldWorks Markdown, which you can edit and apply,
and the Model tab shows its runs. The Pandoc tests need `pandoc` on `PATH`.
`run.cmd` and `run.ps1` build the host and start it. The playground shows what a person writing sees: a scenario picker, the field, and
beside it the field as FieldWorks Markdown, which you can edit and apply. Select some text and a small bar appears over it: bold, italic,
underline, writing system and character style, and under **More** the paragraph style and a picture. **Developer mode** (the check box, or
`--dev`) adds every switch, the model's runs and the event log. The scenarios: bidi, Indic and Thai shaping, NFD, inline pictures, unknown
properties, spelling, the environment box, long documents. The Pandoc tests need `pandoc` on `PATH`.

![The selection bar with More open, over French text](docs/images/selection-bar.png)

## Projects

Expand Down Expand Up @@ -150,7 +154,7 @@ Planned, not built:
- **The `fwmd` command-line checker** ([#161](https://github.com/sillsdev/SIL.TextEditing/issues/161)).
- **The FieldWorks Markdown clipboard form** ([#168](https://github.com/sillsdev/SIL.TextEditing/issues/168)).
- **Editor integration**: an inline WYSIWYG and Markdown source mode, and a VS Code extension with a language server. The playground's
Markdown tab is a host-side sketch of the source mode. The plan and a proposed ADR are awaiting owner decisions ([#170](https://github.com/sillsdev/SIL.TextEditing/issues/170)).
Markdown pane is a host-side sketch of the source mode. The plan and a proposed ADR are awaiting owner decisions ([#170](https://github.com/sillsdev/SIL.TextEditing/issues/170)).
- **Retiring the liblcm refusals** once FieldWorks pins a liblcm with its fixes [#410](https://github.com/sillsdev/liblcm/issues/410), [#413](https://github.com/sillsdev/liblcm/issues/413) and [#414](https://github.com/sillsdev/liblcm/issues/414) ([#159](https://github.com/sillsdev/SIL.TextEditing/issues/159)).

## Contributing
Expand Down
5 changes: 3 additions & 2 deletions docs/images/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -10,11 +10,12 @@ Rendered by `tests/SIL.TextEditing.Playground.Tests/ScreenshotGenerator.cs`: a 1
$env:TEXTEDITING_SCREENSHOTS=1; dotnet test tests\SIL.TextEditing.Playground.Tests -c Release -f net10.0 --filter ScreenshotGenerator
```

- `bidi-selection.png`: Latin and Arabic in one paragraph, one selection running across the direction changes ("Latin and Arabic" scenario), with the same text as FieldWorks Markdown in the Markdown tab.
- `bidi-selection.png`: Latin and Arabic in one paragraph, one selection running across the direction changes ("Latin and Arabic" scenario), the selection bar over it, and the same text as FieldWorks Markdown beside it.
- `selection-bar.png`: the selection bar over French text with More open: bold, italic, underline, writing system, character style, then paragraph style and Picture.
- `indic-thai-shaping.png`: Hindi, Tamil and Thai shaped correctly, with a Devanagari conjunct selected as one cluster.
- `nfd-surrogates.png`: composed and decomposed accents, stacked marks, and emoji (surrogate pairs and a ZWJ family), with the emoji selected.
- `inline-pictures.png`: inline picture objects (U+FFFC) in left-to-right and right-to-left text, selected along with the text around them.
- `unknown-properties-inspector.png`: runs that carry properties the editor does not understand (9001, 9002), a paragraph style and a character style, and the Model tab showing the runs and their property numbers.
- `unknown-properties-inspector.png`: runs that carry properties the editor does not understand (9001, 9002), a paragraph style and a character style, and, in developer mode, the Model tab showing the runs and their property numbers.
- `environment-box.png`: the phonological-environment box, one line with coloured chips and a squiggle on a class the language service rejects.
- `environment-fix-menu.png`: right-click on a problem in the environment box: the service's message, its fix ("Insert the closing parenthesis") and the Insert items.
- `spelling-squiggles.png`: red squiggles on misspelled words, blue on a word that glues two writing systems, nothing on do-not-check or read-only text.
Expand Down
Binary file modified docs/images/bidi-selection.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file modified docs/images/block-features.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
2 changes: 1 addition & 1 deletion docs/images/capture-hosts.ps1
Original file line number Diff line number Diff line change
Expand Up @@ -10,7 +10,7 @@
param(
[string]$Scenario = 'Latin and Arabic',
[int]$Width = 1280,
[int]$Height = 800
[int]$Height = 700 # fits a 768-pixel-high screen at y=20; a window that runs off the screen copies blank pixels
)
$ErrorActionPreference = 'Stop'
$root = (Resolve-Path (Join-Path $PSScriptRoot '..\..')).Path
Expand Down
Binary file modified docs/images/copy-as-submenu.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file modified docs/images/desktop-window.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file modified docs/images/environment-box.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file modified docs/images/environment-fix-menu.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file modified docs/images/host-winforms-fieldworks-shape.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file modified docs/images/indic-thai-shaping.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file modified docs/images/inline-pictures.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file modified docs/images/long-document.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file modified docs/images/many-fields.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added docs/images/selection-bar.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file modified docs/images/spelling-context-menu.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file modified docs/images/spelling-squiggles.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file modified docs/images/unknown-properties-inspector.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
11 changes: 8 additions & 3 deletions docs/manual-testing.md
Original file line number Diff line number Diff line change
Expand Up @@ -25,7 +25,12 @@ Where a step says **all hosts**, do it on each of the three and write one result

## The window

* **Top**: scenario picker; field count (for the Many fields scenario); **B I U**; Undo, Redo; Picture, Cut, Copy,
Turn on **Developer mode** (the check box at the top right, or start the host with `--dev`): most steps below use its controls. Without it
the window shows only the scenario picker, the field, the selection bar and the Markdown.

* **Selection bar**: select text and it appears above the selection: **B I U**, the writing system, the character style, and under
**More** the paragraph style and Picture. It never takes focus from the field and goes away when the selection does.
* **Top** (developer mode): field count (for the Many fields scenario); **B I U**; Undo, Redo; Picture, Cut, Copy,
Paste. The toolbar never takes focus from the field.
* **Writing-system bar**: `ws:` shows the writing system at the caret. Default analysis (en) and default vernacular
(swh) buttons, then every sample writing system: en, fr (analysis) and ar, swh, hi, ta, th (vernacular). With a
Expand All @@ -36,7 +41,7 @@ Where a step says **all hosts**, do it on each of the three and write one result
Apply to put it in the field as one undo step; an error, read-only text or a second paragraph in a single-paragraph field changes nothing
and says why. Revert shows the field again.
* **Model tab** (beside the Markdown tab; click it for the steps below that read the model): caret, anchor and selection as paragraph:offset; undo counts; every paragraph with its key (`(none)` until the host assigns one),
direction, style and runs. A run reads `r1 [9,13) ws=ar "text" props{3=1, 9001=42@1}`: offsets, writing system,
direction, style and runs. A run reads `r1 [9,13) ws=ar "text" props{3=1@3, 9001=42@1}`: offsets, writing system,
text with escapes (`́` a combining mark, `\U0001F600` a surrogate pair, `` an object), then the property
bag as `number=value`, `@n` for a variation. Documents over 30 paragraphs show a window around the caret.
* **Event log** (bottom right): `caret ws en -> ar: would switch keyboard to ar` (the library only reports; it never
Expand All @@ -52,7 +57,7 @@ Where a step says **all hosts**, do it on each of the three and write one result
| 1.4 | Put a caret in English text, click the `fr` button, type `bonjour`. | `ws: fr`; the typed text is a new run `ws=fr` in the Model tab. | | | | |
| 1.5 | Click Default vernacular, type `habari`; then Default analysis. | `ws: swh`, then `ws: en`; run `ws=swh "habari"` in the Model tab. | | | | |
| 1.6 | Select a word with Shift+Right, click the `hi` button. | Only the selected text becomes `ws=hi` and is drawn in the Hindi font; the selection stays. Undo restores it. | | | | |
| 1.7 | Select a word, press B, then B again; then Ctrl+I and Ctrl+U. | Bold, italic, underline are drawn; the Model tab shows `props{3=1}` (bold), `2=1` (italic), `5=1` (underline); pressing B again removes it and the runs merge back. Paragraph keys do not change. | | | | |
| 1.7 | Select a word, press B, then B again; then Ctrl+I and Ctrl+U. | Bold, italic, underline are drawn; the Model tab shows `props{3=1@3}` (bold), `2=1@3` (italic), `5=1@3` (underline), and the Markdown tab `**word**`, `*word*` and `[word]{underline=single}`; pressing B again removes it and the runs merge back. Paragraph keys do not change. | | | | |
| 1.8 | Type, press Undo, Undo, Redo, Redo. Then Ctrl+Z and Ctrl+Y in the field. | Text, caret and the Model tab's `undo n done, n undone` follow; the log says `undo requested (button)` or `(Ctrl+Z in the field)`. | | | | |
| 1.9 | Press Enter in the middle of a paragraph, then Backspace at the start of the new one. | Two paragraphs, then one. The first keeps its key on a split and on the join; the new right-hand paragraph has `key=(none)` until the host assigns one (compare in the Model tab). | | | | |
| 1.10 | Press Enter at the very start of a paragraph. | A new empty paragraph appears above; the new paragraph shows `key=(none)` and the original key stays on the paragraph that holds the text. | | | | |
Expand Down
8 changes: 5 additions & 3 deletions docs/reference/projects.md
Original file line number Diff line number Diff line change
Expand Up @@ -33,9 +33,11 @@ The `ITsString` adapter and the TsString XML clipboard form. See [The LCModel ad

Samples do not ship.

- **`samples/SIL.TextEditing.Playground`** (netstandard2.0, net10.0): the shared playground UI. A `RichTextField`, scenario picker,
writing-system bar, format and undo buttons, block-feature switches (tables, lists, headings; ADR 0033), a Markdown tab (the field as FieldWorks
Markdown, editable, applied as one undo step), a model tab and an event log. Both hosts and the integration tests use it.
- **`samples/SIL.TextEditing.Playground`** (netstandard2.0, net10.0): the shared playground UI. By default a scenario picker, the
`RichTextField`, a selection bar over the selection (bold, italic, underline, writing system, character style; under More the paragraph
style and a picture) and the field as FieldWorks Markdown, editable and applied as one undo step. Developer mode adds the writing-system bar,
format and undo buttons, block-feature switches (tables, lists, headings; ADR 0033), find and replace, a model tab and an event log. Both
hosts and the integration tests use it; the tests run in developer mode unless they test the default.
- **`samples/Playground.Desktop`** (net48, net10.0): plain Avalonia desktop app showing the playground. Avalonia 11.3.17 on net48, Avalonia
12 on net10.0 (Motif's shape).
- **`samples/Host48`** (net48): WinForms form hosting the playground through `WinFormsAvaloniaControlHost` between two WinForms TextBoxes,
Expand Down
4 changes: 2 additions & 2 deletions samples/Host48/Program.cs
Original file line number Diff line number Diff line change
Expand Up @@ -58,13 +58,13 @@ bool FieldWants(Keys keyData)
static class Program
{
/// <summary>FieldWorks' shape: a WinForms form, the playground embedded between two WinForms TextBoxes, to try Tab
/// and key handoff and focus. Options: <c>--scenario "name"</c>, <c>--minimized</c>.</summary>
/// and key handoff and focus. Options: <c>--scenario "name"</c>, <c>--dev</c> (developer mode), <c>--minimized</c>.</summary>
[STAThread]
static void Main(string[] args)
{
AppBuilder.Configure<PlaygroundApp>().UsePlatformDetect().LogToTrace().SetupWithoutStarting();
int s = Array.IndexOf(args, "--scenario");
var view = s >= 0 && s + 1 < args.Length ? new PlaygroundView(args[s + 1]) : new PlaygroundView();
var view = new PlaygroundView(s >= 0 && s + 1 < args.Length ? args[s + 1] : Scenarios.MixedBidi, args.Contains("--dev"));
var form = new Form
{
Text = "SIL.TextEditing playground in WinForms (net48, Avalonia " + PlaygroundApp.AvaloniaVersion + ")",
Expand Down
4 changes: 2 additions & 2 deletions samples/Playground.Desktop/Program.cs
Original file line number Diff line number Diff line change
Expand Up @@ -7,7 +7,7 @@

namespace SIL.TextEditing.Samples.PlaygroundDesktop
{
/// <summary>Options: <c>--scenario "name"</c> opens that scenario; <c>--minimized</c> starts minimized without
/// <summary>Options: <c>--scenario "name"</c> opens that scenario; <c>--dev</c> opens in developer mode; <c>--minimized</c> starts minimized without
/// taking focus (for smoke runs).</summary>
sealed class DesktopApp : PlaygroundApp
{
Expand All @@ -17,7 +17,7 @@ public override void OnFrameworkInitializationCompleted()
{
var args = desktop.Args ?? new string[0];
int s = Array.IndexOf(args, "--scenario");
var view = s >= 0 && s + 1 < args.Length ? new PlaygroundView(args[s + 1]) : new PlaygroundView();
var view = new PlaygroundView(s >= 0 && s + 1 < args.Length ? args[s + 1] : Scenarios.MixedBidi, args.Contains("--dev"));
var window = new Window
{
Title = "SIL.TextEditing playground (" + RuntimeLabel + ", Avalonia " + AvaloniaVersion + ")",
Expand Down
Loading
Loading