Add frame options to encourage scanning

[TheJoeFin]

Similar to how other QR Codes have the option,
Things like

• Scan ME
• Scan here

Examples:

---

---

[TheJoeFin]

Implementation Plan

Context

This feature adds text frame labels ("Scan Me", "Scan Here", "Scan QR Code", or custom text) rendered directly into the QR code image — extending the image below the code. The label appears in the live preview and all exported formats (PNG, SVG, ZIP). The FrameLabel setting flows through the full rendering pipeline the same way QrPaddingModules does: ViewModel → render helpers → export service → history persistence.

---

Files to Modify

1. Helpers/BarcodeHelpers.cs

Add string? frameLabel = null to three methods:

• GetQrCodeBitmapFromText() — preview bitmap
• SaveQrCodePngToStream() — PNG export
• CreateQrCodeBitmap() (private) — core renderer

At the end of CreateQrCodeBitmap(), after the logo overlay, call a new private helper if frameLabel is non-empty:

if (!string.IsNullOrWhiteSpace(frameLabel))
    return AddTextLabelToBitmap(bitmap, frameLabel, foreground, background);

New private method AddTextLabelToBitmap():

• Creates a taller Bitmap: same width, height = QR height + text area
• Text area height = measured text height + ~20% vertical padding each side
• Fills text area with background color
• Draws text horizontally centered using foreground color
• Font: "Segoe UI", Bold, ~12% of bitmap width in pixels, GraphicsUnit.Pixel
• Uses TextRenderingHint.AntiAlias
• Returns new Bitmap; caller's using block disposes the original

For SVG (GetSvgQrCodeForText()): add string? frameLabel = null. If non-empty, post-process the SVG string to extend the viewBox height and append a background <rect> + centered <text> element before </svg>.

2. Models/QrCodeDesignState.cs

public string? FrameLabel { get; init; }

3. Models/HistoryItem.cs

public string? FrameLabel { get; set; }

(nullable → backward-compatible with existing history JSON)

4. Models/QrRenderSettingsSnapshot.cs

Add string? FrameLabel to the private constructor, Create() factory, and as a public property.

5. Helpers/QrCodeDesignStateMapper.cs

• FromHistoryItem(): add FrameLabel = historyItem.FrameLabel
• ToHistoryItem(): add FrameLabel = state.FrameLabel
• ToBrandItem(): no change — frame labels are not part of brand presets

6. ViewModels/MainViewModel.cs

Property (alongside QrPaddingModules):

[ObservableProperty]
[NotifyPropertyChangedFor(nameof(FrameLabelButtonText))]
public partial string FrameLabel { get; set; } = string.Empty;

Computed property for the DropDownButton label:

public string FrameLabelButtonText => string.IsNullOrEmpty(FrameLabel) ? "Frame" : FrameLabel;

Changed handler (triggers debounce + persists):

partial void OnFrameLabelChanged(string value)
{
    debounceTimer.Stop();
    debounceTimer.Start();
    _ = LocalSettingsService.SaveSettingAsync(nameof(FrameLabel), value);
}

Preset command:

[RelayCommand]
private void SetFrameLabel(string label) => FrameLabel = label;

Other updates in MainViewModel:

• CreatePreviewItem(): pass frameLabel: FrameLabel
• CreateRenderSettingsSnapshot(): pass FrameLabel to QrRenderSettingsSnapshot.Create()
• CreateCurrentDesignState(): include FrameLabel = FrameLabel
• ApplyDesignState(): set FrameLabel = state.FrameLabel ?? string.Empty
• LoadSettingsAsync(): add FrameLabel = await LocalSettingsService.ReadSettingAsync<string>(nameof(FrameLabel)) ?? string.Empty;

7. Services/QrExportService.cs

• RenderRequestedCodePngBytesAsync(): pass renderSettings.FrameLabel to SaveQrCodePngToStream()
• GetRequestedCodeAsSvgTextAsync(): pass renderSettings.FrameLabel to GetSvgQrCodeForText()

8. Views/MainPage.xaml

Add a DropDownButton to the QrCodeOptions horizontal StackPanel (after BrandManagementControl):

<DropDownButton ToolTipService.ToolTip="Scan Frame Label" MinWidth="80">
    <TextBlock Text="{x:Bind ViewModel.FrameLabelButtonText, Mode=OneWay}" />
    <DropDownButton.Flyout>
        <Flyout Placement="Bottom">
            <StackPanel Spacing="4" MinWidth="180">
                <Button Content="No Frame"
                        Command="{x:Bind ViewModel.SetFrameLabelCommand}"
                        CommandParameter=""
                        HorizontalAlignment="Stretch" HorizontalContentAlignment="Left" />
                <Button Content="Scan Me"
                        Command="{x:Bind ViewModel.SetFrameLabelCommand}"
                        CommandParameter="Scan Me"
                        HorizontalAlignment="Stretch" HorizontalContentAlignment="Left" />
                <Button Content="Scan Here"
                        Command="{x:Bind ViewModel.SetFrameLabelCommand}"
                        CommandParameter="Scan Here"
                        HorizontalAlignment="Stretch" HorizontalContentAlignment="Left" />
                <Button Content="Scan QR Code"
                        Command="{x:Bind ViewModel.SetFrameLabelCommand}"
                        CommandParameter="Scan QR Code"
                        HorizontalAlignment="Stretch" HorizontalContentAlignment="Left" />
                <TextBox Header="Custom"
                         Text="{x:Bind ViewModel.FrameLabel, Mode=TwoWay, UpdateSourceTrigger=PropertyChanged}"
                         PlaceholderText="Custom label..." />
            </StackPanel>
        </Flyout>
    </DropDownButton.Flyout>
</DropDownButton>

---

Execution Order

1. BarcodeHelpers.cs — rendering logic first (independently testable)
2. QrCodeDesignState.cs, HistoryItem.cs, QrRenderSettingsSnapshot.cs — data models
3. QrCodeDesignStateMapper.cs — history ↔ state mapping
4. MainViewModel.cs — property, command, settings, call-site updates
5. QrExportService.cs — pass-through to export methods
6. MainPage.xaml — UI last (requires ViewModel changes to compile)

---

Verification Checklist

• Set "Scan Me" from flyout → QR preview updates with text below
• Enter custom text → debounce fires, preview updates
• Clear to "No Frame" → QR is square again
• Export PNG → label present in saved file
• Export SVG → label present in SVG output
• Save to history → reload from history restores the label
• Restart app → FrameLabel remembered from LocalSettings
• Existing history JSON without FrameLabel loads without error (null → no label)