ZFX + Developia

Code: Alles auswählen

# QR Code Generator — Documentation

## Overview

A self-contained, fully offline desktop application for generating QR codes.
Built with Flutter (Windows primary target). No network access is required at
any point; all encoding and rendering happens in-process.

---

## Features

### QR Types

Six content types are supported. Selecting a type swaps the input fields
immediately; all field values are retained in memory while the app is open so
switching back does not erase previous input.

| Type | Fields | Encoded format |
|------|--------|----------------|
| **URL / Website** | URL | Raw URL string (`https://…`) |
| **Plain Text** | Multi-line text area | Raw string |
| **Phone** | Phone number | `tel:<number>` URI |
| **Wi-Fi** | SSID, Password, Security (WPA/WPA2, WEP, None) | `WIFI:T:<sec>;S:<ssid>;P:<pw>;;` |
| **Contact (vCard)** | First/Last name, Phone, Email, Organisation | vCard 3.0 block (`BEGIN:VCARD … END:VCARD`) |
| **Location** | Latitude, Longitude | `geo:<lat>,<lng>` URI |

### Live Preview

The QR code re-renders automatically on every keystroke — no generate button.
This is achieved by attaching an `addListener(() => setState(…))` callback to
every `TextEditingController` at initialisation time
(`_HomePageState._c`, `home_page.dart:48–51`). An empty-data guard in
`_qrData` (`home_page.dart:61–86`) returns an empty string when the minimum
required fields are blank, which causes the preview panel to show a placeholder
instead of an invalid QR code.

### Output Size

A slider (200 – 1000 px, 16 steps) controls the pixel dimensions of the saved
PNG. The preview scales proportionally: `_displaySize = (_saveSize * 0.38)
.clamp(160, 244)` (`home_page.dart:89`), so moving the slider visibly resizes
the preview as well.

### Error Correction Level

A four-segment button selects the Reed-Solomon error correction level passed
directly to `QrPainter` / `QrImageView`:

| Level | Data recovery |
|-------|---------------|
| L | ~7 % |
| M | ~15 % (default) |
| Q | ~25 % |
| H | ~30 % |

Higher levels produce denser codes. M is the default because it balances
scannability with damage tolerance for typical print use-cases.

### 10 % White Border

Every saved PNG includes a white quiet-zone border equal to 10 % of the output
dimension on each side (`home_page.dart:117–118`):

```
border  = saveSize × 0.1
qrArea  = saveSize − 2 × border   (= 80 % of saveSize)
```

The QR painter is translated by `(border, border)` before painting so the code
sits centred inside the margin. This quiet zone is part of the QR standard and
improves reliable scanning, particularly when the image is printed without
additional margins.

### Text Label Option

A checkbox ("Print content as text below code") appends the raw encoded string
as a human-readable caption. The feature affects both the live preview and the
saved file.

**Preview** (`_PreviewPanel.build`, `home_page.dart:642–654`): a `Text` widget
is conditionally inserted below the QR container; it wraps to three lines
maximum with ellipsis overflow.

**Saved PNG** (`_HomePageState._save`, `home_page.dart:120–141`): the text is
pre-laid-out with `dart:ui`'s `ParagraphBuilder` before the canvas is created,
so the required extra height is known upfront. The total image height becomes:

```
totalHeight = saveSize + textGap + paragraph.height + textGap
```

Font size scales with output size (`saveSize × 0.044`) and the text is
constrained to the same horizontal margins as the QR code itself (`qrArea`
width), ensuring alignment.

### Save as PNG

Clicking **Save as PNG** opens the platform's native *Save File* dialog
(`FilePicker.platform.saveFile`, `home_page.dart:96–101`). The dialog
pre-populates the filename with `qr_<type>.png` (e.g. `qr_url.png`,
`qr_wifi.png`) derived from the enum name. The folder picker is shown
**before** the spinner starts so a cancellation never triggers any rendering
work. A `.png` extension is appended defensively if the user removes it
(`home_page.dart:103`).

Rendering uses `dart:ui` directly rather than a screenshot widget:

1. `QrPainter` encodes the data and provides a `paint(Canvas, Size)` method.
2. A `ui.PictureRecorder` / `Canvas` pair captures all draw calls off-screen.
3. The white background, the QR code (translated into the border area), and
   optionally the text paragraph are all drawn onto this canvas.
4. `picture.toImage(w, h)` rasterises to a `ui.Image`.
5. `image.toByteData(format: png)` produces the final bytes written to disk.

---

## Design Decisions

### Single-page, no navigation

Everything lives on one screen. The separation between "input" and "output" is
handled spatially (left / right columns) rather than with tabs or navigation
routes. This matches the typical usage pattern: the user iterates on the
content while watching the code update.

### Two-column layout

The body is a `Row` with an `Expanded` scrollable left column and a fixed-width
(292 px) right column separated by a `VerticalDivider`
(`_HomePageState.build`, `home_page.dart:201–258`). The right column is not
inside a `ScrollView`, so the QR preview and Save button remain permanently
visible regardless of how tall the left column's content grows (e.g. vCard
with five fields).

### All state in one StatefulWidget

`_HomePageState` owns every piece of mutable state: selected type, all text
controllers, all settings. Child widgets (`_InputCard`, `_SettingsCard`,
`_PreviewPanel`) are `StatelessWidget`s that receive data and callbacks. This
keeps the data flow explicit and avoids the complexity of shared state
management packages for an app of this scale.

### Single flat controller map

