MMDevice: adds functions to XYStage and Stage to let them signal whether they use callbacks

DeviceAdapters/CNCMicroscope/RAMPSStage/XYStage.h

@@ -66,7 +66,6 @@ class RAMPSXYStage : public CXYStageBase<RAMPSXYStage>
 
   int IsXYStageSequenceable(bool& isSequenceable) const;
 
-
   // action interface
   // ----------------
   int OnPosition(MM::PropertyBase* pProp, MM::ActionType eAct);

DeviceAdapters/Cephla/Squid.h

@@ -284,6 +284,7 @@ class SquidXYStage : public CXYStageBase<SquidXYStage>
 
    int IsXYStageSequenceable(bool& isSequenceable) const { isSequenceable = false; return DEVICE_OK; }
 
+   int UsesOnXYStagePositionChanged(bool& result) const { result = true; return DEVICE_OK; }
 
    // action interface
    // ----------------
@@ -354,6 +355,8 @@ class SquidZStage : public CStageBase<SquidZStage>
    }
    bool IsContinuousFocusDrive() const { return false; };
 
+   int UsesOnStagePositionChanged(bool& result) const { result = true; return DEVICE_OK; }
+
    int OnAcceleration(MM::PropertyBase* pProp, MM::ActionType eAct);
    int OnMaxVelocity(MM::PropertyBase* pProp, MM::ActionType eAct);
 

DeviceAdapters/ChuoSeiki_MD5000/ChuoSeiki_MD_XYZ.h

@@ -119,6 +119,7 @@ class MD_SingleStage:
 // Checking device functions
 	int IsStageSequenceable(bool& isSequenceable) const {isSequenceable = false; return DEVICE_OK;}
 	bool IsContinuousFocusDrive() const {return DEVICE_OK;}
+	int UsesOnStagePositionChanged(bool& result) const { result = true; return DEVICE_OK; }
 	bool SupportsDeviceDetection(void);
 	MM::DeviceDetectionStatus DetectDevice(void);
 

DeviceAdapters/DemoCamera/DemoCamera.h

@@ -556,6 +556,8 @@ class CDemoStage : public CStageBase<CDemoStage>
 
    bool IsContinuousFocusDrive() const {return false;}
 
+   int UsesOnStagePositionChanged(bool& result) const { result = true; return DEVICE_OK; }
+
    // action interface
    // ----------------
    int OnPosition(MM::PropertyBase* pProp, MM::ActionType eAct);
@@ -636,6 +638,7 @@ class CDemoXYStage : public CXYStageBase<CDemoXYStage>
 
    int IsXYStageSequenceable(bool& isSequenceable) const {isSequenceable = false; return DEVICE_OK;}
 
+   int UsesOnXYStagePositionChanged(bool& result) const { result = true; return DEVICE_OK; }
 
    // action interface
    // ----------------

DeviceAdapters/ESP32/esp32.h

@@ -389,6 +389,8 @@ class CESP32XYStage : public CXYStageBase<CESP32XYStage>
 
     int IsXYStageSequenceable(bool& isSequenceable) const { isSequenceable = false; return DEVICE_OK; }
 
+    int UsesOnXYStagePositionChanged(bool& result) const { result = true; return DEVICE_OK; }
+
     int OnXStageMinPos(MM::PropertyBase* pProp, MM::ActionType eAct);
     int OnXStageMaxPos(MM::PropertyBase* pProp, MM::ActionType eAct);
     int OnYStageMinPos(MM::PropertyBase* pProp, MM::ActionType eAct);

DeviceAdapters/OpenFlexure/OpenFlexure.h

@@ -165,6 +165,7 @@ class ZStage : public CStageBase<ZStage>
 	int GetLimits(double& lower, double& upper) { return DEVICE_UNSUPPORTED_COMMAND;} // nah 
 	int IsStageSequenceable(bool& isSequenceable) const { isSequenceable = false;  return DEVICE_OK;}
 	bool IsContinuousFocusDrive() const  { return false; }
+
 	bool Busy() { return false; }
 
 	// Helper functions

DeviceAdapters/PriorPureFocus/PureFocus.h

