comparison src/Analyser.h @ 199:0ba33d6c0a71

Properly rationalise the show/hide/add/remove layer logic for pitch candidates: ctrl+return maps through to a show layer command (but the layers remain in the view) while the add/remove layer flow is used for layer creation after selection and for abandoning an edit or discarding a selection.

      */
     QString reAnalyseSelection(Selection sel, FrequencyRange range);
 
     /**
      * Return true if the analysed pitch candidates are currently
-     * visible (by default they are hidden after construction until
-     * the user requests them). Note that the shown/hidden state is
-     * independent of whether any pitch candidates actually exist --
-     * it's possible they might be shown but not have been created yet
-     * because creation (through reAnalyseSelection) is asynchronous.
-     *
-     *!!! this interface is not right
+     * visible (they are hidden from the call to reAnalyseSelection
+     * until they are requested through showPitchCandidates()). Note
+     * that this may return true even when no pitch candidate layers
+     * actually exist yet, because they are constructed
+     * asynchronously. If that is the case, then the layers will
+     * appear when they are created (otherwise they will remain hidden
+     * after creation).
      */
     bool arePitchCandidatesShown() const;
 
     /**
-     * Show or hide the analysed pitch candidate layers. As in
-     * arePitchCandidatesShown, this is independent of whether the
-     * candidate layers actually exist. Call reAnalyseSelection to
-     * schedule creation of those layers.
-     *
-     *!!! this interface is not right
+     * Show or hide the analysed pitch candidate layers. This is reset
+     * (to "hide") with each new call to reAnalyseSelection. Because
+     * the layers are created asynchronously, setting this to true
+     * does not guarantee that they appear immediately, only that they
+     * will appear once they have been created.
      */
     void showPitchCandidates(bool shown);
-
-    bool haveHigherPitchCandidate() const;
-    bool haveLowerPitchCandidate() const;
 
     /**
      * If a re-analysis has been activated, switch the selected area
      * of the main pitch track to a different candidate from the
      * analysis results.
      */
     void switchPitchCandidate(Selection sel, bool up);
 
     /**
+     * Return true if it is possible to switch up to another pitch
+     * candidate. This may mean that the currently selected pitch
+     * candidate is not the highest, or it may mean that no alternate
+     * pitch candidate has been selected at all yet (but some are
+     * available).
+     */
+    bool haveHigherPitchCandidate() const;
+
+    /**
+     * Return true if it is possible to switch down to another pitch
+     * candidate. This may mean that the currently selected pitch
+     * candidate is not the lowest, or it may mean that no alternate
+     * pitch candidate has been selected at all yet (but some are
+     * available).
+     */
+    bool haveLowerPitchCandidate() const;
+
+    /**
      * Delete the pitch estimates from the selected area of the main
      * pitch track.
      */
     void deletePitches(Selection sel);
 

      * tracks up or down an octave in the selected area.
      */
     void shiftOctave(Selection sel, bool up);
 
     /**
-     * Remove any re-analysis layers (equivalent to
-     * showPitchCandidates(false)) and also reset the pitch track in
+     * Remove any re-analysis layers and also reset the pitch track in
      * the given selection to its state prior to the last re-analysis,
-     * abandoning any changes made since then.
-     */
-    void clearReAnalysis(Selection sel);
+     * abandoning any changes made since then. No re-analysis layers
+     * will be available until after the next call to
+     * reAnalyseSelection.
+     */
+    void abandonReAnalysis(Selection sel);
 
     /**
      * Import the pitch track from the given layer into our
      * pitch-track layer.
      */

 
     QString addVisualisations();
     QString addWaveform();
     QString addAnalyses();
 
+    void discardPitchCandidates();
+    
     // Document::LayerCreationHandler method
     void layersCreated(std::vector<Layer *>, std::vector<Layer *>);
 
     void saveState(Component c) const;
     void loadState(Component c);