All `TextEditingController` instances live in one `Map<String, TextEditingController>`
keyed by short string identifiers (`_keys` / `_c`, `home_page.dart:40–51`).
Controllers are created eagerly for all types at startup; unused ones simply
hold empty strings. This avoids creating/disposing controllers on type changes
and keeps the input state alive when the user switches types back and forth.

### Offline-first, no state persistence

No data is written to disk except when the user explicitly saves. There is no
preferences file, no history, and no auto-save. This keeps the app simple and
predictable — what you see is what you get.

### dart:ui canvas for PNG rendering

Flutter's widget tree cannot be trivially serialised to a PNG at arbitrary
resolution. Instead, `QrPainter` (the lower-level primitive exposed by
`qr_flutter`) is used directly with a `PictureRecorder` canvas. This gives
full control over image dimensions, border, and text placement without
depending on `RepaintBoundary` captures (which are tied to the display's device
pixel ratio) or screenshot packages.

### Preview size linked to output size

`_displaySize` is a linear function of `_saveSize` rather than a fixed
constant. This gives the user immediate visual feedback that moving the slider
changes the resolution — smaller slider value → smaller preview, larger slider
value → larger preview. The clamp (160 – 244 px) prevents the preview from
becoming uselessly tiny or overflowing the right column.

### No colour customisation

Foreground/background colour pickers were removed after initial prototyping.
The QR is always black on white. This is the combination with the highest
contrast and the most reliable scanning across lighting conditions and scanner
implementations. Offering colour options would add UI complexity with little
practical benefit for the core use-case.

---

## Dependencies

### `qr_flutter ^4.1.0`

QR encoding and rendering. Two components are used:

- **`QrImageView`** — Flutter widget used in the live preview. Handles
  encoding and painting internally; re-renders when its `data` property changes.
- **`QrPainter`** — Lower-level `CustomPainter` used during PNG export. Exposes
  a `paint(Canvas, Size)` method that integrates with the `dart:ui` recorder
  pipeline.
- **`QrErrorCorrectLevel`** — Integer constants (`L=1, M=0, Q=3, H=2`) that map
  to the segmented button values.
- **`QrVersions.auto`** — Lets the library choose the smallest QR version that
  fits the data.

No network access. The library is pure Dart with platform-native canvas
rendering.

### `file_picker ^8.1.7`

Native file system dialogs. Only one method is used:

- **`FilePicker.platform.saveFile(...)`** — Opens the OS *Save As* dialog,
  returning the full path chosen by the user, or `null` if cancelled.

On Windows this invokes the Win32 `GetSaveFileName` common dialog. The package
handles the platform channel plumbing; no additional Windows-specific setup is
required beyond the package registration that Flutter's build system handles
automatically.

### `flutter` (SDK)

- **`dart:ui`** — Low-level graphics primitives: `PictureRecorder`, `Canvas`,
  `ParagraphBuilder`, `ParagraphStyle`, `TextStyle`, `ImageByteFormat`. Used
  exclusively in `_save()` for off-screen PNG rendering.
- **`dart:io`** — `File.writeAsBytes()` for writing the final PNG to disk.
- **Material 3** widget library for all UI components.

### `cupertino_icons ^1.0.8`

Pulled in by the default Flutter template; not actively used (all icons come
from the Material icon font).

---

## File Structure

```
lib/
  main.dart        — App entry point, MaterialApp, theme configuration
  home_page.dart   — All application logic and UI widgets

windows/
  runner/
    main.cpp       — Win32 entry point; sets initial window size (800 × 580)

pubspec.yaml       — Dependencies and SDK constraints
```

---

## Key Identifiers Reference

| Identifier | File : line | Purpose |
|------------|-------------|---------|
| `QrType` enum | `home_page.dart:10` | Defines the six supported content types with display label and icon |
| `_HomePageState._type` | `home_page.dart:33` | Currently selected QR type |
| `_HomePageState._saveSize` | `home_page.dart:34` | Output PNG dimension in pixels (200–1000) |
| `_HomePageState._errorLevel` | `home_page.dart:35` | Reed-Solomon error correction level |
| `_HomePageState._wifiSecurity` | `home_page.dart:36` | Wi-Fi security protocol string (`WPA`, `WEP`, `nopass`) |
| `_HomePageState._showLabel` | `home_page.dart:37` | Whether to render the content string as text in the output |
| `_HomePageState._keys` | `home_page.dart:40` | All controller map keys; controllers are created for every key at startup |
| `_HomePageState._c` | `home_page.dart:48` | Flat map of all `TextEditingController`s; each triggers `setState` on change |
| `_HomePageState._qrData` | `home_page.dart:61` | Computed getter: assembles the type-appropriate QR payload string |
| `_HomePageState._displaySize` | `home_page.dart:89` | Preview render size derived from `_saveSize` |
| `_HomePageState._save()` | `home_page.dart:91` | Full save pipeline: dialog → encode → render → write |
| `_TypeSelector` | `home_page.dart:265` | Horizontal scrolling chip row for type selection |
| `_InputCard._fields()` | `home_page.dart:336` | Returns the correct set of input widgets for the active type |
| `_SettingsCard` | `home_page.dart:452` | Output size slider, error correction selector, label checkbox |
| `_PreviewPanel` | `home_page.dart:567` | Right-column widget: QR preview container, optional label text, Save button |
| `QrCodeGeneratorApp` | `main.dart:8` | Root widget; owns the `MaterialApp` and theme |
| Seed colour | `main.dart:18` | `Color(0xFF1565C0)` — Material Blue 800; drives the entire M3 colour scheme |
| Window size | `windows/runner/main.cpp:29` | `Win32Window::Size(800, 580)` |