@@ -170,6 +170,7 @@ class PureFocusOffset : public CStageBase<PureFocusOffset> {
    bool IsContinuousFocusDrive() const {
       return false;
    };
+
    void CallbackPositionSteps(long steps);
    void RemoveHub() { pHub_ = 0; };
 

DeviceAdapters/PyDevice/PyStage.h

@@ -118,6 +118,11 @@ class CPyXYStage : public PyXYStageClass {
         return DEVICE_UNSUPPORTED_COMMAND;
     }
 
+    int UsesOnXYStagePositionChanged(bool& result) const override {
+        result = false;
+        return DEVICE_OK;
+    }
+
 protected:
     double origin_x_ = 0.0;
     double origin_y_ = 0.0;

DeviceAdapters/StandaStage/StandaStage.h

@@ -266,7 +266,6 @@ class CStandaXYStage : public CXYStageBase<CStandaXYStage>
 
    int IsXYStageSequenceable(bool& isSequenceable) const {isSequenceable = false; return DEVICE_OK;}
 
-
    // action interface
    // ----------------
 

DeviceAdapters/WieneckeSinske/ZPiezoCanDevice.h

@@ -77,7 +77,6 @@ class ZPiezoCANDevice : public CStageBase<ZPiezoCANDevice>
 	int SetOrigin();
 	int IsStageSequenceable(bool& isSequenceable) const {isSequenceable = false; return DEVICE_OK;}
 
-
 	// action interface                                                       
 	// ----------------                                                       
 	int OnPort(MM::PropertyBase* pProp, MM::ActionType eAct); 

DeviceAdapters/WieneckeSinske/ZPiezoWSDevice.h

@@ -77,7 +77,6 @@ class ZPiezoWSDevice : public CStageBase<ZPiezoWSDevice>
 	int SetOrigin();
 	int IsStageSequenceable(bool& isSequenceable) const {isSequenceable = false; return DEVICE_OK;}
 
-
 	// action interface                                                       
 	// ----------------                                                       
 	int OnPort(MM::PropertyBase* pProp, MM::ActionType eAct); 

DeviceAdapters/ZeissCAN29/ZeissCAN29.h

@@ -836,6 +836,8 @@ class Axis : public CStageBase<Axis>, public ZeissAxis
    int IsStageSequenceable(bool& isSequenceable) const {isSequenceable = false; return DEVICE_OK;}
    bool IsContinuousFocusDrive() const {return false;}
 
+   int UsesOnStagePositionChanged(bool& result) const { result = true; return DEVICE_OK; }
+
    // action interface
    // ----------------
    int OnPosition(MM::PropertyBase* pProp, MM::ActionType eAct);
@@ -890,6 +892,8 @@ class XYStage : public CXYStageBase<XYStage>, public ZeissAxis
   double GetStepSizeYUm() {return stepSize_um_;}
   int IsXYStageSequenceable(bool& isSequenceable) const {isSequenceable = false; return DEVICE_OK;}
 
+   int UsesOnXYStagePositionChanged(bool& result) const { result = true; return DEVICE_OK; }
+
    // action interface
    // ----------------
    int OnMoveMode(MM::PropertyBase* pProp, MM::ActionType eAct);

MMCore/Devices/StageInstance.cpp

@@ -60,6 +60,7 @@ StageInstance::SetFocusDirection(MM::FocusDirection direction)
    focusDirectionHasBeenSet_ = true;
 }
 
+int StageInstance::UsesOnStagePositionChanged(bool& result) const { RequireInitialized(__func__); return GetImpl()->UsesOnStagePositionChanged(result); }
 int StageInstance::IsStageSequenceable(bool& isSequenceable) const { RequireInitialized(__func__); return GetImpl()->IsStageSequenceable(isSequenceable); }
 int StageInstance::IsStageLinearSequenceable(bool& isSequenceable) const { RequireInitialized(__func__); return GetImpl()->IsStageLinearSequenceable(isSequenceable); }
 bool StageInstance::IsContinuousFocusDrive() const { RequireInitialized(__func__); return GetImpl()->IsContinuousFocusDrive(); }

MMCore/Devices/StageInstance.h

@@ -57,6 +57,7 @@ class StageInstance : public DeviceInstanceBase<MM::Stage>
    int GetLimits(double& lower, double& upper);
    MM::FocusDirection GetFocusDirection();
    void SetFocusDirection(MM::FocusDirection direction);
+   int UsesOnStagePositionChanged(bool& result) const;
    int IsStageSequenceable(bool& isSequenceable) const;
    int IsStageLinearSequenceable(bool& isSequenceable) const;
    bool IsContinuousFocusDrive() const;

MMCore/Devices/XYStageInstance.cpp

