Coding Guidance Qt

Qt Coding Guidance

This skill adds portable Qt implementation, refactoring, and review guidance for Qt C++ code with a QWidget desktop focus. Widget, dialog, model/view, Designer, and desktop-UX guidance here is specific to Widgets work; broader QObject, threading, and build guidance also applies to non-UI Qt C++ code.

Adjacent Skills

This skill provides portable Qt engineering principles. Compose with:

• Workflow: thinking (planning), recursive-thinking (stress-testing),

security (threat modeling)

• Domain overlays: ui-guidance (ordinary graphical UI work),

ui-design-guidance (stronger design and UX work), project-core-dev (repo-specific build/test commands), project-platform-diagnose (environment-sensitive diagnosis)

Use this as the default principle skill for Qt code. Reach for coding-guidance-cpp only when the task is mostly non-Qt C++ or needs deeper general C++ design judgment than Qt-specific guidance.

Quick Routing

Open bundled references only when the task actually needs them:

• references/qt-build-compatibility.md

for CMake, generated-code, or Qt5/Qt6 compatibility work

• references/qt-debugging-checklist.md

for diagnosis-heavy tasks

• references/qt-designer-ui-files.md

for .ui files, Qt Widgets Designer, uic, or generated ui_*.h code

• references/qt-layouts-and-desktop-ux.md

for layout, dialog, panel, and desktop-UX work

• references/qt-model-view-checklist.md

for QAbstractItemModel, roles, resets, selections, and model/view contract work

Stay in the main skill when the task is broad Qt implementation or review and no single failure mode dominates yet.

When Not to Lean on This Skill

• non-Qt work
• pure backend or library code written in C++ that does not use Qt types,

eventing, object lifetime, or Qt build tooling

• Qt Quick or QML-first work; use only the QObject, threading, and build

guidance here when it genuinely applies, and rely on a QML/Qt Quick-specific skill or repo guidance for declarative UI architecture, bindings, and scene graph concerns

• design-only work where no Qt API, object model, build, or code judgment is

needed

Implementation Workflow

1. Read the touched widgets, models, controllers, dialogs, .ui forms, tests, and build files before editing. 2. Infer intended behavior from current signals and slots, ownership, thread affinity, layouts, and tests when the request is partially specified. Ask only when multiple plausible Qt designs would change semantics. 3. Choose the narrowest change that keeps QObject ownership, event ordering, layout behavior, model contracts, and UI-thread rules explicit. 4. Implement with one clear application bootstrap, small widget responsibilities, modern typed connect usage, minimal GUI-thread work, and narrow seams between widgets and domain logic. 5. Add or update deterministic tests close to the changed behavior. Default: Qt Test for widget, signal-slot, and model behavior; GoogleTest for pure non-Qt domain logic. Do not mix both in the same seam without a reason. If the repo already uses Qt Test, use QSignalSpy-style assertions for signal contracts. 6. Run the narrowest relevant formatter, build, test, and affected-platform smoke path the repo supports. If the change touches Qt5/Qt6 compatibility, validate each supported build variant.

Refactoring Workflow

Use this instead of the default implementation workflow when the task is primarily cleanup or restructuring:

1. Capture current ownership, signal flow, event-loop assumptions, thread affinity, layout behavior, and model or binding contracts. 2. Break the refactor into small slices that preserve visible behavior. 3. Remove long widget constructors, tangled signal chains, view-model leakage, duplicated object wiring, and layout hacks one step at a time. 4. Keep tests or smoke paths passing after each slice; add characterization coverage first when behavior is unclear. 5. Stop when the code is simpler, safer around lifetime and threading, and easier to reason about.

Review Workflow

When reviewing (not implementing), skip the implementation workflow and use this instead:

1. Read the change in full before commenting. 2. Identify findings, ordered by severity: Critical > Important > Suggestion. 3. Prioritize ownership and deletion bugs, cross-thread QObject misuse, connection lifetime mistakes, GUI-thread blocking, model/view contract violations, layout breakage, Qt5/Qt6 build regressions, resource-path and platform assumptions, and missing tests. 4. State findings with concrete evidence and the likely consequence. 5. For Qt-specific claims, name the proof: sender/receiver types and lifetimes for signal issues, thread affinity for cross-thread issues, begin/end and reset boundaries for model issues, and the visible interaction path for layout or .ui regressions.

Qt Rules

First tier - causes bugs

• These rules apply to Qt C++ broadly; Widget-specific rules appear in later

sections.

• Treat QObject ownership, parent-child lifetime, and thread affinity as core

contracts, not cleanup details

• Every Widgets application gets exactly one QApplication; create it before

