Skip to content

AGENTS.md

Latest commit

 

History

History
47 lines (41 loc) · 6.32 KB

AGENTS.md

File metadata and controls

47 lines (41 loc) · 6.32 KB
Raw

Repository Instructions

Project Overview

  • Qt 4.7 / QML 1.1 application for Symbian Belle, targeting Nokia C7-class devices with self-signed SIS deployment.
  • Generated from the qt-symbian-belle-starter template.
  • See docs/PLAN.md for milestones and docs/DEVICE_NOTES.md for the device experiment log.

Architecture

  • C++ managers in src/ are exposed to QML via setContextProperty in main.cpp: storage (StorageManager), memoryMonitor, tlsChecker, and audioEngine.
  • StatusNotifier (context property notifier, Symbian only) wraps the vendored Pigler Notifications API client in src/pigler/ to show status-panel notifications via showStatus(title, subtitle) and clearStatus().
  • StorageManager handles SQLite with a multi-candidate writable-path fallback.
  • QML uses Symbian Components 1.1. AppWindow.qml is the root, and pages live in qml/.
  • Qt 4 has no QJsonDocument; use the vendored lib/qjson library for native JSON.
  • See docs/QT4_SYMBIAN_PRACTICES.md for reusable networking, qrc, file URL, and device-verification practices.

Critical Symbian Rules

  • Never write the position property on a QML Audio element. This causes KErrMMAudioDevice (-12014) and can break all audio until the phone restarts. Drive playback through the C++ audioEngine with QMediaPlayer::setPosition().
  • Data caging: /private/<UID>/ directories are writable but invisible to QDir::exists(). Skip exists()/mkpath() checks and go straight to an I/O test.
  • SQL driver: prefer QSYMSQL over QSQLITE on Symbian. Tests should use the same driver as production code.
  • Path separators: use QDir::toNativeSeparators() for paths passed to SQL drivers on Symbian.
  • Hardware volume keys are RemCon media keys, not window-server key events. A QML Keys handler or RWindowGroup::CaptureKey sees nothing. Register a CRemConCoreApiTarget via CRemConInterfaceSelector::OpenTargetL() only after view.show() plus QApplication::processEvents(); registering before the window is foreground causes the first few presses to be silently dropped until focus re-resolves.
  • The app icon cache is sticky. Symbian's AppArc icon cache is keyed by UID and does not reliably refresh on a plain reinstall over an existing install, even with a version bump. A report that an icon fix "isn't showing up" needs a full uninstall, reboot, then reinstall — not a code re-diagnosis first.
  • The Simulator build excludes all #ifdef Q_OS_SYMBIAN code. A green build-simulator.ps1 run does not validate native Symbian-only code such as RemCon handling, data-caged paths, or QSYMSQL. Compile-check any Symbian-only edit with scripts/build-symbian.ps1 before requesting a device SIS build; this only proves compilation, not runtime behavior, and device round-trips are expensive.

QML 1.1 Compatibility Rules

  • No block expressions in property bindings. Use a helper function or ternary.
  • No named function declarations inside non-root elements. Declare functions only at the Page or root level.
  • No negative anchor margins. Size a larger Item for touch targets instead.
  • SVG icon sizing: Symbian renders icons using the SVG viewBox dimensions and ignores width/height. To resize, change both width/height and viewBox, wrapping paths in <g transform="scale(factor)">.
  • Use double, not qreal, for QML-facing numeric properties. On Symbian, qreal is float; moc encodes Q_PROPERTY(qreal ...) as QMetaType::QReal, which overflows RVCT4's signed metadata expression and emits warning #61-D. Keep the property, accessors, parameters, locals, and backing storage consistently typed as double.
  • font.pixelSize must be an int. A fractional value such as 12.5 throws Invalid property assignment: int expected at load time, which silently fails the entire containing page (Type <Page> unavailable), not just that element. Round fractional design sizes when porting.
  • New .qml files need a qml.qrc entry. QML loads from the Qt resource system, not the filesystem, so a file missing from qml/qml.qrc makes pageStack.push(...) or initialPage silently fail with "File not found" and no crash; the page simply never appears.
  • List and grid delegates need one full-delegate MouseArea. Anchor a single MouseArea to fill the whole delegate root, placed first so it sits behind the visual content, so taps anywhere on the row register. A partial hit target scoped to only part of the row reads as "not tappable" on a small screen.
  • Pair every openSoftwareInputPanel() call with a closeSoftwareInputPanel(). On Symbian the on-screen keyboard opens on a click reaching a TextInput, not on forceActiveFocus() alone, which is desktop/simulator-only behavior. If the panel is never explicitly closed on page exit, it stays "visible" and keeps reserving viewport height on the next page, clipping content underneath it.

Notifications (Pigler)

  • Status-panel notifications use the Pigler Notifications API (PNA), a separate on-device server the user installs (Pigler.sis from nnproject.cc/pna). The app degrades gracefully without it.
  • StatusNotifier (context property notifier) wraps the vendored QPiglerAPI (src/pigler/, from upstream piglerorg/pigler). All Pigler code is under #ifdef Q_OS_SYMBIAN; off-Symbian the class is a no-op so the simulator still builds.
  • Build: vendored sources plus LIBS += -lrandom -laknnotify go only in the symbian {} scope of BelleApp.pro; no extra capability needed.
  • Gotcha — removeOnTap: Pigler's server default is remove-on-tap, so a tap deletes the notification. For a persistent one, call setRemoveOnTap(id, false) (StatusNotifier already does this in showStatus()).
  • Gotcha — slots behind #ifdef: moc processes headers on every platform, but a slot declared inside #ifdef Q_OS_SYMBIAN is missing from the meta-object on other platforms, so a string-based connect(SIGNAL(...), SLOT(...)) wires up to nothing, silently, at runtime. Declare such slots unconditionally and guard only the body. Compile-checks (both simulator and ARM) will not catch this.

Device Experimentation Log

  • After any audio, media, or platform API experiment, record the result in docs/DEVICE_NOTES.md with a dated heading in the form ## YYYY-MM-DD - Title.
  • Include error codes and failed approaches in the log.
  • Read docs/DEVICE_NOTES.md before touching audio or media code because Symbian MMF behavior is fragile.