@@ -42,6 +42,7 @@ int XYStageInstance::SetYOrigin() { RequireInitialized(__func__); return GetImpl
 int XYStageInstance::GetStepLimits(long& xMin, long& xMax, long& yMin, long& yMax) { RequireInitialized(__func__); return GetImpl()->GetStepLimits(xMin, xMax, yMin, yMax); }
 double XYStageInstance::GetStepSizeXUm() { RequireInitialized(__func__); return GetImpl()->GetStepSizeXUm(); }
 double XYStageInstance::GetStepSizeYUm() { RequireInitialized(__func__); return GetImpl()->GetStepSizeYUm(); }
+int XYStageInstance::UsesOnXYStagePositionChanged(bool& result) const { RequireInitialized(__func__); return GetImpl()->UsesOnXYStagePositionChanged(result); }
 int XYStageInstance::IsXYStageSequenceable(bool& isSequenceable) const { RequireInitialized(__func__); return GetImpl()->IsXYStageSequenceable(isSequenceable); }
 int XYStageInstance::GetXYStageSequenceMaxLength(long& nrEvents) const { RequireInitialized(__func__); return GetImpl()->GetXYStageSequenceMaxLength(nrEvents); }
 int XYStageInstance::StartXYStageSequence() { RequireInitialized(__func__); return GetImpl()->StartXYStageSequence(); }

MMCore/Devices/XYStageInstance.h

@@ -56,6 +56,7 @@ class XYStageInstance : public DeviceInstanceBase<MM::XYStage>
    int GetStepLimits(long& xMin, long& xMax, long& yMin, long& yMax);
    double GetStepSizeXUm();
    double GetStepSizeYUm();
+   int UsesOnXYStagePositionChanged(bool& result) const;
    int IsXYStageSequenceable(bool& isSequenceable) const;
    int GetXYStageSequenceMaxLength(long& nrEvents) const;
    int StartXYStageSequence();

MMCore/MMCore.cpp

@@ -106,7 +106,7 @@ namespace mmi = mmcore::internal;
  * (Keep the 3 numbers on one line to make it easier to look at diffs when
  * merging/rebasing.)
  */
-const int MMCore_versionMajor = 11, MMCore_versionMinor = 13, MMCore_versionPatch = 0;
+const int MMCore_versionMajor = 11, MMCore_versionMinor = 14, MMCore_versionPatch = 0;
 
 
 ///////////////////////////////////////////////////////////////////////////////
@@ -2265,6 +2265,24 @@ void CMMCore::loadExposureSequence(const char* cameraLabel, std::vector<double>
       throw CMMError(getDeviceErrorText(ret, pCamera));
 }
 
+/**
+* Queries whether this stage uses callbacks to signal position changes
+* When false, use polling to stay updated about the positionf of the stage
+*/
+bool CMMCore::isStageUsingCallbacks(const char* label) MMCORE_LEGACY_THROW(CMMError)
+{
+   std::shared_ptr<mmi::StageInstance> pStage =
+      deviceManager_->GetDeviceOfType<mmi::StageInstance>(label);
+
+   mmi::DeviceModuleLockGuard guard(pStage);
+
+   bool result;
+   int ret = pStage->UsesOnStagePositionChanged(result);
+   if (ret != DEVICE_OK)
+      throw CMMError(getDeviceErrorText(ret, pStage));
+   return result;
+}
+
 
 /**
  * Queries stage if it can be used in a sequence
@@ -2417,6 +2435,26 @@ void CMMCore::setStageLinearSequence(const char* label, double dZ_um, int nSlice
       throw CMMError(getDeviceErrorText(ret, pStage));
 }
 
+
+/**
+* Queries whether this XYStage uses callbacks to signal position changes
+* When false, use polling to stay updated about the positionf of the stage
+*/
+bool CMMCore::isXYStageUsingCallbacks(const char* label) MMCORE_LEGACY_THROW(CMMError)
+{
+   std::shared_ptr<mmi::XYStageInstance> pStage =
+      deviceManager_->GetDeviceOfType<mmi::XYStageInstance>(label);
+
+   mmi::DeviceModuleLockGuard guard(pStage);
+
+   bool result;
+   int ret = pStage->UsesOnXYStagePositionChanged(result);
+   if (ret != DEVICE_OK)
+      throw CMMError(getDeviceErrorText(ret, pStage));
+
+   return result;
+}
+
 /**
  * Queries XY stage if it can be used in a sequence
  * @param label    the XY stage device label

MMCore/MMCore.h

@@ -493,6 +493,7 @@ class CMMCore
    void setFocusDirection(const char* stageLabel, int sign);
    int getFocusDirection(const char* stageLabel) MMCORE_LEGACY_THROW(CMMError);
 
+   bool isStageUsingCallbacks(const char* stageLabel) MMCORE_LEGACY_THROW(CMMError);
    bool isStageSequenceable(const char* stageLabel) MMCORE_LEGACY_THROW(CMMError);
    bool isStageLinearSequenceable(const char* stageLabel) MMCORE_LEGACY_THROW(CMMError);
    void startStageSequence(const char* stageLabel) MMCORE_LEGACY_THROW(CMMError);
@@ -530,6 +531,7 @@ class CMMCore
          double newXUm, double newYUm) MMCORE_LEGACY_THROW(CMMError);
    void setAdapterOriginXY(double newXUm, double newYUm) MMCORE_LEGACY_THROW(CMMError);
 
+   bool isXYStageUsingCallbacks(const char* xyStageLabel) MMCORE_LEGACY_THROW(CMMError);
    bool isXYStageSequenceable(const char* xyStageLabel) MMCORE_LEGACY_THROW(CMMError);
    void startXYStageSequence(const char* xyStageLabel) MMCORE_LEGACY_THROW(CMMError);
    void stopXYStageSequence(const char* xyStageLabel) MMCORE_LEGACY_THROW(CMMError);

MMCoreJ_wrap/pom.xml

@@ -6,7 +6,7 @@
 
     <groupId>org.micro-manager.mmcorej</groupId>
     <artifactId>MMCoreJ</artifactId>
-    <version>11.13.0</version>
+    <version>11.14.0</version>
 
     <name>MMCore Java API</name>
     <description>Java bindings for MMCore, the device abstraction layer of Micro-Manager, the microscope control and acquisition platform.</description>

MMDevice/DeviceBase.h

@@ -1905,6 +1905,15 @@ class CStageBase : public CDeviceBase<MM::Stage, U>
       return DEVICE_OK;
    }
 
+   /**
+   * @brief Return true when your device adapter uses OnStagePositionChanged callbacks.
+   */
+   virtual int UsesOnStagePositionChanged(bool& result) const
+   {
+      result = false;
+      return DEVICE_OK;
+   }
+
    virtual int IsStageLinearSequenceable(bool& isSequenceable) const
    {
       isSequenceable = false;
@@ -2113,6 +2122,15 @@ class CXYStageBase : public CDeviceBase<MM::XYStage, U>
       return this->SetPositionSteps(xSteps+x, ySteps+y);
    }
 
+   /**
+    * @brief Return true when your device adapter uses OnXYStagePositionChanged callbacks.
+   */
+   virtual int UsesOnXYStagePositionChanged(bool& result) const
+   {
+      result = false;
+      return DEVICE_OK;
+   }
+
    virtual int Move(double /*vx*/, double /*vy*/)
    {
       return DEVICE_UNSUPPORTED_COMMAND;

MMDevice/MMDevice.h

@@ -28,7 +28,7 @@
 // Header version
 // If any of the class definitions changes, the interface version
 // must be incremented
-#define DEVICE_INTERFACE_VERSION 74
+#define DEVICE_INTERFACE_VERSION 75
 ///////////////////////////////////////////////////////////////////////////////
 
 // N.B.
@@ -602,6 +602,17 @@ namespace MM {
       virtual int SetOrigin() = 0;
       virtual int GetLimits(double& lower, double& upper) = 0;
 
+      /**
+      * @brief Stages can use the OnStagePositionChanged callback to signal
+      * updates about their position.  Some adapters do so, others do not,
+      * in which case the UI code should use polling.  This function signals whether
+      * the device adapters uses callbacks, so that the UI knows it does not need
+      * to poll this device. It is best practice to not change the result of this
+      * function (i.e. use a const value) as the UI will query the function 
+      * only once.
+      */
+      virtual int UsesOnStagePositionChanged(bool& result) const = 0;
+
       /**
        * @brief Return the focus direction.
        *
@@ -708,6 +719,17 @@ namespace MM {
       virtual int Home() = 0;
       virtual int Stop() = 0;
 
+      /**
+      * @brief XY stages can use the OnXYStagePositionChanged callback to signal
+      * updates about their position.  Some stage adapters do so, others do not,
+      * in which case the UI code can use polling.  This function signals whether
+      * the device adapters uses callbacks, so that the UI knows it does not need
+      * to poll this device. It is best practice to not change the result of this
+      * function (i.e. use a const value) as the UI will query the function 
+      * only once.
+      */
+      virtual int UsesOnXYStagePositionChanged(bool &result) const = 0;
+
       /**
        * @brief Define the current position as the (hardware) origin (0, 0).
        */