any widget, QPixmap, QIcon, or other GUI object

• Do not copy QObject subclasses; keep lifetime and ownership explicit
• Use deleteLater() rather than immediate deletion when an object may still be

participating in the event loop

• Do not touch GUI objects from non-GUI threads
• Bind connection lifetime to a context object when possible so queued work does

not outlive the receiver

• Prefer the typed connect syntax over string-based SIGNAL and SLOT

macros unless the repo is constrained by old APIs

• Do not block the GUI thread with filesystem, network, database, or heavy CPU

work

• When model data changes, emit the correct notifications and bracket

structural changes with the correct begin/end calls

• Do not hand-place widgets with setGeometry() when a real layout should own

sizing and positioning

Second tier - prevents mistakes

• Keep widgets, models, delegates, dialogs, and business logic separated

enough to test behavior without full UI setup

• Prefer explicit ownership and small helper objects over hidden globals or

wide controller classes

• Keep slot bodies short; move non-trivial work into named helpers, presenters,

or model logic

• Prefer Qt containers, strings, and utilities where the repo already uses

them; do not introduce needless conversions at every boundary

• Follow the repo's Qt version and idioms before introducing newer Qt APIs
• Keep compiler, clazy, and Qt-specific warnings at zero in repo-owned code

Architecture and object lifetime

• This section mixes general Qt lifetime guidance with QWidget screen-structure

defaults.

• For Widgets apps, keep application bootstrap, main-window construction, and

signal wiring easy to find

• In QMainWindow code, separate central-widget setup, action/menu setup, and

signal wiring instead of burying everything in one constructor

• Use this default boundary unless the repo already chose differently:

plain C++ domain logic owns rules and state transitions; Qt-facing models or adapters translate domain state for the UI; widgets own presentation, local interaction, and signal wiring

• For non-trivial screens, a presenter, controller, or adapter seam is often

simpler than stuffing decisions into slots

• Parent-child ownership is convenient, but only when the parent truly owns the

child for the same lifetime

• Use raw pointers for non-owning QObject references only when lifetime is

obvious; use QPointer or a clearer ownership boundary when deletion can race with callbacks or queued work

• Avoid parented stack objects and mixed manual-plus-parent ownership
• Make who creates, owns, and tears down long-lived objects obvious near the

construction site

• Be careful with lambdas connected to signals; capture only what can outlive

the connection or tie the connection to a context object

Signals, slots, and events

• These rules apply to Qt C++ broadly, not only Widgets screens.
• Treat signals as contracts; name them for state changes or completed actions,

not vague implementation detail

• Prefer one clear signal over several partially overlapping ones when callers

need a stable contract

• Avoid long signal chains that make control flow impossible to follow
• Be explicit about connection type when thread hops or reentrancy matter
• Guard against recursive updates and signal storms when setters feed models,

bindings, or other observers

• If a signal appears connected but never fires, verify sender lifetime,

signature compatibility, and that moc ran after the last Q_OBJECT change

• Use event filters sparingly; prefer normal event handlers when ownership and

routing are local

Models, views, and UI boundaries

• This section is mostly QWidget model/view guidance; use the reference for

contract-heavy model work.

• Preserve the formal contract of Qt item models; invalid indexes, role names,

and reset behavior are compatibility boundaries

• Keep view state, model state, and domain state separated enough that each can

be tested and debugged directly

• Prefer explicit model roles and property names over stringly ad hoc data

blobs

• Avoid doing heavy logic in delegates, bindings, or paint paths
• When a view needs derived presentation state, prefer a model or adapter seam

over burying logic in widget callbacks

• In mixed QML/Widgets code, treat binding loops and context-property sprawl as

design smells; this skill still defaults to the QWidget side

• Detailed model/view rules and review checks live in

references/qt-model-view-checklist.md

Layouts and desktop UX

• This section is Widgets-specific.
• Layouts own geometry; use real layout types and desktop-native composition

instead of manual sizing or geometry hacks

• Use QFormLayout, QSplitter, QDockWidget, QGroupBox, and

QDialogButtonBox deliberately where their semantics match the screen

• Prefer standard buttons, shortcuts, dialogs, icons, and paths when Qt

provides them, instead of hard-coding one platform's desktop conventions

• Be deliberate with QSizePolicy, stretch factors, margins, spacing,

accessibility names, and keyboard flow

• Detailed layout and desktop-UX patterns live in

references/qt-layouts-and-desktop-ux.md

Threading, async, and responsiveness

• These rules apply to Qt C++ broadly, not only Widgets screens.
• Move blocking or long-running work off the GUI thread and define how results

