Show and correctly clear the ALC Gain meter (#5636). Principle XI.

Show the Phone-panel ALC Gain meter only when the radio defines it. Clear stale painted readings immediately, register the rendered surface, and notify meter withdrawal after routing cleanup. Add mutation-checked lifecycle and registry coverage.

Operator rfoust authorized the visual-design override and squash merge.

Co-authored-by: on8st <258096273+on8st@users.noreply.github.com>
Co-authored-by: Claude Opus 5 (1M context) <noreply@anthropic.com>
Co-authored-by: Robbie Foust <rfoust@gmail.com>

Author: 3 people

docs/CERTIFICATION.md

@@ -974,7 +974,7 @@ need:
 |---|---|
 | `TX:FWDPWR` / `TX:REFPWR` defined but never fed | two power meters that can never move; publish with a documented scale or stop defining them |
 | `SliceModel::setRfGain` has no runtime path | LNA gain is connect-parameters only; the preamp control does nothing after connect |
-| ~~`TX:ALC` computed and discarded~~ | **Producer fixed; operator-visible half remains #5636** (not yet verified on a real radio) — `Hl2TxDsp::alcGain` now feeds a meter of its own, `TX:ALCGAIN` (dB), through `MeterModel`, radiocert and the automation bridge; no GUI surface renders it yet. It was NOT a repoint of `TX:ALC`: that key is a post-ALC LEVEL consumed by `MeterModel::swAlc()`, both ALC gauges, the certification table and the bridge, and changing what a published key means breaks all of them silently. The two are now separate quantities, as they are in WDSP (`TXA_ALC_PK` and `TXA_ALC_GAIN`) |
+| ~~`TX:ALC` computed and discarded~~ | **Producer and Phone-panel display implemented (#5506, #5636)** (not yet verified on a real radio) — `Hl2TxDsp::alcGain` now feeds a meter of its own, `TX:ALCGAIN` (dB), through `MeterModel`, radiocert and the automation bridge; the Phone panel renders ALC Gain when the meter is defined, with immediate clearing on invalidation. It was NOT a repoint of `TX:ALC`: that key is a post-ALC LEVEL consumed by `MeterModel::swAlc()`, both ALC gauges, the certification table and the bridge, and changing what a published key means breaks all of them silently. The two are now separate quantities, as they are in WDSP (`TXA_ALC_PK` and `TXA_ALC_GAIN`) |
 | Tune power not separable from RF power | TUNE keys at full drive on a fresh connect |
 | `RTTY` unmapped | silently demodulated as USB; conventionally lower-sideband on HF, so it wants a decision rather than a default |
 | Sideband stage saturates | even at 5 % drive into a dummy load a few inches away; needs inline attenuation or a second receiver |

src/core/MeterSurfaces.h

@@ -102,7 +102,7 @@ inline constexpr std::array<MeterSurface, 10> kMeterSurfaces{{
     // nothing — it reports the ALC's success, not their input level." This is
     // the number that answers "is the ALC holding, and by how much". This PR
     // publishes that value through MeterModel and the diagnostic surfaces;
-    // the operator-facing gauge is deliberately a separate change (#5636).
+    // the Phone panel renders it when the radio declares the meter (#5636).
     //
     // dB ONLY, deliberately, where TX:ALC accepts dBFS or Percent. That set has
     // two members because an Icom reports its ALC level as a percentage of its
@@ -112,7 +112,7 @@ inline constexpr std::array<MeterSurface, 10> kMeterSurfaces{{
     // same line — `TXA_ALC_PK` and `TXA_ALC_GAIN` are separate entries in
     // `txaMeterType` in `third_party/wdsp/upstream/TXA.h`.
     {"TX:ALCGAIN", "dB", "MeterModel::alcGainChanged / alcGainDb()",
-     "No GUI surface (producer-only; proposed Phone panel gauge is #5636)", false},
+     "Phone applet ALC Gain gauge (when the meter is defined)", true},
 
     {"TX:COMPPEAK", "dB", "MeterModel::compressionChanged",
      "Phone/CW applet Compression gauge", true},

src/gui/MainWindow.cpp

@@ -7551,6 +7551,15 @@ void MainWindow::applyCapabilitiesToUi(bool connected, const RadioCapabilities&
             cwCaps.cwPitchMinHz, cwCaps.cwPitchMaxHz, cwCaps.cwPitchStepHz);
         m_appletPanel->phoneCwApplet()->setHasAudioPeakingFilter(
             m_radioModel.hasAudioPeakingFilter());
+        // The ALC Gain gauge, on the meter EXISTING rather than on a
+        // capability flag: only the HL2 publishes TX:ALCGAIN, and the Phone
+        // panel is shared. `connected &&` rather than the permissive
+        // `!connected ||` used above — a disconnected panel must be the panel
+        // that shipped before this gauge, and the disconnect edge is what
+        // takes the row back down after an HL2 session so the next Flex
+        // connect does not inherit it.
+        m_appletPanel->phoneCwApplet()->setHasAlcGainMeter(
+            connected && m_radioModel.meterModel().hasAlcGainMeter());
     }
 
     // ── The 8-band graphic EQ ───────────────────────────────────────────────

src/gui/MainWindow_DspApplets.cpp

@@ -266,6 +266,55 @@ void MainWindow::wireDspApplets()
             m_appletPanel->phoneCwApplet()->resetAlc();
         }
     });
+    // The ALC's applied GAIN, beside the ALC's output level above. Gated the
+    // same way and additionally on the model having a SAMPLE: unity gain and
+    // "nothing has said what the ALC is doing" are the same 0 dB on the face,
+    // so without hasAlcGainValue() a cleared meter would render as a confident
+    // "the ALC is holding at unity" — the fabricated-reading failure §1.8
+    // describes, where a dead meter and a real reading of nothing look alike.
+    // WHETHER THE ROW EXISTS IS A DEFINITION QUESTION, and it is answered on
+    // the definition signals — never on the arrival of a value.
+    //
+    // It was answered inside the alcGainChanged handler below, and that is a
+    // value signal: submitTxAudio() returns early on !m_keyed, so alcGain never
+    // fires outside TX. The gauge was therefore absent during exactly the
+    // pre-transmission mic-gain setup it exists to inform, inserted itself into
+    // the panel mid-over, and in CW-only operation never appeared at all. The
+    // regime the meter earns its place in is the quiet-mic one — the ALC hits
+    // its makeup ceiling near -41.4 dBFS, below the Level gauge's -40 floor, so
+    // both existing gauges are pinned there and only this one can show the
+    // difference. Gating on a value hid it precisely there.
+    //
+    // applyCapabilitiesToUi() alone cannot cover it either: Hl2Backend calls
+    // defineMeters() from inside its own connected handler, AFTER RadioModel
+    // has published capabilities, so at the moment the panel is configured the
+    // meter does not exist yet. These three are the model's own account of
+    // which meters exist -- defined, removed, and the disconnect that drops
+    // them all (clear() emits only metersCleared, never a meterRemoved per
+    // index). Idempotent: setHasAlcGainMeter() early-returns on no change.
+    {
+        auto syncAlcGainRow = [this] {
+            m_appletPanel->phoneCwApplet()->setHasAlcGainMeter(
+                m_radioModel.meterModel().hasAlcGainMeter());
+        };
+        connect(&m_radioModel.meterModel(), &MeterModel::meterDefinitionChanged,
+                this, [syncAlcGainRow](int) { syncAlcGainRow(); });
+        connect(&m_radioModel.meterModel(), &MeterModel::meterRemoved,
+                this, [syncAlcGainRow](int) { syncAlcGainRow(); });
+        connect(&m_radioModel.meterModel(), &MeterModel::metersCleared,
+                this, syncAlcGainRow);
+    }
+    connect(&m_radioModel.meterModel(), &MeterModel::alcGainChanged,
+            this, [this](float gainDb) {
+        // READING ONLY. Presence is settled above, on the definition signals.
+        const bool live = m_radioModel.isRadioTransmitting()
+                       && m_radioModel.meterModel().hasAlcGainValue();
+        if (live) {
+            m_appletPanel->phoneCwApplet()->updateAlcGain(gainDb);
+        } else {
+            m_appletPanel->phoneCwApplet()->resetAlcGain();
+        }
+    });
     // Client-side PC mic metering — radio CODEC meters only see hardware mics.
     // Apply VU-style ballistics: fast attack, slow decay (~20 dB/sec).
     {

src/gui/MainWindow_Session.cpp

@@ -1373,6 +1373,10 @@ void MainWindow::wireRadioModel()
         if (!tx) {
             m_appletPanel->phoneCwApplet()->updateCompression(0.0f);
             m_appletPanel->phoneCwApplet()->resetAlc();
+            // Same reason as resetAlc: the last gain the ALC applied describes
+            // a transmission that has ended, and left on the face it reads as
+            // the gain being applied now.
+            m_appletPanel->phoneCwApplet()->resetAlcGain();
         }
         if (tx) {
             AetherSDR::ThemeManager::instance().applyStyleSheet(m_txIndicator, "QLabel { color: white; background: {{color.accent.danger}}; font-weight: bold; "

src/gui/PhoneCwApplet.cpp

@@ -29,6 +29,16 @@
 
 namespace AetherSDR {
 
+// The ALC Gain gauge's face, named because two places need the SAME numbers
+// and one of them is "no reading".
+//
+// Not a display preference: the top is the HL2 modulator's makeup ceiling
+// (Hl2TxDsp::Config::alcMaxGainDb), so a reading pressed against it means the
+// ALC has run out of gain rather than that the face has run out of scale.
+// -20 covers the reductions this chain produces.
+static constexpr float kAlcGainGaugeMinDb = -20.0f;
+static constexpr float kAlcGainGaugeMaxDb = 40.0f;
+
 // ── Triangle button (same as RxApplet) ──────────────────────────────────────
 
 class CwTriBtn : public QPushButton {
@@ -267,6 +277,51 @@ void PhoneCwApplet::buildPhonePanel()
     m_compGauge->setHoverValuePopupEnabled(true);
     vbox->addWidget(m_compGauge);
 
+    // ── ALC Gain gauge (dB: -20 to +40) ──────────────────────────────────
+    // Beside Compression because they answer the same kind of question — how
+    // much is the chain changing my audio — where the ALC gauge below answers
+    // where the audio ended up. The two are easily confused and the difference
+    // is the whole reason this one exists: a post-ALC level meter sits pinned
+    // near its target by construction, so an operator whose microphone is 30 dB
+    // too quiet sees an ALC gauge that looks perfect.
+    //
+    // The range is the modulator's, not a preference: +40 dB is the HL2
+    // modulator's makeup ceiling (Hl2TxDsp::Config::alcMaxGainDb), so a reading
+    // at the top means the ALC has run out of gain rather than that the face
+    // has run out of scale. -20 covers the reductions this chain produces.
+    //
+    // The colour breaks are the modulator's too, not taste. The face's top is
+    // alcMaxGainDb, so yellow at +20 is "half the makeup is spent" and red at
+    // +30 is "three quarters of it is, and the last 10 dB is all that stands
+    // between this microphone and an ALC that cannot reach its target" --
+    // which is a setup fault to fix at the gain control, not in software. The
+    // reduction half is deliberately uncoloured: the ALC taking level away is
+    // it working, at any depth this chain produces.
+    m_alcGainGauge = new HGauge(kAlcGainGaugeMinDb, kAlcGainGaugeMaxDb, 30.0f,
+        "ALC Gain", "dB",
+        {{-20, "-20dB"}, {-10, "-10"}, {0, "0"}, {10, "+10"}, {20, "+20"},
+         {30, "+30"}, {40, "+40"}}, nullptr, 20.0f);
+    m_alcGainGauge->setObjectName(QStringLiteral("phoneAlcGainGauge"));
+    // The floor, not 0: see resetAlcGain(). A gauge built hidden must not be
+    // holding a third-full bar for the moment it is revealed.
+    m_alcGainGauge->setValueImmediate(kAlcGainGaugeMinDb);
+    m_alcGainGauge->setAccessibleName("ALC gain gauge");
+    m_alcGainGauge->setAccessibleDescription(
+        "Gain the transmit ALC is applying, in dB; 0 is unity");
+    m_alcGainGauge->setHoverValueFormatter([](float v) {
+        // Signed, unlike Compression's face below, because both directions are
+        // real here: the ALC both adds makeup and takes level away.
+        return QStringLiteral("%1%2 dB")
+            .arg(v > 0.0f ? QStringLiteral("+") : QString())
+            .arg(QString::number(v, 'f', 1));
+    });
+    m_alcGainGauge->setHoverValuePopupEnabled(true);
+    // Built hidden. The Phone panel is shared with Flex, Icom and the sim,
+    // none of which publish an ALCGAIN meter, and a row they cannot drive is
+    // a change to their panel. setHasAlcGainMeter() is what reveals it.
+    m_alcGainGauge->setVisible(m_hasAlcGainMeter);
+    vbox->addWidget(m_alcGainGauge);
+
     // ── ALC gauge (post-SW-ALC SSB-peak, dBFS) ──────────────────────────
     // Mirrored in m_cwPanel; both gauges read from MeterModel::alcValueChanged
     // so SSB operators watching mic gain see the same indicator CW
@@ -1358,6 +1413,54 @@ void PhoneCwApplet::updateCompression(float compPeak)
     m_compGauge->setValue(-compressionDb);
 }
 
+void PhoneCwApplet::updateAlcGain(float gainDb)
+{
+    if (!m_alcGainGauge) {
+        return;
+    }
+    // No clamp here: HGauge clamps to its own range, and clamping twice would
+    // hide the case worth seeing — a gain pressed against the modulator's
+    // ceiling, which reads as "the ALC has nothing left" rather than as a
+    // meter at the end of its travel.
+    m_alcGainGauge->setValue(gainDb);
+}
+
+void PhoneCwApplet::resetAlcGain()
+{
+    if (!m_alcGainGauge) {
+        return;
+    }
+    // THE FACE FLOOR, NOT ZERO, and the distinction is the whole point of
+    // hasAlcGainValue(). This face runs -20..+40, so HGauge renders 0 dB as a
+    // bar one third full -- and 0 dB is also a real reading, "the ALC is
+    // holding at unity". Driving to 0 on unkey, on disconnect and as the first
+    // thing shown after a TX-slice change therefore painted a confident
+    // measurement in the one state where nothing has been measured. resetAlc()
+    // beside it drives to its own floor for the same reason; an empty bar is
+    // the only rendering of "no reading" this widget has.
+    m_alcGainGauge->setValueImmediate(kAlcGainGaugeMinDb);
+    m_alcGainGauge->clearPeak();
+}
+
+void PhoneCwApplet::setHasAlcGainMeter(bool has)
+{
+    if (m_hasAlcGainMeter == has) {
+        return;
+    }
+    m_hasAlcGainMeter = has;
+    if (!m_alcGainGauge) {
+        return;
+    }
+    // Discard the departing radio's last gain before hiding, for the same
+    // reason setMicLevelMeterState() resets the Level gauge at the lifecycle
+    // boundary: a reading kept behind a hidden widget comes back as the next
+    // radio's when the gauge is shown again.
+    if (!has) {
+        resetAlcGain();
+    }
+    m_alcGainGauge->setVisible(has);
+}
+
 void PhoneCwApplet::setAlcMeterUnit(const QString& unit)
 {
     if (unit == m_alcMeterUnit) {

src/gui/PhoneCwApplet.h

@@ -61,6 +61,19 @@ class PhoneCwApplet : public QWidget {
     // on a Flex unplug.
     void setHasAudioPeakingFilter(bool has);
 
+    // Does THIS session's radio publish an ALCGAIN meter? Gates the ALC Gain
+    // gauge, which is otherwise a face that can never move: the HL2 is the
+    // only family in the tree that publishes the meter, and the shared Phone
+    // panel is also Flex's, Icom's and the sim's. Pushed from
+    // MainWindow::applyCapabilitiesToUi off MeterModel::hasAlcGainMeter(),
+    // and again on definition changes, because meters are DEFINED after
+    // capabilities are published on the connect edge.
+    //
+    // NOT permissive while disconnected, unlike the APF row above: this gauge
+    // is new, and "no radio attached" must render as the panel that shipped
+    // before it rather than as a gauge nothing can drive.
+    void setHasAlcGainMeter(bool has);
+
 signals:
     void micLevelChanged(int level);  // slider value 0-100
 
@@ -79,6 +92,17 @@ public slots:
                       float micPeak, float compPeak);
     void updateCompression(float compPeak);
 
+    // The gain the transmitter's ALC is applying, in dB (0 = unity). A
+    // different reading from updateAlc() below, not a second scaling of it:
+    // that one is the post-ALC LEVEL, which sits near the ALC's target however
+    // the operator has set their gain, and this is how hard the stage is
+    // working to put it there — the half that answers "is the ALC holding, and
+    // by how much" when a transmission goes out quiet.
+    void updateAlcGain(float gainDb);
+    // Clear immediately to the face floor on unkey, disconnect or invalidation.
+    // A missing reading must not animate through apparently measured gains.
+    void resetAlcGain();
+
     // Notify the applet when RADE mode activates/deactivates so the mic level
     // slider and meter behave correctly (client-side gain + RX metering).
     void setRadeActive(bool on);
@@ -119,6 +143,16 @@ public slots:
     MicMeterSessionState m_micLevelMeterSession{MicMeterSessionState::Disconnected};
     bool m_micLevelMeterAvailable{true};
     HGauge* m_compGauge{nullptr};
+    // Phone panel only, beside Compression — the two gauges that report what
+    // the transmit chain is DOING to the operator's audio, as opposed to the
+    // Level and ALC gauges above and below them, which report levels. Not
+    // mirrored onto the CW panel the way the ALC gauge is: the remedy this
+    // meter points at is the mic slider, which is a Phone control.
+    HGauge* m_alcGainGauge{nullptr};
+    // Hidden until a radio says it publishes the meter — see
+    // setHasAlcGainMeter(). False by default so the gauge is built hidden and
+    // a family that never publishes ALCGAIN gets the panel it had before.
+    bool m_hasAlcGainMeter{false};
 
     QComboBox* m_micProfileCombo{nullptr};
 

src/models/MeterModel.cpp

@@ -248,7 +248,6 @@ void MeterModel::removeMeter(int index)
     m_defs.remove(index);
     m_values.remove(index);
     m_valueUpdatedMs.remove(index);
-    emit meterRemoved(index);
 
     const auto matchesIndex = [index](QMap<int, int>::iterator entry) {
         return entry.value() == index;
@@ -329,6 +328,9 @@ void MeterModel::removeMeter(int index)
         clearCompressionState();
         logCompressionSummary("meter-removed", true);
     }
+    // Presence subscribers query the routing maps synchronously. Notify only
+    // after the withdrawn meter has been removed from every index map.
+    emit meterRemoved(index);
 }
 
 float MeterModel::convertRaw(const MeterDef& def, qint16 raw) const