| Martin v. Löwis | 8718459 | 2008-06-04 06:29:55 +0000 | [diff] [blame] | 1 | |
| 2 | |
| 3 | ---------------------------------------------- |
| 4 | |
| 5 | xturtleDemo - Help |
| 6 | |
| 7 | ---------------------------------------------- |
| 8 | |
| 9 | This document has two sections: |
| 10 | |
| 11 | (1) How to use the demo viewer |
| 12 | (2) How to add your own demos to the demo repository |
| 13 | |
| 14 | |
| 15 | (1) How to use the demo viewer. |
| 16 | |
| 17 | Select a demoscript from the example menu. |
| 18 | The (syntax coloured) source code appears in the left |
| 19 | source code window. IT CANNOT BE EDITED, but ONLY VIEWED! |
| 20 | |
| 21 | - Press START button to start the demo. |
| 22 | - Stop execution by pressing the STOP button. |
| 23 | - Clear screen by pressing the CLEAR button. |
| 24 | - Restart by pressing the START button again. |
| 25 | |
| 26 | SPECIAL demos are those which run EVENTDRIVEN. |
| 27 | (For example clock.py - or oldTurtleDemo.py which |
| 28 | in the end expects a mouse click.): |
| 29 | |
| 30 | Press START button to start the demo. |
| 31 | |
| 32 | - Until the EVENTLOOP is entered everything works |
| 33 | as in an ordinary demo script. |
| 34 | |
| 35 | - When the EVENTLOOP is entered, you control the |
| 36 | application by using the mouse and/or keys (or it's |
| 37 | controlled by some timer events) |
| 38 | To stop it you can and must press the STOP button. |
| 39 | |
| 40 | While the EVENTLOOP is running, the examples menu is disabled. |
| 41 | |
| 42 | - Only after having pressed the STOP button, you may |
| 43 | restart it or choose another example script. |
| 44 | |
| 45 | * * * * * * * * |
| 46 | In some rare situations there may occur interferences/conflicts |
| 47 | between events concerning the demo script and those concerning the |
| 48 | demo-viewer. (They run in the same process.) Strange behaviour may be |
| 49 | the consequence and in the worst case you must close and restart the |
| 50 | viewer. |
| 51 | * * * * * * * * |
| 52 | |
| 53 | |
| 54 | (2) How to add your own demos to the demo repository |
| 55 | |
| 56 | - scriptname: must begin with tdemo_ , |
| 57 | so it must have the form tdemo_<your-script-name>.py |
| 58 | |
| 59 | - place: same directory as xturtleDemo.py or some |
| 60 | subdirectory, the name of which must also begin with |
| 61 | tdemo_..... |
| 62 | |
| 63 | - requirements on source code: |
| 64 | code must contain a main() function which will |
| 65 | be executed by the viewer (see provided example scripts) |
| 66 | main() may return a string which will be displayed |
| 67 | in the Label below the source code window (when execution |
| Terry Jan Reedy | 122df1e | 2014-06-22 01:18:48 -0400 | [diff] [blame] | 68 | has finished.) |
| Martin v. Löwis | 8718459 | 2008-06-04 06:29:55 +0000 | [diff] [blame] | 69 | |
| Terry Jan Reedy | 122df1e | 2014-06-22 01:18:48 -0400 | [diff] [blame] | 70 | If the demo is EVENT DRIVEN, main must return the string |
| 71 | "EVENTLOOP". This informs the demo viewer that the script is |
| 72 | still running and must be stopped by the user! |
| Martin v. Löwis | 8718459 | 2008-06-04 06:29:55 +0000 | [diff] [blame] | 73 | |
| Terry Jan Reedy | 122df1e | 2014-06-22 01:18:48 -0400 | [diff] [blame] | 74 | If an "EVENTLOOP" demo runs by itself, as with clock, which uses |
| 75 | ontimer, or minimal_hanoi, which loops by recursion, then the |
| 76 | code should catch the turtle.Terminator exception that will be |
| 77 | raised when the user presses the STOP button. (Paint is not such |
| 78 | a demo; it only acts in response to mouse clicks and movements.) |
| 79 | |