are marshaled back

• Use queued delivery deliberately when crossing thread boundaries; do not

assume the default connection behavior is always correct

• Do not create children for a parent that lives in another thread
• Do not move an object to another thread unless its ownership, children, and

event handling model all remain valid there

• Prefer explicit task ownership, cancellation, and teardown rules for timers,

workers, and asynchronous replies

• Treat shutdown, application quit, and window close paths as lifetime hazards

for queued callbacks and pending replies

Build and version compatibility

• These rules apply to Qt C++ broadly; .ui guidance is Widgets-specific.
• Respect moc, uic, qrc, and build-system boundaries; file moves or class shape

changes that affect generated code are not trivial refactors

• Do not edit generated ui_*.h files; change the .ui form, the wrapper

widget, or the build inputs that generate them

• When a repo uses Qt Widgets Designer, treat .ui XML, form settings, custom

widget declarations, and generated includes as part of the source contract

• If the repo supports both Qt5 and Qt6, use version-driven CMake patterns

rather than hard-coded Qt5:: or Qt6:: targets

• In Qt6-first CMake repos that are not already standardized on a stable local

pattern, prefer Qt's own helper commands such as qt_standard_project_setup() and qt_add_executable() over ad hoc target setup

• Treat Qt version compatibility as a public build contract; test each claimed

variant instead of assuming dynamic find_package is enough

• Prefer stable resource lookup and path handling over current-working-directory

assumptions

• Mark user-visible strings for translation through the repo's chosen path,

tr() by default; do not introduce raw UI text that bypasses extraction

• Keep translation keys, object names, and user-visible strings deliberate

rather than incidental

• Do not introduce obsolete Qt classes or deprecated members in new code when a

maintained alternative exists; if a touched API is obsolete, treat migration pressure as part of the design review

• If a subsystem is mostly plain C++, keep Qt-specific concerns at the boundary

instead of spreading Qt types everywhere without benefit

• Detailed build and compatibility patterns live in

references/qt-build-compatibility.md

Testing and debugging

• Test visible behavior, model transitions, emitted signals, and lifecycle

edges, not just private helper functions

• Prefer deterministic UI tests and offscreen smoke paths over fragile timing-

dependent visual assertions

• Treat build verification as part of test completion; generated or updated

tests that do not compile are incomplete

• Use qDebug() and qWarning() deliberately for widget size, object class,

state transitions, and connection-path diagnostics

• For memory or lifecycle bugs in C++, prefer AddressSanitizer and Qt-aware

lifetime inspection over guessing

• Detailed failure categorization and diagnosis steps live in

references/qt-debugging-checklist.md

Review Hotspots

• missing Q_OBJECT, stale moc output, or signal/slot signature mismatch
• wrong QObject ownership or deleteLater() timing
• cross-thread object parenting or GUI-thread violations
• incorrect model notifications, reset behavior, or invalid index handling
• edits to generated ui_*.h instead of the underlying .ui or wrapper code
• new user-visible strings that bypass translation or break existing i18n paths
• newly introduced obsolete Qt APIs or deprecated members
• hidden layout regressions from QSizePolicy, stretch, spacing, or minimum

size changes

• Qt5/Qt6 target-family drift in CMake

Review Evidence

• For signal or slot bugs, name the sender, receiver, connection style, and the

lifetime or signature fact that breaks the path

• For thread-affinity bugs, name which object lives on which thread and where

the illegal GUI or parenting access occurs

• For model/view bugs, name which contract breaks: wrong data() role,

missing begin*/end*, invalid index handling, reset misuse, or stale selection/persistent-index assumptions

• For layout or .ui bugs, name the affected screen path and the geometry or

form-setting change that causes the regression

• For build or generated-code bugs, name the specific moc/uic/qrc or CMake

input that is stale, missing, or version-skewed

Decision Heuristics

Use these when the right choice is not obvious:

• Lifetime pressure: if it is not obvious who owns a QObject or when it can

die, redesign the boundary before adding more behavior.

• Thread-affinity pressure: if a callback, timer, or reply may arrive on a

different thread, make that hop explicit and local.

• Model-contract pressure: if a change touches model indexes, role names,

or reset behavior, treat it as a compatibility boundary rather than a local cleanup.

• Layout pressure: if you are about to use manual geometry, spacer hacks, or

magic sizes, stop and check whether the right layout type, size policy, or stretch factor would solve it cleanly.

• Build-compatibility pressure: if a repo claims both Qt5 and Qt6 support,

do not hard-code one target family or test only one build.

• Architecture pressure: if widget code starts owning business rules,

