|
| 1 | +# Managing Callback Interruptions in Nelson |
| 2 | + |
| 3 | +## Description |
| 4 | + |
| 5 | + <p>You can assign a callback function to a callback property using one of the following methods:</p> |
| 6 | + <p><b>Function handle</b>: Use this approach when your callback does not need extra input arguments.</p> |
| 7 | + <p><b>Cell array</b>: Ideal for situations where your callback requires additional input arguments. The cell array should include the function handle as the first element, followed by the input arguments.</p> |
| 8 | + <p><b>Anonymous function</b>: This method is suitable for simple callback code or when you want to reuse a function that isn't exclusively used as a callback.</p> |
| 9 | + <p><b>Characters vector or scalar string</b> containing commands.</p> |
| 10 | + <p/> |
| 11 | + <p>Nelson provides control over whether a callback function can be interrupted during its execution. In some cases, allowing interruptions might be desirable, such as enabling users to stop an animation loop through an interrupting callback. However, in scenarios where the execution order of callbacks is crucial, it might be necessary to prevent interruptions to maintain the intended behavior, such as ensuring smooth responsiveness in applications that respond to pointer movements.</p> |
| 12 | + <p/> |
| 13 | + <p>Callback Interruption Behavior:</p> |
| 14 | + <p/> |
| 15 | + <p>Callbacks are executed in the order they are queued. When a callback is running and another user action triggers a second callback, this second callback attempts to interrupt the first one. The first callback is referred to as the "running callback," while the second is the "interrupting callback."</p> |
| 16 | + <p/> |
| 17 | + <p>In some cases, specific commands within the running callback prompt Nelson to process any pending callbacks in the queue.</p> |
| 18 | + <p>When Nelson encounters one of these commands such as <b>drawnow</b>, <b>figure</b>, <b>waitfor</b>, or <b>pause</b> it evaluates whether an interruption should occur.</p> |
| 19 | + <p/> |
| 20 | + <p>No Interruption: If the running callback does not include any of these commands, Nelson will complete the running callback before executing the interrupting callback.</p> |
| 21 | + <p/> |
| 22 | + <p>Interruption Conditions: If the running callback includes any of these commands, the behavior depends on the Interruptible property of the object that owns the running callback:</p> |
| 23 | + <p/> |
| 24 | + <p>If <b>Interruptible</b> is set to <b>'on'</b>, Nelson allows the interruption. The running callback is paused, the interrupting callback is executed, and once it is finished, Nelson resumes the execution of the running callback.</p> |
| 25 | + <p>If <b>Interruptible</b> is set to <b>'off'</b>, the interruption is blocked. The <b>BusyAction</b> property of the interrupting callback then dictates the next step:</p> |
| 26 | + <p>If <b>BusyAction</b> is <b>'queue'</b>, the interrupting callback will be executed after the running callback completes.</p> |
| 27 | + <p>If <b>BusyAction</b> is <b>'cancel'</b>, the interrupting callback is discarded and not executed.</p> |
| 28 | + <p>By default, the <b>Interruptible</b> property is <b>'on'</b>, and <b>BusyAction</b> is <b>'queue'</b>.</p> |
| 29 | + <p/> |
| 30 | + <p>Notably, certain callbacks specifically <b>DeleteFcn</b>, <b>CloseRequestFcn</b>, and <b>SizeChangedFcn</b> will interrupt the running callback regardless of the Interruptible property's value.</p> |
| 31 | + |
| 32 | +## Example |
| 33 | + |
| 34 | +uicontrol demo Interruptible |
| 35 | + |
| 36 | +```matlab |
| 37 | +addpath([modulepath('graphics','root'), '/examples/uicontrol']) |
| 38 | +edit uicontrol_demo_interruptible |
| 39 | +uicontrol_demo_interruptible |
| 40 | +``` |
| 41 | + |
| 42 | +<img src="uicontrol_6_E87E65E2.png" align="middle"/> |
| 43 | + |
| 44 | +## See also |
| 45 | + |
| 46 | +[uicontrol](uicontrol.md), [drawnow](drawnow.md), [waitfor](waitfor.md). |
| 47 | + |
| 48 | +## History |
| 49 | + |
| 50 | +| Version | Description | |
| 51 | +| ------- | --------------- | |
| 52 | +| 1.0.0 | initial version | |
| 53 | + |
| 54 | +## Author |
| 55 | + |
| 56 | +Allan CORNET |
0 commit comments