.. _manual_set_on_program_stopped:

set_on_program_stopped (Manual Mode)
------------------------------------------
This section explains how to use :ref:`set_on_program_stopped <set_on_program_stopped>`  
during **Manual (Teach)** operations. |br|
This function registers a **callback function** that is triggered whenever a program  
running on the controller is **stopped**, either manually from the Teach Pendant (TP),  
through an API command, or due to an error condition.  

It is particularly useful for restoring the teaching environment,  
resetting motion states, or logging the reason for program interruption.

**Typical usage**

- Detect and handle program termination events during manual teaching.  
- Automatically log the stop cause for debugging or traceability.  
- Notify the operator (e.g., log message or popup) when the program halts.  
- Prepare the controller for a safe restart or next teaching sequence.

.. Note::

    - See :ref:`Rules for callback functions <callback_rules>`.

**Example: Log and respond to program stop events**

.. code-block:: cpp

   // Callback triggered when DRL or manual program stops
   void OnProgramStopped(const PROGRAM_STOP_CAUSE cause)
   {
       printf("-------------------------------------------\n");
       printf("[PROGRAM STOPPED]\n");

       // Log the stop cause
       if (cause == PROGRAM_STOP_CAUSE_NORMAL)
           printf("Stop cause: NORMAL (program ended)\n");
       else if (cause == PROGRAM_STOP_CAUSE_FORCE)
           printf("Stop cause: FORCE\n");
       else if (cause == PROGRAM_STOP_CAUSE_ERROR)
           printf("Stop cause: ERROR\n");
       else
           printf("Stop cause: %d\n", (int)cause);

       printf("-------------------------------------------\n");
   }

   drfl.open_connection("192.168.137.100");
   drfl.set_on_program_stopped(OnProgramStopped);
   printf("[Teach] Program stop monitoring active.\n");

   // Keep running to receive program stop events
   while (true)
       this_thread::sleep_for(chrono::seconds(1));

When registered, this callback is called when a DRL program stops on the controller (normal end, drl_stop, or error). It helps implement **automatic post-stop handling**, such as stop-cause logging, system recovery preparation, or custom safety notifications.

**Tips**

- Use to detect and classify **stop causes** in real time.  
- Ideal for automatic recovery, logging, or post-teaching cleanup routines.