persistence, and orchestration together, introduce a presenter/controller seam before adding more slots.

• UI responsiveness: if the feature can stall input, painting, or startup,

rethink the design before polishing the code.

• Repo conventions: if the repo has established patterns for ownership,

signals and slots, widgets vs. QML, testing, or Qt version support, follow them unless they create a correctness problem.

• Narrowness vs. quality: implement the narrowest change that solves the

problem. When narrowness conflicts with correctness or lifecycle safety, prefer correctness. When it conflicts with style alone, prefer narrowness unless the task is explicitly a cleanup.

• Refactor boundary: outside explicit refactor work, fix at most one small

adjacent issue while you are in the file.

• Abstraction threshold: three similar widget handlers, signal-wiring paths,

model-shaping steps, or dialog flows is a pattern; before extracting, check whether a small helper, adapter, presenter, or model object is the simpler move.

• Qt vs. plain C++: if logic does not need the event loop, QObject

identity, or Qt containers, keep it as plain testable C++ instead of forcing Qt into the core domain.

Validation

A change is done when:

• the code builds without new compiler, moc, or Qt-specific warnings
• existing tests pass
• new or changed behavior has test coverage, or the lack of coverage is called

out with a concrete reason

• changed signal, layout, model, or thread-hop behavior has a deterministic

validation path

• UI-facing changes have at least a narrow smoke path on the affected platform
• Qt5/Qt6 compatibility changes were validated on each claimed build variant
• resource paths, generated-code inputs, and translation-sensitive changes were

verified when touched

• review findings at Critical and Important severity are addressed

Examples

• Review this Qt dialog and layout refactor for ownership, size-policy, and accessibility regressions
• Refactor this Qt widget controller so business logic moves out of slots and the UI stays responsive
• Fix this Qt CMake setup so the repo can build cleanly against both Qt5 and Qt6

Qt Build Compatibility

Open this reference only when the task touches CMake, generated Qt build steps, or real Qt5/Qt6 compatibility requirements.

Use when

• the repo claims support for both Qt5 and Qt6
• CMakeLists.txt contains hard-coded Qt5:: or Qt6:: targets
• generated-code inputs such as moc, uic, or qrc are part of the failure
• a build works on one Qt version and fails on the other

Core patterns

• Prefer version-driven discovery over hard-coded target families:

find_package(QT NAMES Qt6 Qt5 REQUIRED COMPONENTS Core Widgets)
find_package(Qt${QT_VERSION_MAJOR} REQUIRED COMPONENTS Core Widgets)

• Prefer version-driven targets:

target_link_libraries(myapp
    Qt${QT_VERSION_MAJOR}::Core
    Qt${QT_VERSION_MAJOR}::Widgets
)

• In Qt6-first repos that are not already standardized on a stable local

pattern, prefer Qt's helper commands such as qt_standard_project_setup() and qt_add_executable() over ad hoc Qt target setup.

• Treat moc, uic, and qrc changes as build-contract changes, not local cleanup.

Review hotspots

• hard-coded Qt5:: / Qt6:: targets in a repo that claims both
• new hand-rolled CMake setup in a Qt6-first repo where Qt helper commands

would be clearer and less error-prone

• generated headers or sources not regenerated after class-shape changes
• stale Q_OBJECT additions that compile only because one platform cached old

generated files

• resource lookups that depend on the current working directory

Validation

• configure and build each claimed Qt variant
• verify generated-code inputs are part of the build graph
• smoke-test the changed UI path on at least one affected platform

Qt Debugging Checklist

Open this reference when the task is primarily diagnosis rather than ordinary implementation.

Use when

• the failure class is still unclear and you need to categorize before editing
• the bug looks like ownership, signal/slot, layout, thread-affinity, or style

breakage

• the change is mostly diagnosis rather than feature or refactor work

Fast categorization

Classify the symptom before changing code:

• invisible widget
• zero-size widget or collapsed layout
• deleted-object access
• cross-thread QObject misuse
• pre-QApplication GUI object construction
• frozen event loop / blocked GUI thread
• signal connected but never fires
• style or QSS mismatch

High-value checks

Invisible or collapsed widget

• check isVisible(), isHidden(), and actual size
• verify parent visibility for child widgets
• verify a real layout is attached
• check QSizePolicy, stretch, minimum size, margins, and accidental

setFixedSize(0, 0)

Deleted-object or lifecycle bug

• check whether the object is owned by a parent that is already gone
• check deleteLater() timing and queued callbacks
• prefer QPointer for observing objects with unstable lifetime
• in C++, use ASan before guessing

Thread-affinity bug

• look for cross-thread parent/child creation
• verify where the receiver lives, not only where the signal was emitted
• make queued delivery explicit if the hop matters

Signal path bug

• verify sender lifetime
• verify exact signal/slot signature compatibility
• verify Q_OBJECT is present and moc reran after the last change

Frozen UI

• find the blocking call on the GUI thread
• move I/O or heavy work off-thread
• treat processEvents() as diagnosis only, not the final fix

Style or QSS bug

• inspect the effective stylesheet
• use local unpolish() / polish() and update() to confirm rule

application before changing rendering logic

Review hotspots

• code changes made before the failure class was identified
• processEvents() used as a production fix instead of diagnosis
• guessed lifecycle or thread explanations without checking object ownership or

affinity

• layout or style fixes applied without verifying the actual geometry or active

stylesheet state

Useful C++ diagnostics

qDebug() << "size" << widget->size();
qDebug() << "class" << widget->metaObject()->className();
qWarning() << "unexpected state" << state;

Validation

• the root failure class is identified
• the fix removes the cause instead of hiding the symptom
• the relevant test or smoke path reproduces the fix deterministically

Qt Designer UI Files

Open this reference when the task touches .ui forms, Qt Widgets Designer, uic, custom Designer widgets, or generated ui_*.h headers.

Core rules

• Treat .ui files as source and generated ui_*.h files as build outputs
• Do not hand-edit generated UI headers; make the change in the form, the

wrapper widget, or the code that consumes the generated UI class

• When a form change affects margins, spacing, or custom widget includes, treat

the Designer form settings as behavior-affecting inputs, not editor metadata

Review hotspots

• generated ui_*.h checked in with manual edits instead of regenerating
• .ui changes that silently alter layout defaults, spacing, or margins
• custom widgets declared in Designer without the includes or build wiring they

require

• wrapper code that bypasses setupUi() assumptions and fights the generated

layout or object naming

Validation

• rebuild after every .ui or Designer custom-widget change so uic reruns
• verify the changed screen through the affected interaction path, not only by

compiling

• if the repo uses Designer heavily, keep layout ownership in the form unless a

code-side override is clearly intentional

Qt Layouts And Desktop UX

Open this reference when the task is mainly widget composition, dialog design, panel layout, or desktop ergonomics.

Layout defaults

• layouts own geometry; do not hand-place widgets unless there is a real custom

rendering need

• prefer QFormLayout for forms, QGridLayout for true grids, and QSplitter

for user-resizable panel balance

• be deliberate with margins, spacing, stretch factors, and QSizePolicy

Useful patterns

Forms

• use QFormLayout for label-field alignment
• use QDialogButtonBox for accept/reject flows

Panels

• use QDockWidget only for real dockable panels
• use QGroupBox when visual grouping materially improves scanability
• persist QSplitter state for long-lived multi-panel screens

Accessibility and keyboard flow

• set accessible names for important controls
• keep tab order sensible
• make important actions keyboard reachable

Native desktop conventions

• prefer QDialogButtonBox standard roles and platform-native button ordering

over custom accept/cancel layouts

• prefer Qt standard shortcuts, icons, and dialogs before inventing custom

desktop conventions

• use Qt-provided standard paths and file dialogs instead of hard-coded

platform-specific locations

Layout debugging

• if a widget is zero-size, check minimum size, size hint, attached layout, and

size policy

• if the layout ignores size changes, inspect stretch factors and whether the

widget is Fixed when it should expand

• if the screen looks cramped, inspect margins and spacing before rewriting the

hierarchy

Qt Model View Checklist

Open this reference when the task touches QAbstractItemModel, QAbstractProxyModel, selection models, custom roles, resets, or view/model interaction bugs.

Core rules

• Treat data(), flags(), headerData(), role names, and index validity as

compatibility-facing contracts

• Use the correct begin*/end* pair for structural changes; do not emit data

change signals as a substitute for inserts, removes, or moves

• Use model reset only when the model contract truly resets; prefer narrower

notifications when the structure is still meaningfully stable

• Keep selection state, current index, and persistent index assumptions explicit

when rows move, reset, or disappear

Review hotspots

• dataChanged emitted where rows were inserted, removed, or moved
• indexes created or consumed without validating parent, row, column, or model
• custom roles added without stable names or without updating the view path that

depends on them

• view code caching model-derived state that becomes stale after reset or move
• delegates or views depending on side effects in data() or paint-time logic

Validation

• verify the affected view path with inserts, removes, updates, and empty-model

cases

• confirm selection/current-index behavior after reset, move, or deletion
• add deterministic model tests where the contract is subtle or previously

broken