GINA Reference Manual

Version 2.1

Michael Spenke  Thomas Berlage  Andreas Bäcker  Andreas Genau

Christian Beilken

Gesellschaft für Mathematik und Datenverarbeitung mbH (German National Research Center for Computer Science) P.O. Box 1316 D-W-5205 Sankt Augustin 1 Germany

                   e-mail: spenke@gmdzi.gmd.de

January 24, 1992

Contents

1 Introduction 10

2 The Hierarchy of GINA Classes 11

3 Some Global Variables of GINA 14 3.1 Variable *bitmap-directories* . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14 3.2 Variable *default-toolkit-host* . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14 3.3 Variable *default-display-host* . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14 3.4 Variable *default-display-number* . . . . . . . . . . . . . . . . . . . . . . . . . . . 14 3.5 Variable *default-screen-number* . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15 3.6 Variable *application* . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15 3.7 Variable *display* . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15 3.8 Variable *running-applications* . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15 3.9 Variable *inspect-click* . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16 3.10 Variable *debug-menu* . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16 3.11 Variable *clx-synchronous* . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16 3.12 Variable *drag-n-drop-transfer-value* . . . . . . . . . . . . . . . . . . . . . . . . . . 16 3.13 Function make-object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16

4 Global Application Management 17 4.1 Variable *loaded-applications* . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17 4.2 Function register-application . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17 4.3 Function start-file . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18

5 The Class APPLICATION 19 5.1 Method initialize-instance :after . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21 5.2 Method print-object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21 5.3 Function make-application . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21 5.4 Method startup-actions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22 5.5 Method cleanup-actions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22 5.6 Method (setf idle-timeout) :after . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23 5.7 Method handle-error . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23 5.8 Method idle-action . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23 5.9 Method restart-timer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23 5.10 Method send-message . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24 5.11 Method quit-app . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24

6 The Class DOCUMENT 25 6.1 Method initialize-instance :after . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28 6.2 Method print-object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28 6.3 Method (setf modified) :before . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28 6.4 Method create-windows . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29 6.5 Method standard-menu-items . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29 6.6 Method destroy-windows . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29 6.7 Method select-new-file . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29 6.8 Method rename . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30 6.9 Method resize-windows . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30 6.10 Method redraw-views . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30 6.11 Method new . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31 6.12 Method do-open . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31 6.13 Method select-old-file . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31 6.14 Method minifinder . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31 6.15 Method save-as . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32 6.16 Method save . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32 6.17 Method revert . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32 6.18 Method do-close . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33 6.19 Method command-executed . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33 6.20 Method command-executed :after . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33 6.21 Method undo . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34 6.22 Method irreversible-change . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34 6.23 Method redo . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34 6.24 Method replay-history . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34 6.25 Method write-to-file . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35 6.26 Method read-from-file . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35 6.27 Method write-header-to-stream . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35 6.28 Method read-header-from-stream . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35 6.29 Method write-to-stream . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 36 6.30 Method read-from-stream . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 36 6.31 Method display-empty . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 36 6.32 Method create-checkpoint . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 36 6.33 Method restore-checkpoint . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37 6.34 Method postscript-print . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37 6.35 Method bitmap-print . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37 6.36 Method display-history-scroller . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37 6.37 Method test-callback . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 38 6.38 Method create-drop-command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 38

7 The Class VIEW 39 7.1 Function make-view . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41 7.2 Method determine-window-id . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 42 7.3 Method xor-foreground . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 42 7.4 Method destroyed . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 42 7.5 Method handle-button-press . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 43 7.6 Method button-press :around . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 43 7.7 Method button-press . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 44 7.8 Method key-press . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 44 7.9 Method key-release . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 45 7.10 Method force-redraw . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 45 7.11 Method invalidate-rectangle . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 45 7.12 Method clear-area . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 46 7.13 Method draw . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 46 7.14 Method draw :around . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 47 7.15 Method get-refresh-candidates . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 47 7.16 Method (setf view-objects) :after . . . . . . . . . . . . . . . . . . . . . . . . . . . . 48 7.17 Method resized . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 48 7.18 Graphic Primitives for Drawing into a View . . . . . . . . . . . . . . . . . . . . . . 48

7.18.1 Method draw-point . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 48 7.18.2 Method draw-points . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 49 7.18.3 Method draw-line . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 49 7.18.4 Method draw-lines . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 50 7.18.5 Method draw-segments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 50 7.18.6 Method draw-rectangle . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 51 7.18.7 Method draw-rectangles . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 51 7.18.8 Method draw-arc . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 52 7.18.9 Method draw-arcs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 53 7.18.10 Method draw-glyph . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 53 7.18.11 Method draw-glyphs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 54

8 The Class VIEW-OBJECT and its Subclasses 55

8.1 Class view-object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 55 8.1.1 Function make-view-object . . . . . . . . . . . . . . . . . . . . . . . . . . . 57 8.1.2 Method install . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 58 8.1.3 Method deinstall . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 58 8.1.4 Macro point-inside-rectangle . . . . . . . . . . . . . . . . . . . . . . . . . . 59 8.1.5 Method point-inside . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 59 8.1.6 Method inside-rectangle . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 59 8.1.7 Function rectangles-overlap . . . . . . . . . . . . . . . . . . . . . . . . . . . 60 8.1.8 Method move . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 60 8.1.9 Method resize . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 60 8.1.10 Method reconfigure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 61 8.1.11 Method invalidate-rectangle . . . . . . . . . . . . . . . . . . . . . . . . . . . 61 8.1.12 Method force-redraw . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 62 8.1.13 Method draw . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 62 8.1.14 Method button-press . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 63 8.1.15 Method double-clicked . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 63 8.1.16 Method (setf selected) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 64 8.1.17 Method draw-selected . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 64 8.1.18 Method draw-outline . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 65 8.1.19 Method constrain-position . . . . . . . . . . . . . . . . . . . . . . . . . . . . 65 8.1.20 Method constrain-size . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 65 8.1.21 Method which-resize-handle . . . . . . . . . . . . . . . . . . . . . . . . . . . 66 8.1.22 Method reconfigured-by-user . . . . . . . . . . . . . . . . . . . . . . . . . . 66 8.1.23 Method create-handle-command . . . . . . . . . . . . . . . . . . . . . . . . 66 8.1.24 Method handle-selection . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 67

8.2 Graphic Primitives for Drawing into View-Objects . . . . . . . . . . . . . . . . . . 67 8.2.1 Method draw-point . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 67 8.2.2 Method draw-points . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 68 8.2.3 Method draw-line . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 68 8.2.4 Method draw-lines . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 69 8.2.5 Method draw-segments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 69 8.2.6 Method clear-area . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 70 8.2.7 Method draw-rectangle . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 71 8.2.8 Method draw-rectangles . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 71 8.2.9 Method draw-arc . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 72 8.2.10 Method draw-arcs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 72 8.2.11 Method draw-glyph . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 73 8.2.12 Method draw-glyphs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 74 8.3 Class direct-manipulation-object . . . . . . . . . . . . . . . . . . . . . . . . . . . . 74

8.3.1 Function make-direct-manipulation-object . . . . . . . . . . . . . . . . . . . 77 8.4 Class movable-icon . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 77

8.4.1 Function make-movable-icon . . . . . . . . . . . . . . . . . . . . . . . . . . 80 8.4.2 Method pathname->image . . . . . . . . . . . . . . . . . . . . . . . . . . . 81 8.4.3 Method image->image-z . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 81 8.4.4 Method image->pixmap . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 82 8.4.5 Method draw . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 82 8.4.6 Method draw-outline . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 83 8.4.7 Method draw-selected . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 83 8.4.8 Method point-inside . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 84

9 The Class CALLBACK 85 9.1 Method print-object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 85 9.2 Function make-callback . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 86 9.3 Function print-parms . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 86 9.4 Method execute . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 87 9.5 Method execute . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 87

10 The Class COMMAND and its Subclasses 88

10.1 Class command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 88 10.1.1 Function make-command . . . . . . . . . . . . . . . . . . . . . . . . . . . . 89 10.1.2 Method submit . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 89 10.1.3 Method executable . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 90 10.1.4 Method doit . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 90 10.1.5 Method scroll-before-undo . . . . . . . . . . . . . . . . . . . . . . . . . . . . 90 10.1.6 Method undoit . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 91 10.1.7 Method scroll-before-redo . . . . . . . . . . . . . . . . . . . . . . . . . . . . 91 10.1.8 Method redoit . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 91 10.1.9 Method commit . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 92

10.2 Class mouse-down-command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 92 10.2.1 Function make-mouse-down-command . . . . . . . . . . . . . . . . . . . . . 94 10.2.2 Method constrain-mouse . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 94 10.2.3 Method draw-feedback . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 95 10.2.4 Method draw-feedback :around . . . . . . . . . . . . . . . . . . . . . . . . . 95 10.2.5 Method track-mouse . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 96 10.2.6 Method mouse-idle . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 97 10.2.7 Method not-submitted . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 97 10.2.8 Method scroll-before-redo . . . . . . . . . . . . . . . . . . . . . . . . . . . . 97 10.2.9 Method mouse-rectangle . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 98

10.3 Class object-mover . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 98 10.3.1 Function make-object-mover . . . . . . . . . . . . . . . . . . . . . . . . . . 100 10.3.2 Method constrain-mouse . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 101 10.3.3 Method draw-feedback . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 101 10.3.4 Method track-mouse . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 102 10.3.5 Method doit . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 102 10.3.6 Method undoit . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 103 10.3.7 Method redoit . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 103

10.4 Class object-resizer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 103 10.4.1 Function make-object-resizer . . . . . . . . . . . . . . . . . . . . . . . . . . 106 10.4.2 Method constrain-mouse . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 106 10.4.3 Method draw-feedback . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 107 10.4.4 Method track-mouse . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 107 10.4.5 Method doit . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 108 10.4.6 Method undoit . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 108 10.4.7 Method redoit . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 108

10.5 Class object-selector . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 109 10.5.1 Function make-object-selector . . . . . . . . . . . . . . . . . . . . . . . . . . 111 10.5.2 Method draw-feedback . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 111 10.5.3 Method doit . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 112 10.5.4 Method not-submitted . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 112

10.6 Class drag-command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 113 10.6.1 Function make-drag-command . . . . . . . . . . . . . . . . . . . . . . . . . 114 10.6.2 Method draw-target-feedback . . . . . . . . . . . . . . . . . . . . . . . . . . 115 10.6.3 Method track-target . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 115 10.6.4 Method not-submitted . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 116

11 The Class WIDGET and its Subclasses 117

11.1 Class widget . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 117 11.1.1 Function make-widget . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 118 11.1.2 Method add-event-handler . . . . . . . . . . . . . . . . . . . . . . . . . . . . 119 11.1.3 Method inspect-clicked . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 119 11.1.4 Method son-created . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 119 11.1.5 Method get-motif-resources . . . . . . . . . . . . . . . . . . . . . . . . . . . 120 11.1.6 Method set-motif-resources . . . . . . . . . . . . . . . . . . . . . . . . . . . 120 11.1.7 Macro more-initargs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 120 11.1.8 Macro more-motif-resources . . . . . . . . . . . . . . . . . . . . . . . . . . . 121 11.1.9 Method destroy . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 121 11.1.10 Method manage . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 121 11.1.11 Method unmanage . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 122 11.1.12 Method update-slots . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 122 11.1.13 Method move . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 122 11.1.14 Method resize . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 123 11.1.15 Method root-coordinates . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 123 11.1.16 Method get-clx-window . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 123 11.1.17 Method point-inside . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 124 11.1.18 Method add-to-tab-group . . . . . . . . . . . . . . . . . . . . . . . . . . . . 124 11.1.19 Method remove-from-tab-group . . . . . . . . . . . . . . . . . . . . . . . . . 124 11.1.20 Method set-keyboard-focus . . . . . . . . . . . . . . . . . . . . . . . . . . . 125 11.1.21 Method set-sensitivity . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 125 11.1.22 Method enclosing-shell . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 125 11.1.23 Method define-cursor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 126

11.2 Class shell . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 126 11.2.1 Function make-shell . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 127 11.2.2 Method handle-button-press . . . . . . . . . . . . . . . . . . . . . . . . . . . 128 11.2.3 Method pop-up . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 128 11.2.4 Method pop-down . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 129 11.2.5 Method enclosing-shell . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 129

11.3 Class toplevel-shell . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 129 11.3.1 Function make-toplevel-shell . . . . . . . . . . . . . . . . . . . . . . . . . . 131 11.3.2 Method pop-up :after . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 131 11.3.3 Method resized-by-user . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 131 11.3.4 Method expose . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 132 11.3.5 Method destroy . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 132 11.3.6 Method closed-by-wm . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 132 11.3.7 Macro with-cursor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 133

11.3.8 Macro with-clock-cursor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 133 11.4 Class modeless-dialog-shell . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 133

11.4.1 Function make-modeless-dialog-shell . . . . . . . . . . . . . . . . . . . . . . 135 11.4.2 Method pop-up . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 135 11.4.3 Method pop-down . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 136

11.5 Class modal-dialog-shell . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 136 11.5.1 Function make-modal-dialog-shell . . . . . . . . . . . . . . . . . . . . . . . . 137 11.5.2 Method closed-by-wm . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 138

11.6 Class menu-shell . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 138

11.6.1 Function make-menu-shell . . . . . . . . . . . . . . . . . . . . . . . . . . . . 139 11.7 Class basic-document-shell . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 140

11.7.1 Function make-basic-document-shell . . . . . . . . . . . . . . . . . . . . . . 141 11.7.2 Method destroy :before . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 141 11.7.3 Method closed-by-wm . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 142

11.8 Class document-shell . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 142

11.8.1 Function make-document-shell . . . . . . . . . . . . . . . . . . . . . . . . . 144 11.9 Class document-shell-with-scroller . . . . . . . . . . . . . . . . . . . . . . . . . . . 144

11.9.1 Function make-document-shell-with-scroller . . . . . . . . . . . . . . . . . . 146 11.10Class label . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 146

11.10.1 Function make-label . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 147 11.11Class drag-label . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 147

11.11.1 Function make-drag-label . . . . . . . . . . . . . . . . . . . . . . . . . . . . 148 11.12Class toggle-button . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 148

11.12.1 Function make-toggle-button . . . . . . . . . . . . . . . . . . . . . . . . . . 149 11.12.2 Method execute-value-changed-callback . . . . . . . . . . . . . . . . . . . . 150

11.13Class push-button . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 150 11.13.1 Function make-push-button . . . . . . . . . . . . . . . . . . . . . . . . . . . 151 11.13.2 Method execute-activate-callback . . . . . . . . . . . . . . . . . . . . . . . . 152

11.14Class cascade-button . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 152

11.14.1 Function make-cascade-button . . . . . . . . . . . . . . . . . . . . . . . . . 153 11.15Class arrow-button . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 153

11.15.1 Function make-arrow-button . . . . . . . . . . . . . . . . . . . . . . . . . . 154 11.15.2 Method execute-activate-callback . . . . . . . . . . . . . . . . . . . . . . . . 154

11.16Class scale . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 155 11.16.1 Function make-scale . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 156 11.16.2 Method execute-value-changed-callback . . . . . . . . . . . . . . . . . . . . 156

11.17Class scrollbar . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 157 11.17.1 Function make-scrollbar . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 158 11.17.2 Method execute-value-changed-callback . . . . . . . . . . . . . . . . . . . . 158

11.18Class main-menu . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 159 11.18.1 Function make-main-menu . . . . . . . . . . . . . . . . . . . . . . . . . . . . 160 11.18.2 Method insert-menu-entry . . . . . . . . . . . . . . . . . . . . . . . . . . . . 160 11.18.3 Method remove-menu-entry . . . . . . . . . . . . . . . . . . . . . . . . . . . 161 11.18.4 Method find-menu-entry . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 161 11.18.5 Method add-menu-command . . . . . . . . . . . . . . . . . . . . . . . . . . 161

11.19Class menu-entry . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 162

11.19.1 Method (setf sensitive) :after . . . . . . . . . . . . . . . . . . . . . . . . . . 162 11.20Class button-entry . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 162

11.20.1 Function make-button-entry . . . . . . . . . . . . . . . . . . . . . . . . . . . 163 11.20.2 Method (setf label-string) :after . . . . . . . . . . . . . . . . . . . . . . . . . 164 11.20.3 Method (setf accelerator) :after . . . . . . . . . . . . . . . . . . . . . . . . . 164 11.20.4 Method (setf acc-modifier) :after . . . . . . . . . . . . . . . . . . . . . . . . 164

11.21Class toggle-entry . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 164 11.21.1 Function make-toggle-entry . . . . . . . . . . . . . . . . . . . . . . . . . . . 165 11.21.2 Method (setf value) :after . . . . . . . . . . . . . . . . . . . . . . . . . . . . 165

11.22Class toggle-group-entry . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 166 11.22.1 Function make-toggle-group-entry . . . . . . . . . . . . . . . . . . . . . . . 167 11.22.2 Method (setf value) :before . . . . . . . . . . . . . . . . . . . . . . . . . . . 168 11.22.3 Method set-item-list . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 168

11.23Class radio-group-entry . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 169 11.23.1 Function make-radio-group-entry . . . . . . . . . . . . . . . . . . . . . . . . 170 11.23.2 Method set-item-list . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 170

11.24Class menu-bar . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 171

11.24.1 Function make-menu-bar . . . . . . . . . . . . . . . . . . . . . . . . . . . . 172 11.25Class option-menu . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 172

11.25.1 Function make-option-menu . . . . . . . . . . . . . . . . . . . . . . . . . . . 173 11.25.2 Method set-item-list . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 173 11.25.3 Method execute-value-changed-callback . . . . . . . . . . . . . . . . . . . . 174 11.25.4 Method (setf value) :after . . . . . . . . . . . . . . . . . . . . . . . . . . . . 175

11.26Class menu-pulldown . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 175

11.26.1 Function make-menu-pulldown . . . . . . . . . . . . . . . . . . . . . . . . . 175 11.27Class main-window . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 176

11.27.1 Function make-main-window . . . . . . . . . . . . . . . . . . . . . . . . . . 176 11.28Class scroller . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 177

11.28.1 Function make-scroller . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 177 11.28.2 Method son-created . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 178 11.28.3 Method scroll-to . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 178 11.28.4 Method show-point . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 179 11.28.5 Method point-visible . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 179

11.29Class separator . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 179

11.29.1 Function make-separator . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 180 11.30Class frame . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 180

11.30.1 Function make-frame . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 181 11.31Class paned-window . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 181

11.31.1 Function make-paned-window . . . . . . . . . . . . . . . . . . . . . . . . . . 181 11.31.2 Function define-pane-constraint . . . . . . . . . . . . . . . . . . . . . . . . . 182

11.32Class row-column . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 182

11.32.1 Function make-row-column . . . . . . . . . . . . . . . . . . . . . . . . . . . 183 11.33Class labeled-frame . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 183

11.33.1 Function make-labeled-frame . . . . . . . . . . . . . . . . . . . . . . . . . . 184 11.34Class toggle-button-group . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 184

11.34.1 Function make-toggle-button-group . . . . . . . . . . . . . . . . . . . . . . . 185 11.34.2 Method (setf value) :before . . . . . . . . . . . . . . . . . . . . . . . . . . . 186 11.34.3 Method set-item-list . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 186 11.34.4 Method execute-value-changed-callback . . . . . . . . . . . . . . . . . . . . 187

11.35Class radio-button-group . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 187 11.35.1 Function make-radio-button-group . . . . . . . . . . . . . . . . . . . . . . . 189 11.35.2 Method set-item-list . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 189

11.36Class selection-list . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 190 11.36.1 Function make-selection-list . . . . . . . . . . . . . . . . . . . . . . . . . . . 191 11.36.2 Method (setf value) :after . . . . . . . . . . . . . . . . . . . . . . . . . . . . 191 11.36.3 Method set-item-list . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 192 11.36.4 Method show-item . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 193

11.37Class scrollable-selection-list . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 193

11.37.1 Function make-scrollable-selection-list . . . . . . . . . . . . . . . . . . . . . 194 11.38Class bulletin-board . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 194

11.38.1 Function make-bulletin-board . . . . . . . . . . . . . . . . . . . . . . . . . . 195 11.39Class form . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 195

11.39.1 Function make-form . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 196 11.39.2 Function define-form-constraint . . . . . . . . . . . . . . . . . . . . . . . . . 196

11.40Class text . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 197

11.40.1 Function make-text . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 198 11.41Class scrolled-text . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 198

11.41.1 Function make-scrolled-text . . . . . . . . . . . . . . . . . . . . . . . . . . . 199 11.42Class labeled-text . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 199

11.42.1 Function make-labeled-text . . . . . . . . . . . . . . . . . . . . . . . . . . . 200 11.42.2 Method (setf label-position) :after . . . . . . . . . . . . . . . . . . . . . . . 201

11.43Class dialog-box . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 201

11.43.1 Method closed-by-wm . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 202 11.44Class modeless-dialog-box . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 202

11.44.1 Function make-modeless-dialog-box . . . . . . . . . . . . . . . . . . . . . . . 203 11.44.2 Method (setf default-button) :after . . . . . . . . . . . . . . . . . . . . . . . 204 11.44.3 Method pop-up . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 204 11.44.4 Method pop-down . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 205

11.45Class modal-dialog-box . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 205 11.45.1 Function make-modal-dialog-box . . . . . . . . . . . . . . . . . . . . . . . . 207 11.45.2 Method (setf default-button) :after . . . . . . . . . . . . . . . . . . . . . . . 207 11.45.3 Method pop-up . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 207 11.45.4 Method pop-down . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 208

11.46Class tool-dialog-box . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 208 11.46.1 Function make-tool-dialog-box . . . . . . . . . . . . . . . . . . . . . . . . . 210 11.46.2 Method pop-up . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 210 11.46.3 Method pop-down . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 211

11.47Class dialog-dismiss-button . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 211 11.47.1 Function make-dialog-dismiss-button . . . . . . . . . . . . . . . . . . . . . . 212 11.47.2 Method execute-activate-callback . . . . . . . . . . . . . . . . . . . . . . . . 212

11.48Class dialog-dismiss-button-row . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 213 11.48.1 Function make-dialog-dismiss-button-row . . . . . . . . . . . . . . . . . . . 213

12 Predefined Standard Dialogs 215 12.1 Function warning-dialog . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 215 12.2 Function question-dialog . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 215 12.3 Function confirm-dialog . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 216 12.4 Function alternative-dialog . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 216 12.5 Function select-dialog . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 217 12.6 Function make-open-dialog-box . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 217 12.7 Function make-save-dialog-box . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 217 12.8 Variable *inspected-object* . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 218 12.9 Function inspect-dialog . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 218

13 Background Processes 219 13.1 Macro in-background-process . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 219 13.2 Method kill-background-process . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 219 13.3 Method kill-all-background-processes . . . . . . . . . . . . . . . . . . . . . . . . . . 220 13.4 Macro with-application . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 220 13.5 Macro with-document . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 220 13.6 Macro with-clm-connection . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 220 13.7 Macro with-progress-bar . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 221 13.8 Function progress-bar-aborted . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 221

13.9 Function indicate-progress . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 222

14 Some Utilities for File System Handling 223 14.1 Function name-and-type . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 223 14.2 Function current-directory-wildcard . . . . . . . . . . . . . . . . . . . . . . . . . . . 223 14.3 Function directory-wildcard . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 224 14.4 Function subdirectory-wildcard . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 224 14.5 Function parent-directory-wildcard . . . . . . . . . . . . . . . . . . . . . . . . . . . 225 14.6 Function parent-directory-wildcards . . . . . . . . . . . . . . . . . . . . . . . . . . 225 14.7 Function parent-directory . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 226 14.8 Function parent-directories . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 226 14.9 Function root-directory-p . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 226 14.10Function root-directory-wildcard . . . . . . . . . . . . . . . . . . . . . . . . . . . . 227 14.11Function directoryp . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 227 14.12Function pathname-equal . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 228 14.13Function pathname-name< . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 228 14.14Function file-exists . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 228 14.15Function replace-returns . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 229 14.16Function unreplace-returns . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 229 14.17Function find-bitmap . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 229 14.18Function shell-command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 229

15 Calling GINA Functions from the Editor 230 15.1 Macro with-application-stopped . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 230 15.2 Function rotate-applications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 230 15.3 Function focus-application . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 231 15.4 Macro defginapackage . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 231

Index 232

Chapter 1

Introduction

This manual is the complete description of the programming interface of GINA Version 2.1 for CommonLisp. It contains detailed descriptions of all classes, methods, function, macros, and global variables which are important for the implementor of a GINA application. The information contained in this manual can also be examined using an interactive program called the GINA Browser. The entries for each routine are automatically extracted from the GINA source code which contains semiformal comments. Therefore, the manual can be immediately updated whenever a modification is relevant for the programming interface. The first chapter contains the hierarchy of the GINA classes. There are references to the description of each class. Further chapters are concerned with groups of related functions or variables. For each function, the parameters are explained and a description of the returned value is given if it is relevant. Often, concrete examples demonstrate the use of a function. Each class is described in a separate chapter. There is a short description of each relevant slot. The slots inherited by superclasses are also listed. The class description contains an overview of all direct and inherited methods and their parameters. The only exception is that for subclasses of class widget only the direct methods are listed. Single characters before each method indicate whether the method can be called by an application (c), must be called (C), can be overridden (o), or must be overridden (O) by an application. Following the description of a class a complete description of all its methods is given. In the Browser the description of a routine or class is somewhat shorter, but instead there are commands to collect further information (e.g. to find all methods of a class). For those who are interested in the GINA source code it should be noted that the entries in the manual correspond to the order of the definitions in the source files. The files are scanned in the following order:

• globals.lisp

• framework.lisp

• views.lisp

• commands.lisp

• motif-widgets.lisp

• dialogs.lisp

• background.lisp

• OS-dependent.lisp

Chapter 2

The Hierarchy of GINA Classes

application  (Page 19)

the superclass of all GINA applications

document  (Page 25)

the superclass of all documents

view-object  (Page 55)

the superclass of all objects shown in views

▷ direct-manipulation-object  (Page 74)

a view-object with direct-manipulation capabilities

▷ ▷ movable-icon  (Page 77)

a direct manipulation-object displaying a pixmap

command  (Page 88)

an object representing a single user action

▷ drag-command  (Page 113)

a command class to implement drag and drop across windows

▷ mouse-down-command  (Page 92)

a mouse command with feedback as long as the mouse is down

▷ ▷ object-mover  (Page 98)

a mouse-down-command to move a direct-manipulation-object

▷ ▷ object-resizer  (Page 103)

a mouse-down-command to resize a direct-manipulation-object

▷ ▷ object-selector  (Page 109)

a mouse-down-command to select direct-manipulation-objects

callback  (Page 85)

a data object describing an action to do later

widget  (Page 117)

the abstract superclass of all CLOS-Objects encapsulating Motif widgets

▷ arrow-button  (Page 153)

the Motif arrow button widget

▷ bulletin-board  (Page 194)

the Motif bulletin board widget

▷ ▷ form  (Page 195)

the Motif form widget

▷ ▷ ▷ dialog-box  (Page 201)

a superclass for gina dialog boxes

▷ ▷ ▷ ▷ modal-dialog-box  (Page 205)

a form with a shell around it for modal dialogs

▷ ▷ ▷ ▷ modeless-dialog-box  (Page 202)

a form with a shell around it for modeless dialogs

▷ ▷ ▷ ▷ tool-dialog-box  (Page 208)

a form with a shell around it for tool dialogs with a menu

▷ frame  (Page 180)

the Motif frame widget

▷ ▷ labeled-frame  (Page 183)

a frame with a label on top

▷ label  (Page 146)

the Motif label widget

▷ ▷ cascade-button  (Page 152)

the Motif cascade button widget

▷ ▷ drag-label  (Page 147)

a picture label for drag and drop

▷ ▷ push-button  (Page 150)

the Motif push button widget

▷ ▷ ▷ dialog-dismiss-button  (Page 211)

a push-button to dismiss a dialog box

▷ ▷ toggle-button  (Page 148)

the Motif toggle button widget

▷ main-window  (Page 176)

the Motif main-window widget

▷ menu-bar  (Page 171)

a special kind of row-column widget

▷ ▷ main-menu  (Page 159)

a menu-bar plus its popup shells

▷ menu-pulldown  (Page 175)

the Motif row-column widget operating as a menu pane

▷ option-menu  (Page 172)

the Motif option menu widget

▷ paned-window  (Page 181)

the Motif paned window widget

▷ row-column  (Page 182)

the Motif row-column widget

▷ ▷ dialog-dismiss-button-row  (Page 213)

a row of dialog-dismiss-buttons with the leftmost as default

▷ ▷ toggle-button-group  (Page 184)

a group of toggle buttons with optional label and frame

▷ ▷ ▷ radio-button-group  (Page 187)

a group of radio buttons with optional label and frame

▷ scale  (Page 155)

the Motif scale widget

▷ scrollbar  (Page 157)

the Motif scroll bar widget

▷ scroller  (Page 177)

the Motif scrolled-window widget

▷ selection-list  (Page 190)

the Motif List widget

▷ ▷ scrollable-selection-list  (Page 193)

a selection-list inside a scroller

▷ separator  (Page 179)

the Motif separator widget

▷ shell  (Page 126)

the abstract superclass of all Motif-shells

▷ ▷ menu-shell  (Page 138)

the Motif menu-shell widget

▷ ▷ modal-dialog-shell  (Page 136)

the Motif dialog-shell widget used for modal dialogs

▷ ▷ toplevel-shell  (Page 129)

the abstract superclass of all document-shells and modeless dialog boxes

▷ ▷ ▷ basic-document-shell  (Page 140)

a toplevel-shell for a document without a menubar

▷ ▷ ▷ ▷ document-shell  (Page 142)

a toplevel-shell with a main-menu, representing a document

▷ ▷ ▷ ▷ ▷ document-shell-with-scroller  (Page 144)

a document-shell with a single scroller

▷ ▷ ▷ modeless-dialog-shell  (Page 133)

the Motif dialog-shell widget used for modeless dialogs

▷ text  (Page 197)

the Motif text widget

▷ ▷ labeled-text  (Page 199)

a text widget with a label

▷ ▷ scrolled-text  (Page 198)

a text widget inside a scroller

▷ view  (Page 39)

a drawing area where document contents are shown

Some Global Variables of GINA

3.1 *bitmap-directories* Variable

Value: list of directories where bitmaps are searched. Default: DEPENDS ON YOUR SITE You can modify this variable during the installation of GINA.

3.2 *default-toolkit-host* Variable

Value: name of host where toolkit server runs. Default: automatically start server on local host You can modify this variable if the server runs on a remote host.

3.3 *default-display-host* Variable

Value: name of host where X server runs. Default: the local host You can modify this variable if the server runs on a remote host.

3.4 *default-display-number* Variable

Value: number of display on host where X server runs.

Default: 0 You can modify this variable if the server runs on a display other than 0.

3.5 *default-screen-number* Variable

Value: number of screen on host where X server runs. Default: 0 You can modify this variable if the server runs on a screen other than 0.

3.6 *application* Variable

Value: in each process a pointer to its application object. Default: the own application object You can modify this variable inside the editor to focus on another application. The macro with-application-stopped sets the global copy of this variable

3.7 *display* Variable

Value: in each process a pointer to a CLX display structure. Default: the own CLX display structure You can modify this variable inside the editor to focus on another application. The macro with-application-stopped sets the global copy of this variable

3.8 *running-applications* Variable

Value: the list of all running applications, maybe on different displays. Default: none You can modify this variable using the function focus-application.

3.9 *inspect-click* Variable

Value: flag if inspect click is generally enabled. Default: inspect click enabled You can modify this variable to turn off this debugging facility.

3.10 *debug-menu* Variable

Value: flag if debug menu is generally present. Default: debug menu is present You can modify this variable to turn off this debugging facility.

3.11 *clx-synchronous* Variable

Value: flag if CLX is generally run in synchronous mode. Default: not synchronous You can modify this variable to turn on this debugging facility.

3.12 *drag-n-drop-transfer-value* Variable

Value: value to be transferred between applications by drag-and-drop. Default: none Normally, you do not modify this variable.

3.13 make-object Function

Purpose: call make-instance with a list of additional inits.

(defun make-object (class more-inits &rest init-plist))

The returned value is the newly created object. You can call this function in the constructor of a new class with no superclasses. It is called by GINA whenever any object is created.

Global Application Management

4.1 *loaded-applications* Variable

Value: the list of all loaded and registered applications.

Default: none

You can modify this variable by calling the function register-application.

4.2 register-application Function

Purpose: make application class known to the finder.

(defun register-application (signature application-class file-type))

signature: a short string application-class: a symbol denoting an application file-type: a short string

You call this function in each application. It is never called by GINA. This Function is called once for each application class.

Example

(register-application "bitedit" 'bitmap-editor "bitmap")

Signature bitedit denotes application bitmap-editor

4.3 start-file Function

Purpose: start the given file which may be a document or an application.

(defun start-file (pathname &key (display-host (display-host *application*))
                   (display-number (display-number *application*))
                   (screen-number (screen-number *application*))
                   (toolkit-host (toolkit-host *application*)) (signature nil)
                   (from-document (first (document-list *application*)))))

pathname: pathname-object or string display-host: X display to use. By default the same as the calling application display-number: X display number to use. By default the same as the calling application screen-number: X screen number to use. By default the same as the calling application toolkit-host: toolkit server to use. By default the same as the calling application signature: will be automatically determined if not supplied from-document: where to popup possible error messages

You can call this function if a foreign document or application is to be started. It is sometimes called by GINA.

Example

(with-application-stopped (start-file "/vol/gina/documents/hello.appl"))

start an application

(with-application-stopped (start-file "/vol/gina/documents/five-rects.gredit"))

open a document

(with-application-stopped (start-file nil :signature "browser"))

start the browser

The Class APPLICATION

5 application Class

The class application is the superclass of all GINA applications. You must define a subclass of this class. GINA defines subclasses of this class: only in the demo applications. You create an instance of this class to run the empty application.

Shared Slots:

name name of application

Default: "GINA"

document-type class of application dependent documents

                       Default: 'document

signature internal identification of application

Default: "GINA"

file-type type field of pathnames for saved documents Default: "empty"

Local Slots:

display-host where the X-server runs display-number number of display on host where X-server runs screen-number number of screen on host where X-server runs toolkit-host where the toolkit-server runs debug flag for debugging-output document-list the document objects currently open

Default: nil

process the process running this application

Default: nil

mailbox a list of messages, sent by other applications

Default: nil

display the CLX-display used by this application Default: nil clx-synchronous flag if CLX is run in synchronous mode

                       Default: *clx-synchronous*

xtk-connection the Motif-connection used by this application

Default: nil

application-shell invisible shell, root of widget hierarchy toplevel-shells List of all toplevel shells

Default: nil

idle-timeout time interval in seconds between calls of method idle-action

Default: nil

timer-id id for xtk:change-timer and friends

Default: nil

timer-active-in-handlerkeyword parameter for xtk:create-timer

Default: nil

inspect-click flag whether inspect-click is enabled

                       Default: *inspect-click*

debug-menu flag whether debug menu is present

                       Default: *debug-menu*

just-print-errors flag whether errors are just printed or debugger is invoked

Default: t

feedback-animation flag for experimental mouse-feedback animation Default: nil

Methods of class application:

[o ] cleanup-actions ((app application))  (Page 22)

last actions after application has stopped to process events

[o ] handle-error ((app application) condition)  (Page 23)

handle conditions signalled by Lisp

[o ] idle-action ((app application))  (Page 23)

react to timeout when no events come in

[  ] (setf idle-timeout) :after (new-idle-timeout (app application))  (Page 23)

change timer when slot is modified

[ c] image->image-z ((appl application) image)  (Page 81)

look up cached image in z-format or convert to it and cache it

[ c] image->pixmap ((appl application) image drawable)  (Page 82)

lookup cached pixmap for image or create pixmap and cache it

[  ] initialize-instance :after ((app application) &rest initargs)  (Page 21)

initialize a just created instance

[ c] pathname->image ((appl application) pathname-or-image)  (Page 81)

look up cached image for pathname or read file and cache it

[o ] print-object ((app application) stream)  (Page 21)

specialized printed representation

[  ] quit-app ((app application))  (Page 24)

terminate the application

[ c] restart-timer ((app application))  (Page 23)

begin a new full time interval before timeout occurs

[ c] send-message ((app application) message)  (Page 24)

send a message to another application

[o ] startup-actions ((app application))  (Page 22)

initializations before application begins to process events

5.1 initialize-instance :after Method

Purpose: initialize a just created instance.

(defmethod initialize-instance :after ((app application) &rest initargs))

Deamon installed by GINA. This deamon is called immediately after instantiation. It initializes the slots of class application. You can add further :after methods to initialize your subclasses.

Related methods:

[  ] initialize-instance :after ((doc document) &rest initargs)  (Page 28)

initialize a just created instance

5.2 print-object Method

Purpose: specialized printed representation.

(defmethod print-object ((app application) stream))

You override this method to get a special printed representation. The default version prints name and host. Normally, you do not call this method. It is called by GINA to denote an application object. It is never overridden by GINA.

Related methods:

[o ] print-object ((cb callback) stream)  (Page 85)

specialized printed representation

[o ] print-object ((doc document) stream)  (Page 28)

specialized printed representation

5.3 make-application Function

Purpose: create and run an application object.

(defun make-application (&key (display-host *default-display-host*)
                         (display-number *default-display-number*)
                         (screen-number *default-screen-number*)
                         (toolkit-host *default-toolkit-host*)
                         (document-pathname nil) (extra-process t) (debug nil)
                         (class 'application) (more-inits nil)))

display-host: X display to use. display-number: X display number to use. screen-number: X screen number to use. toolkit-host: toolkit server to use. document-pathname: pathname-object or string or nil extra-process: whether the application runs in an extra process class: class of the desired application more-inits: additional initializations for the application subclass

This is the constructor function for class application. The returned value is a newly created object of class application. You can call this function in constructors for subclasses of application. It is called by GINA whenever an application is started.

Example

(make-application)

starts the empty application

(make-application :class 'micky:micky-application)

starts the micky mouse application

5.4 startup-actions Method

Purpose: initializations before application begins to process events.

(defmethod startup-actions ((app application)))

You override this method to initialize the application using *display* and xtk:*motif-connection*. The default version does not do anything. Normally, you do not call this method. It is called by GINA when connections to the servers have been opened. It is never overridden by GINA.

5.5 cleanup-actions Method

Purpose: last actions after application has stopped to process events.

(defmethod cleanup-actions ((app application)))

You override this method to cleanup at the end of the application. The default version does not do anything. Normally, you do not call this method. It is called by GINA before an application is stopped. It is never overridden by GINA.

5.6 (setf idle-timeout) :after Method

Purpose: change timer when slot is modified.

(defmethod (setf idle-timeout) :after (new-idle-timeout (app application)))

Deamon installed by GINA.

5.7 handle-error Method

Purpose: handle conditions signalled by Lisp.

(defmethod handle-error ((app application) condition))

condition: signalled condition

You override this method to define special error handling. The default version prints the error or invokes the debugger. Normally, you do not call this method. It is called by GINA whenever an error is signalled. It is never overridden by GINA. (throw ’xtk:proceed-from-error nil) resumes execution of main loop Just returning from this will enter the debugger

5.8 idle-action Method

Purpose: react to timeout when no events come in.

(defmethod idle-action ((app application)))

You override this method to react to timeouts. The default version does not do anything. Normally, you do not call this method. It is called by GINA whenever the specified timeout occurs. It is never overridden by GINA. You have to set the slot idle-timeout of your application to get timeouts.

5.9 restart-timer Method

Purpose: begin a new full time interval before timeout occurs.

(defmethod restart-timer ((app application)))

You rarely override this method or add deamons. The default version is sufficient for most cases. You can call this method. It is never called by GINA. It is never overridden by GINA.

5.10 send-message Method

Purpose: send a message to another application.

(defmethod send-message ((app application) message))

message: a function or a callback to be executed by the recipient

You rarely override this method or add deamons. The default version is sufficient for most cases. You can call this method to communicate with other applications. It is called by GINA to tell an application to open a document. It is never overridden by GINA.

Example

(with-application-stopped
  (send-message *application* (make-callback #'xlib:bell *display*)))

Tell *application* to beep

5.11 quit-app Method

Purpose: terminate the application.

(defmethod quit-app ((app application)))

You rarely override this method or add deamons. The default version closes all documents. Normally, you do not call this method. It is called by GINA in reaction to the quit menu entry. It is never overridden by GINA.

The Class DOCUMENT

6 document Class

The class document is the superclass of all documents. You must define a subclass of this class. GINA defines subclasses of this class: only in the demo applications. You never create an instance of this class.

Shared Slots:

max-history maximum number of past commands stored or NIL for unlimited history Default: nil

Local Slots:

file-pathname where the document is stored wildcard directory where the document is stored number used for ’Untitled <number>’ name the name part of the pathname modified flag if document was modified since last save

Default: nil

undo-commands list of undoable commands

Default: nil

redo-commands list of redoable commands

Default: nil

active-mouse-command pointer to the currently active mouse-command

Default: nil

toplevel-shells list of all toplevel shells

Default: nil

views all views showing the document contents main-view the application can store the most important view here

Default: nil

main-shell the toplevel-window of the document shell-width width of the shell for this document

Default: :auto shell-height height of the shell for this document

Default: :auto

active-modal-dialogs stack of modal dialogs currently visible

Default: nil

undo-menu-entry dynamically changing menu entry for UNDO

Default: nil

redo-menu-entry dynamically changing menu entry for REDO

Default: nil

docs-menu-entry changing menu entry for DOCUMENTS

Default: nil

save-menu-entry sometimes insensitive menu entry for SAVE

Default: nil

revert-menu-entry sometimes insensitive menu entry for REVERT

Default: nil

background-processes list of all running background processes

Default: nil

drag-protocols a list of keywords of accepted drag-commands Default: nil

Methods of class document:

[  ] bitmap-print ((doc document))  (Page 37)

hardcopy bitmap of the main view

[  ] command-executed :after ((doc document))  (Page 33)

adjust undo/redo menu entries

[o ] command-executed ((doc document))  (Page 33)

inform document that a command has been executed

[  ] create-checkpoint ((doc document))  (Page 36)

create a string describing the document contents

[o ] create-drop-command ((doc document) shell x y protocol-id transfer-value received-from)  (Page 38)

create a duplicate drag-command

[O ] create-windows ((doc document))  (Page 29)

create the windows belonging to this document

[o ] destroy-windows ((doc document))  (Page 29)

destroy all windows belonging to this document

[o ] display-empty ((doc document))  (Page 36)

init and display empty document

[  ] display-history-scroller ((doc document))  (Page 37)

pop-up history scroller, create if necessary

[  ] do-close ((doc document))  (Page 33)

close document; ask for save if modified

[  ] do-open ((doc document))  (Page 31)

let user select a document of this type and open it

[  ] initialize-instance :after ((doc document) &rest initargs)  (Page 28)

initialize a just created instance

[ c] irreversible-change ((doc document))  (Page 34)

clear the command history

[ c] kill-all-background-processes ((doc document))  (Page 220)

kill all background processes and wait for them to die

[ c] kill-background-process ((doc document) process)  (Page 219)

kill process, but wait until he is out of critical sections

[  ] minifinder ((doc document))  (Page 31)

let user select any document or application and open it

[  ] (setf modified) :before (new-value (doc document))  (Page 28)

set sensitivity of SAVE and REVERT menu entries

[  ] new ((doc document))  (Page 31)

execute the NEW menu item

[  ] postscript-print ((doc document))  (Page 37)

hardcopy document on postscript printer

[o ] print-object ((doc document) stream)  (Page 28)

specialized printed representation

[  ] read-from-file ((doc document) pathname &key (create-windows t))  (Page 35)

read the document from the specified file

[O ] read-from-stream ((doc document) stream)  (Page 36)

read the document contents from the specified stream

[  ] read-header-from-stream ((doc document) stream)  (Page 35)

read the window-size from the specified stream

[  ] redo ((doc document) &key (update-history-scroller t))  (Page 34)

redo the last command undone

[oc] redraw-views ((doc document))  (Page 30)

redraw all views, because the document contents have changed

[o ] rename ((doc document) new-pathname)  (Page 30)

react when user has changed the name of a document

[  ] replay-history ((doc document))  (Page 34)

undo all commands and then redo as an animation

[o ] resize-windows ((doc document))  (Page 30)

resize windows, because the document contents have changed

[  ] restore-checkpoint ((doc document) checkpoint)  (Page 37)

restore document from a checkpoint

[  ] revert ((doc document))  (Page 32)

read last saved version from file

[  ] save ((doc document))  (Page 32)

save document to file; ask for filename if not yet known

[  ] save-as ((doc document))  (Page 32)

let user select a new filename and save

[o ] select-new-file ((doc document))  (Page 29)

ask user for a pathname of a new document

[o ] select-old-file ((doc document) file-type)  (Page 31)

ask user for a pathname of an existing document

[o ] standard-menu-items ((document document) (shell document-shell))  (Page 29)

create the standard menu entries for this document

[o ] test-callback ((doc document))  (Page 38)

do some testing within a callback

[  ] undo ((doc document) &key (update-history-scroller t))  (Page 34)

undo the last command executed

[  ] write-header-to-stream ((doc document) stream)  (Page 35)

write the window-size to the specified stream

[  ] write-to-file ((doc document) pathname)  (Page 35)

write the document to the specified file

[O ] write-to-stream ((doc document) stream)  (Page 36)

write the document contents to the specified stream

6.1 initialize-instance :after Method

Purpose: initialize a just created instance.

(defmethod initialize-instance :after ((doc document) &rest initargs))

Deamon installed by GINA. This deamon is called immediately after instantiation. It initializes the slots of class document. You can add further :after methods to initialize your subclasses.

Related methods:

[  ] initialize-instance :after ((app application) &rest initargs)  (Page 21)

initialize a just created instance

6.2 print-object Method

Purpose: specialized printed representation.

(defmethod print-object ((doc document) stream))

You override this method to get a special printed representation. The default version prints name of document. Normally, you do not call this method. It is called by GINA to denote a document object. It is never overridden by GINA.

Related methods:

[o ] print-object ((app application) stream)  (Page 21)

specialized printed representation

[o ] print-object ((cb callback) stream)  (Page 85)

specialized printed representation

6.3 (setf modified) :before Method

Purpose: set sensitivity of SAVE and REVERT menu entries.

(defmethod (setf modified) :before (new-value (doc document)))

Deamon installed by GINA. You should never access the slot modified directly.

6.4 create-windows Method

Purpose: create the windows belonging to this document.

(defmethod create-windows ((doc document)))

You must override this method. The default version creates a window with some randomly distributed buttons. Normally, you do not call this method. It is called by GINA whenever a new document is created. It is never overridden by GINA.

6.5 standard-menu-items Method

Purpose: create the standard menu entries for this document.

(defmethod standard-menu-items ((document document) (shell document-shell)))

You override this method if you want completely different menu entries. The default version installs all the standard enries. Normally, you do not call this method. It is called by GINA when a document-shell is created. It is never overridden by GINA.

6.6 destroy-windows Method

Purpose: destroy all windows belonging to this document.

(defmethod destroy-windows ((doc document)))

You override this method if there are more windows than the toplevel shells. The default version deletes all toplevel-shells stored in the document. Normally, you do not call this method. It is called by GINA whenever a document is closed. It is never overridden by GINA.

6.7 select-new-file Method

Purpose: ask user for a pathname of a new document.

(defmethod select-new-file ((doc document)))

The returned value is T if a new pathname was selected, NIL otherwise. You override this method only if standard dialog box is not sufficient. The default version pops up the standard save-dialog-box. Normally, you do not call this method. It is called by GINA when appropriate. It is never overridden by GINA.

6.8 rename Method

Purpose: react when user has changed the name of a document.

(defmethod rename ((doc document) new-pathname))

You override this method if a renaming has further consequences. The default version changes the name, wildcard and title of the main window. Normally, you do not call this method. It is called by GINA when a document is renamed by the user. It is never overridden by GINA.

6.9 resize-windows Method

Purpose: resize windows, because the document contents have changed.

(defmethod resize-windows ((doc document)))

You override this method if also the window contents depend on the size. The default version resizes the shell. Normally, you do not call this method. It is called by GINA when a document is reverted to an old version. It is never overridden by GINA.

6.10 redraw-views Method

Purpose: redraw all views, because the document contents have changed.

(defmethod redraw-views ((doc document)))

You override this method to redisplay more parts of the display than the views. The default version redraws all views known to the doc. You can call this method to redisplay all content dependent information. It is called by GINA when a document is reverted to an old version. It is never overridden by GINA.

6.11 new Method

Purpose: execute the NEW menu item.

(defmethod new ((doc document)))

You rarely override this method or add deamons. The default version creates a new document. Normally, you do not call this method. It is called by GINA in reaction to the new menu entry. It is never overridden by GINA.

6.12 do-open Method

Purpose: let user select a document of this type and open it.

(defmethod do-open ((doc document)))

You rarely override this method or add deamons. The default version is sufficient for most cases. Normally, you do not call this method. It is called by GINA in reaction to the open menu entry. It is never overridden by GINA.

6.13 select-old-file Method

Purpose: ask user for a pathname of an existing document.

(defmethod select-old-file ((doc document) file-type))

The returned value is T if a pathname was selected, NIL otherwise. You override this method only if the standard open-dialog-box is not sufficient. The default version pops up standard the open-dialog-box. Normally, you do not call this method. It is called by GINA when appropriate. It is never overridden by GINA.

6.14 minifinder Method

Purpose: let user select any document or application and open it.

(defmethod minifinder ((doc document)))

You rarely override this method or add deamons. The default version is sufficient for most cases. Normally, you do not call this method. It is called by GINA in reaction to the minifinder menu entry. It is never overridden by GINA.

6.15 save-as Method

Purpose: let user select a new filename and save.

(defmethod save-as ((doc document)))

You rarely override this method or add deamons. The default version is sufficient for most cases. Normally, you do not call this method. It is called by GINA in reaction to the save-as menu entry. It is never overridden by GINA.

6.16 save Method

Purpose: save document to file; ask for filename if not yet known.

(defmethod save ((doc document)))

You rarely override this method or add deamons. The default version is sufficient for most cases. Normally, you do not call this method. It is called by GINA in reaction to the save menu entry. It is never overridden by GINA.

6.17 revert Method

Purpose: read last saved version from file.

(defmethod revert ((doc document)))

You rarely override this method or add deamons. The default version is sufficient for most cases. Normally, you do not call this method. It is called by GINA in reaction to the revert menu entry. It is never overridden by GINA.

6.18 do-close Method

Purpose: close document; ask for save if modified.

(defmethod do-close ((doc document)))

You rarely override this method or add deamons. The default version is sufficient for most cases. Normally, you do not call this method. It is called by GINA in reaction to the close menu entry. It is never overridden by GINA.

6.19 command-executed Method

Purpose: inform document that a command has been executed .

(defmethod command-executed ((doc document)))

You override this method to implement actions to be done after each command. The default version does not do anything. Normally, you do not call this method. It is called by GINA whenever a command is executed, undone, or redone. It is never overridden by GINA.

Related methods:

[  ] command-executed :after ((doc document))  (Page 33)

adjust undo/redo menu entries

6.20 command-executed :after Method

Purpose: adjust undo/redo menu entries.

(defmethod command-executed :after ((doc document)))

Deamon installed by GINA.

Related methods:

[o ] command-executed ((doc document))  (Page 33)

inform document that a command has been executed

6.21 undo Method

Purpose: undo the last command executed.

(defmethod undo ((doc document) &key (update-history-scroller t)))

You rarely override this method or add deamons. The default version is sufficient for most cases. Normally, you do not call this method. It is called by GINA in reaction to the undo menu entry. It is never overridden by GINA.

6.22 irreversible-change Method

Purpose: clear the command history.

(defmethod irreversible-change ((doc document)))

You rarely override this method or add deamons. The default version is sufficient for most cases. You can call this method to indicate that no more undo/redo possible now. It is called by GINA if an undoable command is executed that causes a change. It is never overridden by GINA.

6.23 redo Method

Purpose: redo the last command undone.

(defmethod redo ((doc document) &key (update-history-scroller t)))

You rarely override this method or add deamons. The default version is sufficient for most cases. Normally, you do not call this method. It is called by GINA in reaction to the redo menu entry. It is never overridden by GINA.

6.24 replay-history Method

Purpose: undo all commands and then redo as an animation.

(defmethod replay-history ((doc document)))

You rarely override this method or add deamons. The default version is sufficient for most cases. Normally, you do not call this method. It is called by GINA in reaction to the replay-history menu entry. It is never overridden by GINA.

6.25 write-to-file Method

Purpose: write the document to the specified file.

(defmethod write-to-file ((doc document) pathname))

You rarely override this method or add deamons. The default version opens the the pathname and writes header and contents. Normally, you do not call this method. It is called by GINA when the document is saved. It is never overridden by GINA.

6.26 read-from-file Method

Purpose: read the document from the specified file.

(defmethod read-from-file ((doc document) pathname &key (create-windows t)))

You rarely override this method or add deamons. The default version opens the the pathname and reads header and contents. Normally, you do not call this method. It is called by GINA when the document is opened. It is never overridden by GINA.

6.27 write-header-to-stream Method

Purpose: write the window-size to the specified stream.

(defmethod write-header-to-stream ((doc document) stream))

You rarely override this method or add deamons. The default version writes out signature, width and height. Normally, you do not call this method. It is called by GINA when the document is saved. It is never overridden by GINA.

6.28 read-header-from-stream Method

Purpose: read the window-size from the specified stream.

(defmethod read-header-from-stream ((doc document) stream))

You rarely override this method or add deamons. The default version reads signature, width and height. Normally, you do not call this method. It is called by GINA when the document is opened. It is never overridden by GINA.

6.29 write-to-stream Method

Purpose: write the document contents to the specified stream.

(defmethod write-to-stream ((doc document) stream))

You must override this method. The default version does not do anything. Normally, you do not call this method. It is called by GINA when the document is saved. It is never overridden by GINA.

6.30 read-from-stream Method

Purpose: read the document contents from the specified stream.

(defmethod read-from-stream ((doc document) stream))

You must override this method. The default version does not do anything. Normally, you do not call this method. It is called by GINA when the document is opened. It is never overridden by GINA.

6.31 display-empty Method

Purpose: init and display empty document.

(defmethod display-empty ((doc document)))

You override this method if even the empty document needs content-dependent widgets. The default version does not do anything. Normally, you do not call this method. It is called by GINA after a new empty document is created. It is never overridden by GINA.

6.32 create-checkpoint Method

Purpose: create a string describing the document contents.

(defmethod create-checkpoint ((doc document)))

You rarely override this method or add deamons. The default version just calls write-to-stream into a string. Normally, you do not call this method. It is called by GINA if an undoable command is implemented by a checkpoint. It is never overridden by GINA.

6.33 restore-checkpoint Method

Purpose: restore document from a checkpoint.

(defmethod restore-checkpoint ((doc document) checkpoint))

You rarely override this method or add deamons. The default version just calls read-from-stream with a string. Normally, you do not call this method. It is called by GINA if an undoable command is implemented by a checkpoint. It is never overridden by GINA.

6.34 postscript-print Method

Purpose: hardcopy document on postscript printer.

(defmethod postscript-print ((doc document)))

You rarely override this method or add deamons. The default version is sufficient for most cases. Normally, you do not call this method. It is called by GINA in reaction to the postscript-print menu entry. It is never overridden by GINA.

6.35 bitmap-print Method

Purpose: hardcopy bitmap of the main view.

(defmethod bitmap-print ((doc document)))

You rarely override this method or add deamons. The default version is sufficient for most cases. Normally, you do not call this method. It is called by GINA in reaction to the bitmap-print menu entry. It is never overridden by GINA.

6.36 display-history-scroller Method

Purpose: pop-up history scroller, create if necessary.

(defmethod display-history-scroller ((doc document)))

You rarely override this method or add deamons. The default version is sufficient for most cases. Normally, you do not call this method. It is called by GINA in reaction to the history scroller menu entry. It is never overridden by GINA.

6.37 test-callback Method

Purpose: do some testing within a callback.

(defmethod test-callback ((doc document)))

You override this method do test some code inside a callback. The default version pops up a warning dialog box. Normally, you do not call this method. It is called by GINA in response to the Test-Callback menu entry. It is never overridden by GINA.

6.38 create-drop-command Method

Purpose: create a duplicate drag-command.

(defmethod create-drop-command ((doc document) shell x y protocol-id
transfer-value received-from))

shell: the shell that received the cmd x: x-pos relative to shell y: y-pos relative to shell protocol-id: symbol identifying the cmd transfer-value: transfer-value from cmd received-from: x-window to send response to

You override this method to react to drop commands understood by this document. The default version does not do anything. Normally, you do not call this method. It is called by GINA when a drag command enters a shell of this doc. It is never overridden by GINA.

The Class VIEW

7 view Class

An instance of class view is a drawing area where document contents are shown. It is a subclass of widget. You must define a subclass of this class. GINA defines subclasses of this class: only in the demo applications. You create an instance of this class to make very simple tests.

Shared Slots:

\underline{view:} double-click-interval maximum time interval for double clicks in milliseconds

Default: 250

overlapping-objects flag whether view-objects can overlap. If not, some operations are more efficient.

Default: t

Local Slots:

\underline{view:} document the document shown in the view scroller the scroller containing the view, if any width width of the view in pixels height height of the view in pixels backing-store flag, whether backing-store is desired x-window CLX-structure denoting the underlying window

Default: nil

name-of-font name of default font for this view

Default: "9x15"

font default font for this view gcontext CLX graphics context used for drawing primitives

Default: nil

printing flag, whether drawing is currently done for printing Default: nil view-objects list of objects displayed in the view

Default: nil

propagate-button-press flag, whether button-press is propagated to the view-objects

Default: t

repeated-click Number of very recent clicks

Default: 1

last-click-time Internal real-time of last button-press event

Default: nil

\underline{widget:} widget-id integer returned by CLM create-widget call group-widget-id id used when the whole group is meant widget-id-for-sons may be different from widget-id in compound widgets parent the parent widget object in the hierarchy name name string for resource database lookup width total width in pixels height total height in pixels x-pos the x-coordinate relative to the parent y-pos the y-coordinate relative to the parent

Methods of class view:

[o ] button-press ((view view) code repetition x y)  (Page 44)

a button was pressed inside the view

[  ] button-press :around ((view view) code repetition x y)  (Page 43)

propagate button-press to hit view-object if any

[ c] clear-area ((view view) x y width height)  (Page 46)

turn area into background color

[o ] destroyed ((view view) ignore)  (Page 42)

the view has been destroyed

[o ] determine-window-id ((view view))  (Page 42)

ask for the window id of the underlying X-window

[  ] draw :around ((view view) count x y width height)  (Page 47)

draw all view-objects in the view after drawing directly in the view

[o ] draw ((view view) count x y width height)  (Page 46)

draw view contents from the internal representation

[ c] draw-arc ((view view) x y width height angle1 angle2 &optional (fill-p nil))  (Page 52)

call CLX Function to draw into the view

[ c] draw-arcs ((view view) arcs &optional (fill-p nil))  (Page 53)

call CLX Function to draw into the view

[ c] draw-glyph ((view view) x y elt &key translate width (size :default))  (Page 53)

call CLX Function to draw into the view

[ c] draw-glyphs ((view view) x y sequence &key (start 0) end translate width (size :default)) (Page 54)

call CLX Function to draw into the view

[ c] draw-line ((view view) x1 y1 x2 y2 &optional (relative-p nil))  (Page 49)

call CLX Function to draw into the view

[ c] draw-lines ((view view) points &key relative-p fill-p (shape :complex))  (Page 50)

call CLX Function to draw into the view

[ c] draw-point ((view view) x y)  (Page 48)

call CLX Function to draw into the view

[ c] draw-points ((view view) points &optional relative-p)  (Page 49)

call CLX Function to draw into the view

[ c] draw-rectangle ((view view) x y width height &optional (fill-p nil))  (Page 51)

call CLX Function to draw into the view

[ c] draw-rectangles ((view view) rectangles &optional (fill-p nil))  (Page 51)

call CLX Function to draw into the view

[ c] draw-segments ((view view) segments)  (Page 50)

call CLX Function to draw into the view

[ c] force-redraw ((view view))  (Page 45)

clear and redraw the whole view

[o ] get-refresh-candidates ((view view) objects x y width height)  (Page 47)

compute list of objects which may lie within invalidated rectangle

[o ] handle-button-press ((view view) &rest event-data)  (Page 43)

low level event handler for button-press events

[ c] install ((view-object view-object) (view view) &optional (x 0) (y 0) &key (redraw t)) (Page 58)

install a view-object in a view

[ c] invalidate-rectangle ((view view) x y width height)  (Page 45)

clear and redraw part of the view

[o ] key-press ((view view) char code modifiers x y)  (Page 44)

a key was pressed inside the view

[o ] key-release ((view view) char code modifiers x y)  (Page 45)

a key was released in the view

[o ] resized ((view view) ignore)  (Page 48)

the user has resized the view

[  ] (setf view-objects) :after (new-list (view view))  (Page 48)

clear cached reverse list of view-objects

[ c] xor-foreground ((view view) &optional (color-to-achieve (xlib:screen-black-pixel (screen *application*))))  (Page 42)

determine color value usable as gcontext-foregound for xor drawing

7.1 make-view Function

Purpose: create a new view where X graphics primitives can be used.

(defun make-view (parent &key (width 1000) (height 1000)
                  (document (first (document-list *application*)))
                  (backing-store nil) (double-buffering nil)
                  (resize-policy :none) (class 'view) (initargs nil)
                  (managed t) (motif-widget-class :gina-view)
                  (motif-resources nil)))

parent: the parent widget object width: the initial width of the view height: the initial height of the view document: the document shown in the view backing-store: flag, whether backing-store is desired double-buffering: flag, whether all output is buffered in a pixmap resize-policy: :any :grow or :none class: view or any subclass of it initargs: further initializations for view subclass motif-resources: further Motif resource settings

This is the constructor function for class view. The returned value is a newly created object of class view. You can call this function. It is sometimes called by GINA.

7.2 determine-window-id Method

Purpose: ask for the window id of the underlying X-window.

(defmethod determine-window-id ((view view)))

You override this method adding an :after deamon to do initializations when the x-window is known. The default version opens a font and creates a graphic-context. Normally, you do not call this method. It is called by GINA as soon as the widget has been realized. It is never overridden by GINA.

7.3 xor-foreground Method

Purpose: determine color value usable as gcontext-foregound for xor drawing.

(defmethod xor-foreground ((view view) &optional (color-to-achieve
(xlib:screen-black-pixel (screen *application*)))))
color-to-achieve:  a pixel value

The returned value is a pixel value that xors the view background to color-to-achieve. You rarely override this method or add deamons. The default version is sufficient for most cases. You can call this method to get feedback in a different color than black. It is called by GINA before draw-feedback to set gc foreground. It is never overridden by GINA.

7.4 destroyed Method

Purpose: the view has been destroyed.

(defmethod destroyed ((view view) ignore))

You override this method to do the necessary cleanup. The default version frees the gcontext. Normally, you do not call this method. It is called by GINA when appropriate. It is never overridden by GINA.

7.5 handle-button-press Method

Purpose: low level event handler for button-press events.

(defmethod handle-button-press ((view view) &rest event-data))

event-data: a list of event details

You override this method if you are interested in special event details. The default version calls method button-press with the important parameters. Normally, you do not call this method. It is called by GINA in response to button-press events. It is never overridden by GINA.

Related methods:

[o ] handle-button-press ((shell shell) &rest event-data)  (Page 128)

low level event handler for button-press events

7.6 button-press :around Method

Purpose: propagate button-press to hit view-object if any.

(defmethod button-press :around ((view view) code repetition x y))

code: which mouse button repetition: 1,2,3,.. for single, double, triple click x: relative mouse position in the view y: relative mouse position in the view

Deamon installed by GINA. This deamon determines whether button-press should be called at the view or if it is called at an object installed in the view.

Related methods:

[o ] button-press ((view view) code repetition x y)  (Page 44)

a button was pressed inside the view

[o ] button-press ((obj view-object) code repetition x y)  (Page 63)

react to button-press event in the object

7.7 button-press Method

Purpose: a button was pressed inside the view.

(defmethod button-press ((view view) code repetition x y))

code: which mouse button repetition: 1,2,3,.. for single, double, triple click x: relative mouse position in the view y: relative mouse position in the view

You override this method to define the desired reaction to mouse clicks. The default version selects objects installed in the view. Normally, you do not call this method. It is called by GINA in response to button-press events. It is never overridden by GINA. Code :select denotes the left mouse button. Code :extend denotes the middle mouse button (or Shift-left). Code :menu denotes the right mouse button (or Shift-Control-left). Code :toggle denotes ctrl-left Code :other denotes any other combination

Related methods:

[  ] button-press :around ((view view) code repetition x y)  (Page 43)

propagate button-press to hit view-object if any

[o ] button-press ((obj view-object) code repetition x y)  (Page 63)

react to button-press event in the object

7.8 key-press Method

Purpose: a key was pressed inside the view.

(defmethod key-press ((view view) char code modifiers x y))

char: the key character as a string code: integer identifying key modifiers: indicator for shift, ... x: mouse positioin in view when key was pressed y: mouse positioin in view when key was pressed

You override this method to define the desired reaction to key input. The default version does not do anything. Normally, you do not call this method. It is called by GINA in response to key-press events. It is never overridden by GINA.

7.9 key-release Method

Purpose: a key was released in the view.

(defmethod key-release ((view view) char code modifiers x y))

char: the key character as a string code: integer identifying key modifiers: indicator for shift, ... x: mouse positioin in view when key was pressed y: mouse positioin in view when key was pressed

You override this method to define the desired reaction to key input. The default version does not do anything. Normally, you do not call this method. It is called by GINA in response to key-release events. It is never overridden by GINA.

7.10 force-redraw Method

Purpose: clear and redraw the whole view.

(defmethod force-redraw ((view view)))

You rarely override this method or add deamons. The default version is sufficient for most cases. You can call this method to reflect changes of the internal representation in the display. It is called by GINA when appropriate. It is never overridden by GINA.

Related methods:

[ c] force-redraw ((view-object view-object))  (Page 62)

redraw the whole view-object

7.11 invalidate-rectangle Method

Purpose: clear and redraw part of the view.

(defmethod invalidate-rectangle ((view view) x y width height))

You rarely override this method or add deamons. The default version is sufficient for most cases. You can call this method to reflect changes of the internal representation in the display. It is called by GINA when appropriate. It is never overridden by GINA.

Related methods:

[ c] invalidate-rectangle ((view-object view-object) x y width height) (Page 61)

redraw part of the view-object

7.12 clear-area Method

Purpose: turn area into background color.

(defmethod clear-area ((view view) x y width height))

You rarely override this method or add deamons. The default version is sufficient for most cases. You can call this method. It is called by GINA when appropriate. It is never overridden by GINA.

Related methods:

[ c] clear-area ((view-object view-object) x y width height)  (Page 70)

call same method of the view, but take position into account

7.13 draw Method

Purpose: draw view contents from the internal representation.

(defmethod draw ((view view) count x y width height))

count: number of calls to draw method that will immediately follow x: upper left corner of rectangle which has to be drawn y: upper left corner of rectangle which has to be drawn width: size of rectangle which has to be drawn height: size of rectangle which has to be drawn

You override this method to define the graphical representation of your document. The default version does not do anything. Normally, you do not call this method. It is called by GINA in response to expose events. It is never overridden by GINA. You can simply draw the whole view when count is 0. Optimized versions just draw the necessary parts.

[o ] draw ((view-object view-object) count x y width height)  (Page 62)

draw view-object contents from the internal representation

[  ] draw :around ((view view) count x y width height)  (Page 47)

draw all view-objects in the view after drawing directly in the view

[  ] draw ((icon movable-icon) count x y width height)  (Page 82)

Draw icon optionally with shadow from stored pixmap

7.14 draw :around Method

Purpose: draw all view-objects in the view after drawing directly in the view.

(defmethod draw :around ((view view) count x y width height))

Deamon installed by GINA.

Related methods:

[o ] draw ((view view) count x y width height)  (Page 46)

draw view contents from the internal representation

[o ] draw ((view-object view-object) count x y width height)  (Page 62)

draw view-object contents from the internal representation

[  ] draw ((icon movable-icon) count x y width height)  (Page 82)

Draw icon optionally with shadow from stored pixmap

7.15 get-refresh-candidates Method

Purpose: compute list of objects which may lie within invalidated rectangle.

(defmethod get-refresh-candidates ((view view) objects x y width height))

The returned value is superset of candidate objects and flag whether set is exact, as multiple values. You override this method to optimize redraw of view-objects using application-specific information. The default version simply returns all objects. Normally, you do not call this method. It is called by GINA to determine objects to redraw. It is never overridden by GINA.

7.16 (setf view-objects) :after Method

Purpose: clear cached reverse list of view-objects.

(defmethod (setf view-objects) :after (new-list (view view)))

Deamon installed by GINA.

7.17 resized Method

Purpose: the user has resized the view.

(defmethod resized ((view view) ignore))

You override this method to react when the view is resized by the user. The default version stores the new size and redraws the view. Normally, you do not call this method. It is called by GINA when appropriate. It is never overridden by GINA.

7.18 Graphic Primitives for Drawing into a View

7.18.1 draw-point Method

Purpose: call CLX Function to draw into the view.

(defmethod draw-point ((view view) x y))

You rarely override this method or add deamons. The default version is sufficient for most cases. You can call this method (typically within the draw method of a view). It is never called by GINA. It is never overridden by GINA. This method directly corresponds to the CLX function with the same name.

Example

(with-application-stopped
  (draw-point (main-view (first (document-list *application*))) 10 10))

Related methods:

[ c] draw-point ((view-object view-object) x y)  (Page 67)

call same method of the view, but take position into account

7.18.2 draw-points Method

Purpose: call CLX Function to draw into the view.

(defmethod draw-points ((view view) points &optional relative-p))

points: a flat list of alternating x and y values

You rarely override this method or add deamons. The default version is sufficient for most cases. You can call this method (typically within the draw method of a view). It is never called by GINA. It is never overridden by GINA. This method directly corresponds to the CLX function with the same name.

Example

(with-application-stopped
  (draw-points (main-view (first (document-list *application*)))
               '(10 10 20 20 30 30)))

draws 3 points

Related methods:

[ c] draw-points ((view-object view-object) points &optional relative-p) (Page 68)

call same method of the view, but take position into account

7.18.3 draw-line Method

Purpose: call CLX Function to draw into the view.

(defmethod draw-line ((view view) x1 y1 x2 y2 &optional (relative-p nil)))

You rarely override this method or add deamons. The default version is sufficient for most cases. You can call this method (typically within the draw method of a view). It is never called by GINA. It is never overridden by GINA. This method directly corresponds to the CLX function with the same name.

Example

(with-application-stopped
  (draw-line (main-view (first (document-list *application*))) 10 10 50 50))

[ c] draw-line ((view-object view-object) x1 y1 x2 y2 &optional (relative-p nil))  (Page 68)

call same method of the view, but take position into account

7.18.4 draw-lines Method

Purpose: call CLX Function to draw into the view.

(defmethod draw-lines ((view view) points &key relative-p fill-p (shape
:complex)))

points: a flat list of alternating x and y values

You rarely override this method or add deamons. The default version is sufficient for most cases. You can call this method (typically within the draw method of a view). It is never called by GINA. It is never overridden by GINA. This method directly corresponds to the CLX function with the same name.

Example

(with-application-stopped
  (draw-lines (main-view (first (document-list *application*)))
              '(10 10 50 50 40 30 70 60)
              :fill-p
              t))

Related methods:

[ c] draw-lines ((view-object view-object) points &key relative-p fill-p (shape :complex)) (Page 69)

call same method of the view, but take position into account

7.18.5 draw-segments Method

Purpose: call CLX Function to draw into the view.

(defmethod draw-segments ((view view) segments))

You rarely override this method or add deamons. The default version is sufficient for most cases. You can call this method (typically within the draw method of a view). It is never called by GINA. It is never overridden by GINA. This method directly corresponds to the CLX function with the same name.

Example

(with-application-stopped
  (draw-segments
    (main-view (first (document-list *application*)))
    '(10 10 50 50 40 30 70 60)))

Related methods:

[ c] draw-segments ((view-object view-object) segments)  (Page 69)

call same method of the view, but take position into account

7.18.6 draw-rectangle Method

Purpose: call CLX Function to draw into the view.

(defmethod draw-rectangle ((view view) x y width height &optional (fill-p nil)))

You rarely override this method or add deamons. The default version is sufficient for most cases. You can call this method (typically within the draw method of a view). It is never called by GINA. It is never overridden by GINA. This method directly corresponds to the CLX function with the same name.

Example

(with-application-stopped
  (draw-rectangle
    (main-view (first (document-list *application*)))
    10
    10
    50
    50
    t))

Related methods:

[ c] draw-rectangle ((view-object view-object) x y width height &optional (fill-p nil))  (Page 71)

call same method of the view, but take position into account

7.18.7 draw-rectangles Method

Purpose: call CLX Function to draw into the view.

(defmethod draw-rectangles ((view view) rectangles &optional (fill-p nil)))

You rarely override this method or add deamons. The default version is sufficient for most cases. You can call this method (typically within the draw method of a view). It is never called by GINA. It is never overridden by GINA. This method directly corresponds to the CLX function with the same name.

Example

(with-application-stopped
  (draw-rectangles
    (main-view (first (document-list *application*)))
    '(10 10 50 50 40 30 70 60)))

draws two rectangles

Related methods:

[ c] draw-rectangles ((view-object view-object) rectangles &optional (fill-p nil))  (Page 71)

call same method of the view, but take position into account

7.18.8 draw-arc Method

Purpose: call CLX Function to draw into the view.

(defmethod draw-arc ((view view) x y width height angle1 angle2 &optional (fill-p
nil)))

You rarely override this method or add deamons. The default version is sufficient for most cases. You can call this method (typically within the draw method of a view). It is never called by GINA. It is never overridden by GINA. This method directly corresponds to the CLX function with the same name.

Example

(with-application-stopped
  (draw-arc (main-view (first (document-list *application*)))
            10
            10
            50
            50
            0
            (* 2 pi)
            t))

draws a filled circle

[ c] draw-arc ((view-object view-object) x y width height angle1 angle2 &optional (fill-p nil)) (Page 72)

call same method of the view, but take position into account

7.18.9 draw-arcs Method

Purpose: call CLX Function to draw into the view.

(defmethod draw-arcs ((view view) arcs &optional (fill-p nil)))

You rarely override this method or add deamons. The default version is sufficient for most cases. You can call this method (typically within the draw method of a view). It is never called by GINA. It is never overridden by GINA. This method directly corresponds to the CLX function with the same name.

Example

(with-application-stopped
  (draw-arcs (main-view (first (document-list *application*)))
             `(10 10 50 50 0 ,(* 2 pi) 70 70 50 50 0 ,pi)
             t))

draws one and a half filled circles

Related methods:

[ c] draw-arcs ((view-object view-object) arcs &optional (fill-p nil)) (Page 72)

call same method of the view, but take position into account

7.18.10 draw-glyph Method

Purpose: call CLX Function to draw into the view.

(defmethod draw-glyph ((view view) x y elt &key translate width (size :default)))

You rarely override this method or add deamons. The default version is sufficient for most cases. You can call this method (typically within the draw method of a view). It is never called by GINA. It is never overridden by GINA. This method directly corresponds to the CLX function with the same name.

Example

(with-application-stopped
  (draw-glyph (main-view (first (document-list *application*))) 10 20 #\a))

writes out one character

Related methods:

[ c] draw-glyph ((view-object view-object) x y elt &key translate width (size :default)) (Page 73)

call same method of the view, but take position into account

7.18.11 draw-glyphs Method

Purpose: call CLX Function to draw into the view.

(defmethod draw-glyphs ((view view) x y sequence &key (start 0) end translate
width (size :default)))

You rarely override this method or add deamons. The default version is sufficient for most cases. You can call this method (typically within the draw method of a view). It is never called by GINA. It is never overridden by GINA. This method directly corresponds to the CLX function with the same name.

Example

(with-application-stopped
  (draw-glyphs (main-view (first (document-list *application*)))
               10
               20
               "Hello World"))

writes out a string

Related methods:

[ c] draw-glyphs ((view-object view-object) x y sequence &key (start 0) end translate width (size :default)) (Page 74)

call same method of the view, but take position into account

The Class VIEW-OBJECT and its Subclasses

8.1 view-object Class

The class view-object is the superclass of all objects shown in views. You must define a subclass of this class. GINA defines subclasses of this class: objects which can be moved and resized with the mouse. You create an instance of this class for testing only.

Shared Slots:

facilities one-of nil, :selectable, :movable, :move-and-selectable, :resizable

Default: nil

outlines flag whether complete object is moved or just an outline

Default: t

handle-size size of little rectangles indicating selected state Default: 5

Local Slots:

width extension of enclosing rectangle in pixels height extension of enclosing rectangle in pixels mouse-sensitive whether button-press is to be propagated to this object parent-view the view containing the object

Default: nil

x-pos the x-coordinate relative to the containing view

Default: nil

y-pos the y-coordinate relative to the containing view

Default: nil

selected flag whether object is currently selected Default: nil

Methods of class view-object:

[o ] button-press ((obj view-object) code repetition x y)  (Page 63)

react to button-press event in the object

[ c] clear-area ((view-object view-object) x y width height)  (Page 70)

call same method of the view, but take position into account

[o ] constrain-position ((obj view-object) x y)  (Page 65)

modify x and y position of object during move

[o ] constrain-size ((obj view-object) width height)  (Page 65)

modify width and height of object during resize

[o ] create-handle-command ((obj view-object) code x y which-handle)  (Page 66)

creates a command to react to dragging a handle

[ c] deinstall ((view-object view-object) &key (redraw t))  (Page 58)

remove view-object from the list of view-objects of its parent-view

[o ] double-clicked ((obj view-object) code repetition x y)  (Page 63)

a button was double clicked in the view-object

[o ] draw ((view-object view-object) count x y width height)  (Page 62)

draw view-object contents from the internal representation

[ c] draw-arc ((view-object view-object) x y width height angle1 angle2 &optional (fill-p nil)) (Page 72)

call same method of the view, but take position into account

[ c] draw-arcs ((view-object view-object) arcs &optional (fill-p nil)) (Page 72)

call same method of the view, but take position into account

[ c] draw-glyph ((view-object view-object) x y elt &key translate width (size :default)) (Page 73)

call same method of the view, but take position into account

[ c] draw-glyphs ((view-object view-object) x y sequence &key (start 0) end translate width (size :default)) (Page 74)

call same method of the view, but take position into account

[ c] draw-line ((view-object view-object) x1 y1 x2 y2 &optional (relative-p nil))  (Page 68)

call same method of the view, but take position into account

[ c] draw-lines ((view-object view-object) points &key relative-p fill-p (shape :complex)) (Page 69)

call same method of the view, but take position into account

[o ] draw-outline ((obj view-object) new-x new-y width height &key clear)  (Page 65)

draw outline of the object while being moved or resized

[ c] draw-point ((view-object view-object) x y)  (Page 67)

call same method of the view, but take position into account

[ c] draw-points ((view-object view-object) points &optional relative-p) (Page 68)

call same method of the view, but take position into account

[ c] draw-rectangle ((view-object view-object) x y width height &optional (fill-p nil))  (Page 71)

call same method of the view, but take position into account

[ c] draw-rectangles ((view-object view-object) rectangles &optional (fill-p nil))  (Page 71)

call same method of the view, but take position into account

[ c] draw-segments ((view-object view-object) segments)  (Page 69)

call same method of the view, but take position into account

[o ] draw-selected ((obj view-object) count x y width height)  (Page 64)

draw something to indicate that the object is currently selected

[ c] force-redraw ((view-object view-object))  (Page 62)

redraw the whole view-object

[oc] handle-selection ((obj view-object) code)  (Page 67)

perform selection action depending on button code

[oc] inside-rectangle ((view-object view-object) rect-x rect-y rect-width rect-height)  (Page 59)

check if object intersects with the rectangle

[ c] install ((view-object view-object) (view view) &optional (x 0) (y 0) &key (redraw t)) (Page 58)

install a view-object in a view

[ c] invalidate-rectangle ((view-object view-object) x y width height) (Page 61)

redraw part of the view-object

[ c] move ((view-object view-object) new-x new-y &key (redraw t) &allow-other-keys)  (Page 60)

change x and y coordinates

[oc] point-inside ((view-object view-object) x y)  (Page 59)

check if given point in view coordinates is inside the object

[ c] reconfigure ((view-object view-object) new-x new-y new-width new-height &key (redraw t) &allow-other-keys)  (Page 61)

change position and size

[o ] reconfigured-by-user ((obj view-object) was-moved was-resized)  (Page 66)

to react to move and resize commands for an object

[ c] resize ((view-object view-object) new-width new-height &key (redraw t) &allow-other-keys) (Page 60)

change width and height

[ c] (setf selected) (new-value (obj view-object))  (Page 64)

set slot selected and force redraw

[o ] which-resize-handle ((obj view-object) x y)  (Page 66)

determine which resize handle is at point (x,y) if any

8.1.1 make-view-object Function

Purpose: create a graphical object within a view.

(defun make-view-object (width height &key (mouse-sensitive t)
                         (class 'view-object) (initargs nil)))

width: extension of enclosing rectangle in pixels height: extension of enclosing rectangle in pixels mouse-sensitive: flag whether button-press is to be propagted to this object class: ’view-object or any subclass initargs: further initializations for view-object subclass

This is the constructor function for class view-object. The returned value is a newly created object of class view-object. You can call this function. It is never called by GINA. View-objects can exist without being installed in any view.

8.1.2 install Method

Purpose: install a view-object in a view.

(defmethod install ((view-object view-object) (view view) &optional (x 0) (y 0)
&key (redraw t)))

view-object: the object to install view: the view where it is installed x: position in the view where object is installed y: position in the view where object is installed redraw: flag whether effect is immediately shown on the screen

You rarely override this method or add deamons. The default version is sufficient for most cases. You can call this method. It is never called by GINA. It is never overridden by GINA.

Example

(with-application-stopped
  (install (make-view-object 100 100)
           (main-view (first (document-list *application*)))
           10
           20))

installs a view object into the view

8.1.3 deinstall Method

Purpose: remove view-object from the list of view-objects of its parent-view.

(defmethod deinstall ((view-object view-object) &key (redraw t)))

view-object: the object to deinstall redraw: flag whether effect is immediately shown on the screen

You rarely override this method or add deamons. The default version is sufficient for most cases. You can call this method. It is never called by GINA. It is never overridden by GINA.

Example

(with-application-stopped
  (deinstall (first (view-objects (main-view (first
                                               (document-list
                                                *application*)))))))

8.1.4 point-inside-rectangle Macro

Purpose: check if a given point lies within a certain rectangle

(defmacro point-inside-rectangle (x y rect-x rect-y rect-width rect-height))

You can call this macro. It is called by GINA when appropriate.

8.1.5 point-inside Method

Purpose: check if given point in view coordinates is inside the object.

(defmethod point-inside ((view-object view-object) x y))

You override this method for non-rectangular objects. The default version is sufficient for most cases. You can call this method. It is called by GINA when appropriate. It is never overridden by GINA.

Related methods:

[ c] point-inside ((widget widget) x y)  (Page 124)

test whether point lies inside a widget

[  ] point-inside ((icon movable-icon) x y)  (Page 84)

check if given point in view coordinates is inside the icon

8.1.6 inside-rectangle Method

Purpose: check if object intersects with the rectangle.

(defmethod inside-rectangle ((view-object view-object) rect-x rect-y rect-width
rect-height))

You override this method for non-rectangular objects. The default version is sufficient for most cases. You can call this method. It is called by GINA when appropriate. It is never overridden by GINA.

8.1.7 rectangles-overlap Function

Purpose: check if two given rectangles overlap.

(defun rectangles-overlap (x1 y1 width1 height1 x2 y2 width2 height2))

You can call this function. It is sometimes called by GINA.

8.1.8 move Method

Purpose: change x and y coordinates.

(defmethod move ((view-object view-object) new-x new-y &key (redraw t)
&allow-other-keys))

new-x: desired position within the view new-y: desired position within the view redraw: flag whether effect is immediately shown on the screen

You rarely override this method or add deamons. The default version is sufficient for most cases. You can call this method. It is called by GINA when appropriate. It is never overridden by GINA.

Related methods:

[ c] move ((widget widget) new-x new-y &key &allow-other-keys)  (Page 122)

change x and y coordinates

8.1.9 resize Method

Purpose: change width and height.

(defmethod resize ((view-object view-object) new-width new-height &key (redraw t)
&allow-other-keys))

new-width: desired size

new-height:  desired size

redraw: flag whether effect is immediately shown on the screen

You rarely override this method or add deamons. The default version is sufficient for most cases. You can call this method. It is called by GINA when appropriate. It is never overridden by GINA.

[ c] resize ((widget widget) new-width new-height &key &allow-other-keys)  (Page 123)

change width and height

8.1.10 reconfigure Method

Purpose: change position and size.

(defmethod reconfigure ((view-object view-object) new-x new-y new-width
new-height &key (redraw t) &allow-other-keys))

new-x: desired position within the view new-y: desired position within the view new-width: desired size

new-height:  desired size

redraw: flag whether effect is immediately shown

You rarely override this method or add deamons. The default version is sufficient for most cases. You can call this method. It is called by GINA when appropriate. It is never overridden by GINA.

8.1.11 invalidate-rectangle Method

Purpose: redraw part of the view-object.

(defmethod invalidate-rectangle ((view-object view-object) x y width height))

You rarely override this method or add deamons. The default version is sufficient for most cases. You can call this method. It is called by GINA when appropriate. It is never overridden by GINA.

Related methods:

[ c] invalidate-rectangle ((view view) x y width height)  (Page 45)

clear and redraw part of the view

8.1.12 force-redraw Method

Purpose: redraw the whole view-object.

(defmethod force-redraw ((view-object view-object)))

You rarely override this method or add deamons. The default version is sufficient for most cases. You can call this method. It is called by GINA when appropriate. It is never overridden by GINA.

Related methods:

[ c] force-redraw ((view view))  (Page 45)

clear and redraw the whole view

8.1.13 draw Method

Purpose: draw view-object contents from the internal representation.

(defmethod draw ((view-object view-object) count x y width height))

count: number of calls to draw method that will immediately follow x: upper left corner of rectangle which has to be drawn y: upper left corner of rectangle which has to be drawn width: size of rectangle which has to be drawn height: size of rectangle which has to be drawn

You override this method to define the graphical representation of your view-object. The default version draws a rectangle. Normally, you do not call this method. It is called by GINA in response to expose events. It is never overridden by GINA. You can simply draw the whole view-object when count is 0. Optimized versions just draw the necessary parts.

Related methods:

[o ] draw ((view view) count x y width height)  (Page 46)

draw view contents from the internal representation

[  ] draw :around ((view view) count x y width height)  (Page 47)

draw all view-objects in the view after drawing directly in the view

[  ] draw ((icon movable-icon) count x y width height)  (Page 82)

Draw icon optionally with shadow from stored pixmap

8.1.14 button-press Method

Purpose: react to button-press event in the object.

(defmethod button-press ((obj view-object) code repetition x y))

code: which mouse button repetition: 1,2,3,.. for single, double, triple click x: relative mouse position in the view-object y: relative mouse position in the view-object

You override this method to define the desired reaction to mouse clicks. The default version moves, selects or resizes the object. Normally, you do not call this method. It is called by GINA if a button is pressed inside the object. It is never overridden by GINA. Code :select denotes the left mouse button. Code :extend denotes the middle mouse button (or Shift-left). Code :menu denotes the right mouse button (or Shift-Control-left). Code :toggle denotes ctrl-left Code :other denotes any other combination

Related methods:

[  ] button-press :around ((view view) code repetition x y)  (Page 43)

propagate button-press to hit view-object if any

[o ] button-press ((view view) code repetition x y)  (Page 44)

a button was pressed inside the view

8.1.15 double-clicked Method

Purpose: a button was double clicked in the view-object.

(defmethod double-clicked ((obj view-object) code repetition x y))

code: which mouse button repetition: 2,3,.. for double, triple click x: relative mouse position in the view-object y: relative mouse position in the view-object

You override this method to define the desired reaction to double clicks. The default version does not do anything. Normally, you do not call this method. It is called by GINA in response to multiple button-press events. It is never overridden by GINA. Code :select denotes the left mouse button. Code :extend denotes the middle mouse button (or Shift-left).

Code :menu denotes the right mouse button (or Shift-Control-left). Code :toggle denotes ctrl-left Code :other denotes any other combination

8.1.16 (setf selected) Method

Purpose: set slot selected and force redraw.

(defmethod (setf selected) (new-value (obj view-object)))

You rarely override this method or add deamons. The default version is sufficient for most cases. You can call this method to select an object from the program. It is called by GINA when appropriate. It is never overridden by GINA.

8.1.17 draw-selected Method

Purpose: draw something to indicate that the object is currently selected.

(defmethod draw-selected ((obj view-object) count x y width height))

count: number of calls to draw method that will immediately follow x: upper left corner of rectangle which has to be drawn y: upper left corner of rectangle which has to be drawn width: size of rectangle which has to be drawn height: size of rectangle which has to be drawn

You override this method indicate selected state in a different way. The default version draws 4 selection handles. Normally, you do not call this method. It is called by GINA in response to expose events if object is selected. It is overridden by GINA in class movable-icon. You can simply draw the whole object as selected when count is 0. Optimized versions just draw the necessary parts.

Related methods:

[  ] draw-selected ((icon movable-icon) count x y width height)  (Page 83)

do nothing because already done in draw method

8.1.18 draw-outline Method

Purpose: draw outline of the object while being moved or resized.

(defmethod draw-outline ((obj view-object) new-x new-y width height &key clear))

new-x: current position new-y: current position width: current size height: current size clear: flag whether outline should be drawn or cleared

You override this method if a different form of feedback is desired. The default version draws a dashed rectangle. Normally, you do not call this method. It is called by GINA during move and resize commands. It is never overridden by GINA. :function boole-xor is set in gcontext before this method is called.

Related methods:

[  ] draw-outline ((icon movable-icon) new-x new-y width height &key clear)  (Page 83)

draw icon using xor while being moved

8.1.19 constrain-position Method

Purpose: modify x and y position of object during move.

(defmethod constrain-position ((obj view-object) x y))

x: desired object position y: desired object position

The returned value is x and y as multiple values. You override this method to constrain movement to certain locations in the view. The default version returns x and y unmodified. Normally, you do not call this method. It is called by GINA while object is moved. It is never overridden by GINA.

8.1.20 constrain-size Method

Purpose: modify width and height of object during resize.

(defmethod constrain-size ((obj view-object) width height))

width: desired object width height: desired object height

The returned value is width and height as multiple values. You override this method to constrain possible sizes. The default version returns width and height unmodified. Normally, you do not call this method. It is called by GINA while object is resized. It is never overridden by GINA.

8.1.21 which-resize-handle Method

Purpose: determine which resize handle is at point (x,y) if any.

(defmethod which-resize-handle ((obj view-object) x y))

The returned value is 1 to 4 if handle hit (counterclock), else 0. You override this method if the handles do not sit at the corners of the enclosing rectangle. The default version assumes that the handles sit at the corners of the enclosing rectangle. Normally, you do not call this method. It is called by GINA when the mouse is clicked into an object. It is never overridden by GINA.

8.1.22 reconfigured-by-user Method

Purpose: to react to move and resize commands for an object.

(defmethod reconfigured-by-user ((obj view-object) was-moved was-resized))

was-moved: if obj has been moved was-resized: if object has been resized

You override this method if additional reaction is required. The default version does not do anything. Normally, you do not call this method. It is called by GINA during command execution. It is never overridden by GINA.

8.1.23 create-handle-command Method

Purpose: creates a command to react to dragging a handle.

(defmethod create-handle-command ((obj view-object) code x y which-handle))

which-handle:  the handle hit

You override this method if other than rectangle-resize operation is desired. The default version calls make-object-resizer. Normally, you do not call this method. It is called by GINA on button press in a handle. It is never overridden by GINA.

8.1.24 handle-selection Method

Purpose: perform selection action depending on button code.

(defmethod handle-selection ((obj view-object) code))

code: which mouse button

You override this method for non-standard selection model. The default version is sufficient for most cases. You can call this method in app-specific button-press method. It is called by GINA in button-press method if selectable. It is never overridden by GINA.

8.2 Graphic Primitives for Drawing into View-Objects

8.2.1 draw-point Method

Purpose: call same method of the view, but take position into account.

(defmethod draw-point ((view-object view-object) x y))

You rarely override this method or add deamons. The default version is sufficient for most cases. You can call this method (typically within the draw method of a view-object). It is never called by GINA. It is never overridden by GINA. This method directly corresponds to the CLX function with the same name.

Example

(with-application-stopped
  (draw-point (first (view-objects (main-view (first
                                                (document-list
                                                 *application*)))))
              10
              10))

[ c] draw-point ((view view) x y)  (Page 48)

call CLX Function to draw into the view

8.2.2 draw-points Method

Purpose: call same method of the view, but take position into account.

(defmethod draw-points ((view-object view-object) points &optional relative-p))

You rarely override this method or add deamons. The default version is sufficient for most cases. You can call this method (typically within the draw method of a view-object). It is never called by GINA. It is never overridden by GINA. This method directly corresponds to the CLX function with the same name.

Example

(with-application-stopped
  (draw-points (first (view-objects (main-view (first
                                                 (document-list
                                                  *application*)))))
               '(10 10 20 20 30 30)))

draws 3 points

Related methods:

[ c] draw-points ((view view) points &optional relative-p)  (Page 49)

call CLX Function to draw into the view

8.2.3 draw-line Method

Purpose: call same method of the view, but take position into account.

(defmethod draw-line ((view-object view-object) x1 y1 x2 y2 &optional (relative-p
nil)))

You rarely override this method or add deamons. The default version is sufficient for most cases. You can call this method (typically within the draw method of a view-object). It is never called by GINA. It is never overridden by GINA. This method directly corresponds to the CLX function with the same name.

Example

(with-application-stopped
  (draw-line (first (view-objects (main-view (first
                                               (document-list *application*)))))
             10
             10
             50
             50))

Related methods:

[ c] draw-line ((view view) x1 y1 x2 y2 &optional (relative-p nil))  (Page 49)

call CLX Function to draw into the view

8.2.4 draw-lines Method

Purpose: call same method of the view, but take position into account.

(defmethod draw-lines ((view-object view-object) points &key relative-p fill-p
(shape :complex)))

You rarely override this method or add deamons. The default version is sufficient for most cases. You can call this method (typically within the draw method of a view-object). It is never called by GINA. It is never overridden by GINA. This method directly corresponds to the CLX function with the same name.

Example

(with-application-stopped
  (draw-lines (first (view-objects (main-view (first
                                                (document-list
                                                 *application*)))))
              '(10 10 50 50 40 30 70 60)
              :fill-p
              t))

Related methods:

[ c] draw-lines ((view view) points &key relative-p fill-p (shape :complex))  (Page 50)

call CLX Function to draw into the view

8.2.5 draw-segments Method

Purpose: call same method of the view, but take position into account.

(defmethod draw-segments ((view-object view-object) segments))

You rarely override this method or add deamons. The default version is sufficient for most cases. You can call this method (typically within the draw method of a view-object). It is never called by GINA. It is never overridden by GINA. This method directly corresponds to the CLX function with the same name.

Example

(with-application-stopped
  (draw-segments
    (first (view-objects (main-view (first (document-list *application*)))))
    '(10 10 50 50 40 30 70 60)))

Related methods:

[ c] draw-segments ((view view) segments)  (Page 50)

call CLX Function to draw into the view

8.2.6 clear-area Method

Purpose: call same method of the view, but take position into account.

(defmethod clear-area ((view-object view-object) x y width height))

You rarely override this method or add deamons. The default version is sufficient for most cases. You can call this method (typically within the draw method of a view-object). It is never called by GINA. It is never overridden by GINA. This method directly corresponds to the CLX function with the same name.

Example

(with-application-stopped
  (clear-area (first (view-objects (main-view (first
                                                (document-list
                                                 *application*)))))
              10
              10
              50
              50))

Related methods:

[ c] clear-area ((view view) x y width height)  (Page 46)

turn area into background color

8.2.7 draw-rectangle Method

Purpose: call same method of the view, but take position into account.

(defmethod draw-rectangle ((view-object view-object) x y width height &optional
(fill-p nil)))

You rarely override this method or add deamons. The default version is sufficient for most cases. You can call this method (typically within the draw method of a view-object). It is never called by GINA. It is never overridden by GINA. This method directly corresponds to the CLX function with the same name.

Example

(with-application-stopped
  (draw-rectangle
    (first (view-objects (main-view (first (document-list *application*)))))
    10
    10
    50
    50
    t))

Related methods:

[ c] draw-rectangle ((view view) x y width height &optional (fill-p nil))  (Page 51)

call CLX Function to draw into the view

8.2.8 draw-rectangles Method

Purpose: call same method of the view, but take position into account.

(defmethod draw-rectangles ((view-object view-object) rectangles &optional
(fill-p nil)))

You rarely override this method or add deamons. The default version is sufficient for most cases. You can call this method (typically within the draw method of a view-object). It is never called by GINA. It is never overridden by GINA. This method directly corresponds to the CLX function with the same name.

Example

(with-application-stopped
  (draw-rectangles
    (first (view-objects (main-view (first (document-list *application*)))))
    '(10 10 50 50 40 30 70 60)))

draws two rectangles

[ c] draw-rectangles ((view view) rectangles &optional (fill-p nil))  (Page 51)

call CLX Function to draw into the view

8.2.9 draw-arc Method

Purpose: call same method of the view, but take position into account.

(defmethod draw-arc ((view-object view-object) x y width height angle1 angle2
&optional (fill-p nil)))

You rarely override this method or add deamons. The default version is sufficient for most cases. You can call this method (typically within the draw method of a view-object). It is never called by GINA. It is never overridden by GINA. This method directly corresponds to the CLX function with the same name.

Example

(with-application-stopped
  (draw-arc (first (view-objects (main-view (first
                                              (document-list *application*)))))
            10
            10
            50
            50
            0
            (* 2 pi)
            t))

draws a filled circle

Related methods:

[ c] draw-arc ((view view) x y width height angle1 angle2 &optional (fill-p nil))  (Page 52)

call CLX Function to draw into the view

8.2.10 draw-arcs Method

Purpose: call same method of the view, but take position into account.

(defmethod draw-arcs ((view-object view-object) arcs &optional (fill-p nil)))

You rarely override this method or add deamons. The default version is sufficient for most cases. You can call this method (typically within the draw method of a view-object). It is never called by GINA. It is never overridden by GINA. This method directly corresponds to the CLX function with the same name.

Example

(with-application-stopped
  (draw-arcs (first (view-objects (main-view (first
                                               (document-list *application*)))))
             `(10 10 50 50 0 ,(* 2 pi) 70 70 50 50 0 ,pi)
             t))

draws one and a half filled circles

Related methods:

[ c] draw-arcs ((view view) arcs &optional (fill-p nil))  (Page 53)

call CLX Function to draw into the view

8.2.11 draw-glyph Method

Purpose: call same method of the view, but take position into account.

(defmethod draw-glyph ((view-object view-object) x y elt &key translate width
(size :default)))

You rarely override this method or add deamons. The default version is sufficient for most cases. You can call this method (typically within the draw method of a view-object). It is never called by GINA. It is never overridden by GINA. This method directly corresponds to the CLX function with the same name.

Example

(with-application-stopped
  (draw-glyph (first (view-objects (main-view (first
                                                (document-list
                                                 *application*)))))
              10
              20
              #\a))

writes out one character

[ c] draw-glyph ((view view) x y elt &key translate width (size :default))  (Page 53)

call CLX Function to draw into the view

8.2.12 draw-glyphs Method

Purpose: call same method of the view, but take position into account.

(defmethod draw-glyphs ((view-object view-object) x y sequence &key (start 0) end
translate width (size :default)))

You rarely override this method or add deamons. The default version is sufficient for most cases. You can call this method (typically within the draw method of a view-object). It is never called by GINA. It is never overridden by GINA. This method directly corresponds to the CLX function with the same name.

Example

(with-application-stopped
  (draw-glyphs (first (view-objects (main-view (first
                                                 (document-list
                                                  *application*)))))
               10
               20
               "Hello World"))

writes out a string

Related methods:

[ c] draw-glyphs ((view view) x y sequence &key (start 0) end translate width (size :default)) (Page 54)

call CLX Function to draw into the view

8.3 direct-manipulation-object Class

An instance of class direct-manipulation-object is a view-object with direct-manipulation capabilities. It is a subclass of view-object. You must define a subclass of this class. GINA defines subclasses of this class: movable icons and in the demo applications. You create an instance of this class for testing only.

Shared Slots:

direct-manipulation-object: facilities one-of nil, :selectable, :movable, :move-and-selectable, :resizable

                       Default: :resizable

view-object: facilities one-of nil, :selectable, :movable, :move-and-selectable, :resizable

Default: nil

outlines flag whether complete object is moved or just an outline

Default: t

handle-size size of little rectangles indicating selected state Default: 5

Local Slots:

view-object: width extension of enclosing rectangle in pixels height extension of enclosing rectangle in pixels mouse-sensitive whether button-press is to be propagated to this object parent-view the view containing the object

Default: nil

x-pos the x-coordinate relative to the containing view

Default: nil

y-pos the y-coordinate relative to the containing view

Default: nil

selected flag whether object is currently selected Default: nil

Methods of superclasses:

[o ] button-press ((obj view-object) code repetition x y)  (Page 63)

react to button-press event in the object

[ c] clear-area ((view-object view-object) x y width height)  (Page 70)

call same method of the view, but take position into account

[o ] constrain-position ((obj view-object) x y)  (Page 65)

modify x and y position of object during move

[o ] constrain-size ((obj view-object) width height)  (Page 65)

modify width and height of object during resize

[o ] create-handle-command ((obj view-object) code x y which-handle)  (Page 66)

creates a command to react to dragging a handle

[ c] deinstall ((view-object view-object) &key (redraw t))  (Page 58)

remove view-object from the list of view-objects of its parent-view

[o ] double-clicked ((obj view-object) code repetition x y)  (Page 63)

a button was double clicked in the view-object

[o ] draw ((view-object view-object) count x y width height)  (Page 62)

draw view-object contents from the internal representation

[ c] draw-arc ((view-object view-object) x y width height angle1 angle2 &optional (fill-p nil)) (Page 72)

call same method of the view, but take position into account

[ c] draw-arcs ((view-object view-object) arcs &optional (fill-p nil)) (Page 72)

call same method of the view, but take position into account

[ c] draw-glyph ((view-object view-object) x y elt &key translate width (size :default)) (Page 73)

call same method of the view, but take position into account

[ c] draw-glyphs ((view-object view-object) x y sequence &key (start 0) end translate width (size :default)) (Page 74)

call same method of the view, but take position into account

[ c] draw-line ((view-object view-object) x1 y1 x2 y2 &optional (relative-p nil))  (Page 68)

call same method of the view, but take position into account

[ c] draw-lines ((view-object view-object) points &key relative-p fill-p (shape :complex)) (Page 69)

call same method of the view, but take position into account

[o ] draw-outline ((obj view-object) new-x new-y width height &key clear)  (Page 65)

draw outline of the object while being moved or resized

[ c] draw-point ((view-object view-object) x y)  (Page 67)

call same method of the view, but take position into account

[ c] draw-points ((view-object view-object) points &optional relative-p) (Page 68)

call same method of the view, but take position into account

[ c] draw-rectangle ((view-object view-object) x y width height &optional (fill-p nil))  (Page 71)

call same method of the view, but take position into account

[ c] draw-rectangles ((view-object view-object) rectangles &optional (fill-p nil))  (Page 71)

call same method of the view, but take position into account

[ c] draw-segments ((view-object view-object) segments)  (Page 69)

call same method of the view, but take position into account

[o ] draw-selected ((obj view-object) count x y width height)  (Page 64)

draw something to indicate that the object is currently selected

[ c] force-redraw ((view-object view-object))  (Page 62)

redraw the whole view-object

[oc] handle-selection ((obj view-object) code)  (Page 67)

perform selection action depending on button code

[oc] inside-rectangle ((view-object view-object) rect-x rect-y rect-width rect-height)  (Page 59)

check if object intersects with the rectangle

[ c] install ((view-object view-object) (view view) &optional (x 0) (y 0) &key (redraw t)) (Page 58)

install a view-object in a view

[ c] invalidate-rectangle ((view-object view-object) x y width height) (Page 61)

redraw part of the view-object

[ c] move ((view-object view-object) new-x new-y &key (redraw t) &allow-other-keys)  (Page 60)

change x and y coordinates

[oc] point-inside ((view-object view-object) x y)  (Page 59)

check if given point in view coordinates is inside the object

[ c] reconfigure ((view-object view-object) new-x new-y new-width new-height &key (redraw t) &allow-other-keys)  (Page 61)

change position and size

[o ] reconfigured-by-user ((obj view-object) was-moved was-resized)  (Page 66)

to react to move and resize commands for an object

[ c] resize ((view-object view-object) new-width new-height &key (redraw t) &allow-other-keys) (Page 60)

change width and height

[ c] (setf selected) (new-value (obj view-object))  (Page 64)

set slot selected and force redraw

[o ] which-resize-handle ((obj view-object) x y)  (Page 66)

determine which resize handle is at point (x,y) if any

8.3.1 make-direct-manipulation-object Function

Purpose: create a new direct manipulation object.

(defun make-direct-manipulation-object (width
                                        height
                                        &key
                                        (mouse-sensitive t)
                                        (class 'direct-manipulation-object)
                                        (initargs nil)))

width: extension of enclosing rectangle in pixels height: extension of enclosing rectangle in pixels mouse-sensitive: flag whether button-press should be propagated to this object class: ’direct-manipulation-object or any subclass initargs: further initializations for subclass

This is the constructor function for class direct-manipulation-object. The returned value is a newly created object of class direct-manipulation-object. You can call this function. It is never called by GINA. Direct-manipulation objects can exist without beeing installed in a view.

Example

(with-application-stopped
  (install (make-direct-manipulation-object 100 100)
           (main-view (first (document-list *application*)))
           100
           100))

8.4 movable-icon Class

An instance of class movable-icon is a direct manipulation-object displaying a pixmap. It is a subclass of direct-manipulation-object and view-object. You can define a subclass of this class. GINA defines subclasses of this class: only in the chess demo application. You can create an instance of this class.

Shared Slots:

movable-icon: facilities one-of nil, :selectable, :movable, :move-and-selectable, :resizable

                       Default: :move-and-selectable

outlines flag whether complete (solid) icon is moved (default) or just xor the icon

Default: nil

direct-manipulation-object: facilities one-of nil, :selectable, :movable, :move-and-selectable, :resizable

                       Default: :resizable

view-object: facilities one-of nil, :selectable, :movable, :move-and-selectable, :resizable

Default: nil

outlines flag whether complete object is moved or just an outline

Default: t

handle-size size of little rectangles indicating selected state Default: 5

Local Slots:

movable-icon: icon-pixmap Pixmap of icon on X-server side

Default: nil

mask-pixmap Pixmap of mask on X-server side

Default: nil

icon-image Image structure of icon as read from file mask-image Image structure of mask as read from file shadow-offset Offset of shadow (0 = no shadow) left-margin Free space on left of icon top-margin Free space on top of icon view-object: width extension of enclosing rectangle in pixels height extension of enclosing rectangle in pixels mouse-sensitive whether button-press is to be propagated to this object parent-view the view containing the object

Default: nil

x-pos the x-coordinate relative to the containing view

Default: nil

y-pos the y-coordinate relative to the containing view

Default: nil

selected flag whether object is currently selected Default: nil

Methods of class movable-icon:

[  ] draw ((icon movable-icon) count x y width height)  (Page 82)

Draw icon optionally with shadow from stored pixmap

[  ] draw-outline ((icon movable-icon) new-x new-y width height &key clear)  (Page 83)

draw icon using xor while being moved

[  ] draw-selected ((icon movable-icon) count x y width height)  (Page 83)

do nothing because already done in draw method

[  ] point-inside ((icon movable-icon) x y)  (Page 84)

check if given point in view coordinates is inside the icon

Methods of superclasses:

[o ] button-press ((obj view-object) code repetition x y)  (Page 63)

react to button-press event in the object

[ c] clear-area ((view-object view-object) x y width height)  (Page 70)

call same method of the view, but take position into account

[o ] constrain-position ((obj view-object) x y)  (Page 65)

modify x and y position of object during move

[o ] constrain-size ((obj view-object) width height)  (Page 65)

modify width and height of object during resize

[o ] create-handle-command ((obj view-object) code x y which-handle)  (Page 66)

creates a command to react to dragging a handle

[ c] deinstall ((view-object view-object) &key (redraw t))  (Page 58)

remove view-object from the list of view-objects of its parent-view

[o ] double-clicked ((obj view-object) code repetition x y)  (Page 63)

a button was double clicked in the view-object

[o ] draw ((view-object view-object) count x y width height)  (Page 62)

draw view-object contents from the internal representation

[ c] draw-arc ((view-object view-object) x y width height angle1 angle2 &optional (fill-p nil)) (Page 72)

call same method of the view, but take position into account

[ c] draw-arcs ((view-object view-object) arcs &optional (fill-p nil)) (Page 72)

call same method of the view, but take position into account

[ c] draw-glyph ((view-object view-object) x y elt &key translate width (size :default)) (Page 73)

call same method of the view, but take position into account

[ c] draw-glyphs ((view-object view-object) x y sequence &key (start 0) end translate width (size :default)) (Page 74)

call same method of the view, but take position into account

[ c] draw-line ((view-object view-object) x1 y1 x2 y2 &optional (relative-p nil))  (Page 68)

call same method of the view, but take position into account

[ c] draw-lines ((view-object view-object) points &key relative-p fill-p (shape :complex)) (Page 69)

call same method of the view, but take position into account

[o ] draw-outline ((obj view-object) new-x new-y width height &key clear)  (Page 65)

draw outline of the object while being moved or resized

[ c] draw-point ((view-object view-object) x y)  (Page 67)

call same method of the view, but take position into account

[ c] draw-points ((view-object view-object) points &optional relative-p) (Page 68)

call same method of the view, but take position into account

[ c] draw-rectangle ((view-object view-object) x y width height &optional (fill-p nil))  (Page 71)

call same method of the view, but take position into account

[ c] draw-rectangles ((view-object view-object) rectangles &optional (fill-p nil))  (Page 71)

call same method of the view, but take position into account

[ c] draw-segments ((view-object view-object) segments)  (Page 69)

call same method of the view, but take position into account

[o ] draw-selected ((obj view-object) count x y width height)  (Page 64)

draw something to indicate that the object is currently selected

[ c] force-redraw ((view-object view-object))  (Page 62)

redraw the whole view-object

[oc] handle-selection ((obj view-object) code)  (Page 67)

perform selection action depending on button code

[oc] inside-rectangle ((view-object view-object) rect-x rect-y rect-width rect-height)  (Page 59)

check if object intersects with the rectangle

[ c] install ((view-object view-object) (view view) &optional (x 0) (y 0) &key (redraw t)) (Page 58)

install a view-object in a view

[ c] invalidate-rectangle ((view-object view-object) x y width height) (Page 61)

redraw part of the view-object

[ c] move ((view-object view-object) new-x new-y &key (redraw t) &allow-other-keys)  (Page 60)

change x and y coordinates

[oc] point-inside ((view-object view-object) x y)  (Page 59)

check if given point in view coordinates is inside the object

[ c] reconfigure ((view-object view-object) new-x new-y new-width new-height &key (redraw t) &allow-other-keys)  (Page 61)

change position and size

[o ] reconfigured-by-user ((obj view-object) was-moved was-resized)  (Page 66)

to react to move and resize commands for an object

[ c] resize ((view-object view-object) new-width new-height &key (redraw t) &allow-other-keys) (Page 60)

change width and height

[ c] (setf selected) (new-value (obj view-object))  (Page 64)

set slot selected and force redraw

[o ] which-resize-handle ((obj view-object) x y)  (Page 66)

determine which resize handle is at point (x,y) if any

8.4.1 make-movable-icon Function

Purpose: Create a new movable icon.

(defun make-movable-icon (icon-image-or-pathname &key (mask nil)
                          (shadow-offset 0) (top-margin 0)
                          (bottom-margin shadow-offset) (left-margin 0)
                          (right-margin shadow-offset) (class 'movable-icon)
                          (initargs nil)))
icon-image-or-pathname:image or name of bitmap file

mask: image or name of bitmap file shadow-offset: offset of shadow; 0 = no shadow top-margin: space on top of icon bottom-margin: space (e.g. for shadow) on bottom of icon left-margin: space on left of icon right-margin: space (e.g. for shadow) on right of icon class: class movable-icon or any subclass of it initargs: further initializations for subclass

This is the constructor function for class movable-icon. The returned value is a newly created object of class movable-icon.

You can call this function. It is called by GINA only in the chess demo application.

Example

(with-application-stopped
  (setq icon
        (make-movable-icon
          "/usr/include/X11/bitmaps/mailfull"
          :mask
          "/usr/include/X11/bitmaps/mailfullmsk"
          :shadow-offset
          8))
  (install icon (main-view (first (document-list *application*)))))

8.4.2 pathname->image Method

Purpose: look up cached image for pathname or read file and cache it.

(defmethod pathname->image ((appl application) pathname-or-image))

pathname-or-image: if an image is given, it is just returned

You rarely override this method or add deamons. The default version is sufficient for most cases. You can call this method for mapping pathnames to images. It is called by GINA in methods of class movable-icon. It is never overridden by GINA.

8.4.3 image->image-z Method

Purpose: look up cached image in z-format or convert to it and cache it.

(defmethod image->image-z ((appl application) image))

image: image of any format (image-x -xy or -z)

You rarely override this method or add deamons. The default version is sufficient for most cases. You can call this method for mapping images to images of z-format. It is called by GINA in methods of class movable-icon. It is never overridden by GINA.

8.4.4 image->pixmap Method

Purpose: lookup cached pixmap for image or create pixmap and cache it.

(defmethod image->pixmap ((appl application) image drawable))

image: an image (i.e. pixel data on lisp-side) drawable: a drawable which determines the screen where the pixmap will be used

You rarely override this method or add deamons. The default version is sufficient for most cases. You can call this method for mapping images to pixmaps. It is called by GINA in methods of class movable-icon. It is never overridden by GINA.

8.4.5 draw Method

Purpose: Draw icon optionally with shadow from stored pixmap.

(defmethod draw ((icon movable-icon) count x y width height))

count: number of calls to draw method that will immediately follow x: upper left corner of rectangle which has to be drawn y: upper left corner of rectangle which has to be drawn width: size of rectangle which has to be drawn height: size of rectangle which has to be drawn

You rarely override this method or add deamons. The default version draws icon with or without shadow. Normally, you do not call this method. It is called by GINA in response to expose events. It is never overridden by GINA. You can add a deamon to display more information e.g. a text.

Related methods:

[o ] draw ((view view) count x y width height)  (Page 46)

draw view contents from the internal representation

[o ] draw ((view-object view-object) count x y width height)  (Page 62)

draw view-object contents from the internal representation

[  ] draw :around ((view view) count x y width height)  (Page 47)

draw all view-objects in the view after drawing directly in the view

8.4.6 draw-outline Method

Purpose: draw icon using xor while being moved.

(defmethod draw-outline ((icon movable-icon) new-x new-y width height &key
clear))

new-x: current position new-y: current position width: current size height: current size clear: not used for movable-icon

You rarely override this method or add deamons. The default version draws the icon using xor. Normally, you do not call this method. It is called by GINA during move command. It is never overridden by GINA. function boole-xor is set in gcontext before this method is called.

Related methods:

[o ] draw-outline ((obj view-object) new-x new-y width height &key clear)  (Page 65)

draw outline of the object while being moved or resized

8.4.7 draw-selected Method

Purpose: do nothing because already done in draw method.

(defmethod draw-selected ((icon movable-icon) count x y width height))

You rarely override this method or add deamons. The default version is sufficient for most cases. Normally, you do not call this method. It is called by GINA when appropriate. It is never overridden by GINA.

Related methods:

[o ] draw-selected ((obj view-object) count x y width height)  (Page 64)

draw something to indicate that the object is currently selected

8.4.8 point-inside Method

Purpose: check if given point in view coordinates is inside the icon.

(defmethod point-inside ((icon movable-icon) x y))

You rarely override this method or add deamons. The default version is sufficient for most cases. Normally, you do not call this method. It is called by GINA to test whether mouse click hits icon. It is never overridden by GINA. Uses mask; calls point-inside of view-object when no mask given.

Related methods:

[ c] point-inside ((widget widget) x y)  (Page 124)

test whether point lies inside a widget

[oc] point-inside ((view-object view-object) x y)  (Page 59)

check if given point in view coordinates is inside the object

The Class CALLBACK

9 callback Class

An instance of class callback is a data object describing an action to do later. You rarely define subclasses of this class. GINA does not define subclasses of this class. You can create an instance of this class.

Local Slots:

function-name the function to be called static-args a list of arguments which will always be passed to the function

Methods of class callback:

[  ] execute ((cb callback) dynamic-args)  (Page 87)

apply the stored function to the static- and dynamic args

[o ] print-object ((cb callback) stream)  (Page 85)

specialized printed representation

9.1 print-object Method

Purpose: specialized printed representation.

(defmethod print-object ((cb callback) stream))

You override this method to get a special printed representation. The default version prints name of the function. Normally, you do not call this method. It is called by GINA to denote a callback object. It is never overridden by GINA.

[o ] print-object ((app application) stream)  (Page 21)

specialized printed representation

[o ] print-object ((doc document) stream)  (Page 28)

specialized printed representation

9.2 make-callback Function

Purpose: create a new callback object.

(defun make-callback (function-name &rest static-args))

function-name: the function to be called static-args: a list of arguments which will always be passed to the function

This is the constructor function for class callback. The returned value is a newly created object of class callback. You can call this function. It is sometimes called by GINA.

Example

(execute (make-callback #'list 1 2 3 4) '(5 6 7))

9.3 print-parms Function

Purpose: Just print the parameters supplied.

(defun print-parms (&rest parms))

Normally, you do not call this function. It is called by GINA when supplied as a callback function. You can use this function to find out the parameters of a callback.

Example

(with-application-stopped
  (setq box (make-modeless-dialog-box "test"))
  (make-scrollbar box :value-changed-callback #'print-parms)
  (pop-up box))

Creates a dialog-box with a scrollbar. The new value is printed at each callback.

9.4 execute Method

Purpose: apply the stored function to the static- and dynamic args.

(defmethod execute ((cb callback) dynamic-args))

dynamic-args: additional arguments for the function stored in the callback object

You rarely override this method or add deamons. The default version is sufficient for most cases. Normally, you do not call this method. It is called by GINA when appropriate. It is never overridden by GINA.

Related methods:

[  ] execute ((callback t) dynamic-args)  (Page 87)

apply the stored function to the static- and dynamic args

9.5 execute Method

Purpose: apply the stored function to the static- and dynamic args.

(defmethod execute ((callback t) dynamic-args))

dynamic-args: additional arguments for the function stored in the callback object

You rarely override this method or add deamons. The default version is sufficient for most cases. Normally, you do not call this method. It is called by GINA when appropriate. It is never overridden by GINA. Lambda-expressions and compiled functions can be executed just like callback objects. Callbacks can also be lists of callbacks.

Related methods:

[  ] execute ((cb callback) dynamic-args)  (Page 87)

apply the stored function to the static- and dynamic args

The Class COMMAND and its Subclasses

10.1 command Class

An instance of class command is an object representing a single user action. You must define a subclass of this class. GINA defines subclasses of this class: class mouse-down-command and special commands for direct-manipulation. You never create an instance of this class.

Shared Slots:

name identification shown in the history scroller

                       Default: "Command"

clock-cursor flag whether clock cursor is shown during doit

Default: nil

undoable flag whether an UNDO is possible

Default: t

causes-change flag whether the command modifies the document Default: t

Local Slots:

document the document changed by the command view the view which shows the effect of the command view-x-offset scroll position of the view when command was issued view-y-offset scroll position of the view when command was issued

Methods of class command:

[o ] commit ((cmd command) undone)  (Page 92)

free resources used by the command

[o ] doit ((cmd command))  (Page 90)

execute the effect of the command

[o ] executable ((cmd command))  (Page 90)

check if the command is executable

[o ] redoit ((cmd command))  (Page 91)

repeat effect of the command

[  ] scroll-before-redo ((cmd command))  (Page 91)

do the scrolling necessary so that the effect of REDO can be seen

[  ] scroll-before-undo ((cmd command))  (Page 90)

do the scrolling necessary so that the effect of UNDO can be seen

[ c] submit ((cmd command))  (Page 89)

store command in the document and call doit

[o ] undoit ((cmd command))  (Page 91)

undo effect of the command

10.1.1 make-command Function

Purpose: create a command object.

(defun make-command (document &key (view (main-view document))
                     (immediately-submit t) (create-checkpoint nil)
                     (reverse-undo nil) (class 'command) (initargs nil)))

document: the document changed by the command view: the view which shows the effect of the command immediately-submit: flag whether command is immediately submitted when created class: ’command or any subclass of it initargs: further initializations for command subclass

This is the constructor function for class command. The returned value is a newly created object of class command. You can call this function in the constructor of a command subclass. It is sometimes called by GINA.

10.1.2 submit Method

Purpose: store command in the document and call doit.

(defmethod submit ((cmd command)))

You rarely override this method or add deamons. The default version is sufficient for most cases. You can call this method if a command is not immediately submitted when created. It is called by GINA in make-command. It is never overridden by GINA.

10.1.3 executable Method

Purpose: check if the command is executable.

(defmethod executable ((cmd command)))

You override this method to define conditions for the command to be executed. The default version returns t, because normal commands are always executable. Normally, you do not call this method. It is called by GINA before doit is called. It is never overridden by GINA. Especially mouse commands may be executed only if something is hit.

10.1.4 doit Method

Purpose: execute the effect of the command.

(defmethod doit ((cmd command)))

You override this method to define the special semantics of a command. The default version does not do anything. Normally, you do not call this method. It is called by GINA when the command is submitted. It is overridden by GINA in the predefined commands for direct manipulation.

Related methods:

[  ] doit ((cmd object-mover))  (Page 102)

finally move the specified view-object

[  ] doit ((cmd object-resizer))  (Page 108)

finally resize the specified object

[  ] doit ((cmd object-selector))  (Page 112)

select all captured view objects

10.1.5 scroll-before-undo Method

Purpose: do the scrolling necessary so that the effect of UNDO can be seen.

(defmethod scroll-before-undo ((cmd command)))

You rarely override this method or add deamons. The default version scrolls the view to the position it originally had when the command was executed. Normally, you do not call this method. It is called by GINA before method undoit is called. It is never overridden by GINA.

10.1.6 undoit Method

Purpose: undo effect of the command.

(defmethod undoit ((cmd command)))

You override this method to define the inverse of a command. The default version tries to restore a checkpoint, if there is one. Normally, you do not call this method. It is called by GINA in response to the UNDO menu entry. It is overridden by GINA in the predefined commands for direct manipulation.

Related methods:

[  ] undoit ((cmd object-mover))  (Page 103)

move back the view-object

[  ] undoit ((cmd object-resizer))  (Page 108)

give the object the original size again

10.1.7 scroll-before-redo Method

Purpose: do the scrolling necessary so that the effect of REDO can be seen.

(defmethod scroll-before-redo ((cmd command)))

You rarely override this method or add deamons. The default version scrolls the view to the position it originally had when the command was executed. Normally, you do not call this method. It is called by GINA before method redoit is called. It is overridden by GINA for mouse-commands because of possible auto-scrolling.

Related methods:

[  ] scroll-before-redo ((cmd mouse-down-command))  (Page 97)

do the scrolling necessary so that the effect of REDO can be seen

10.1.8 redoit Method

Purpose: repeat effect of the command.

(defmethod redoit ((cmd command)))

You override this method if repeating the command is different from doing it for the first time. The default version calls the method doit. Normally, you do not call this method. It is called by GINA when the command is repeated by a REDO. It is overridden by GINA in the predefined commands for direct manipulation.

[  ] redoit ((cmd object-mover))  (Page 103)

move the view-object forward again

[  ] redoit ((cmd object-resizer))  (Page 108)

resize the object again

10.1.9 commit Method

Purpose: free resources used by the command.

(defmethod commit ((cmd command) undone))

undone: flag whether the last action with this command was an UNDO

You override this method if there are any resources which must be freed. The default version does not do anything. Normally, you do not call this method. It is called by GINA when no more undo/redo is possible. It is never overridden by GINA.

10.2 mouse-down-command Class

An instance of class mouse-down-command is a mouse command with feedback as long as the mouse is down. It is a subclass of command. You must define a subclass of this class. GINA defines subclasses of this class: the special commands for direct-manipulation. You never create an instance of this class.

Shared Slots:

mouse-down-command: hysteresis minimum mouse movement before command is submitted

Default: 0

auto-scrolling flag whether automatic scrolling is desired

Default: t

idle-timeout seconds before mouse-idle is called and auto-scrolling is done when mouse is not moved

Default: 0.25

call-doit flag whether command should really be submitted

Default: t

name overrides slot of class command

                       Default: "Mouse Command"

\underline{command:} name identification shown in the history scroller

                       Default: "Command"

clock-cursor flag whether clock cursor is shown during doit

Default: nil

undoable flag whether an UNDO is possible

Default: t

causes-change flag whether the command modifies the document Default: t

Local Slots:

mouse-down-command: start-x view coordinate where the mouse button went down start-y view coordinate where the mouse button went down timer-id id for xtk:change-timer and friends

Default: nil

mouse-already-moved flag if hysteresis has been reached

Default: nil

last-x view coordinate of last mouse position last-y view coordinate of last mouse position \underline{command:} document the document changed by the command view the view which shows the effect of the command view-x-offset scroll position of the view when command was issued view-y-offset scroll position of the view when command was issued

Methods of class mouse-down-command:

[o ] constrain-mouse ((cmd mouse-down-command) x y)  (Page 94)

modify x and y position of mouse pointer

[  ] draw-feedback :around ((cmd mouse-down-command) x y &key clear)  (Page 95)

set xor-mode and foreground in the view’s gcontext

[o ] draw-feedback ((cmd mouse-down-command) x y &key clear)  (Page 95)

draw mouse feedback during commands

[o ] mouse-idle ((cmd mouse-down-command) x y)  (Page 97)

react to timeout during mouse command

[ c] mouse-rectangle ((cmd mouse-down-command) x y)  (Page 98)

calculate the positive rectangle between start and x,y

[o ] not-submitted ((cmd mouse-down-command))  (Page 97)

react to the fact that command was not submitted

[  ] scroll-before-redo ((cmd mouse-down-command))  (Page 97)

do the scrolling necessary so that the effect of REDO can be seen

[o ] track-mouse ((cmd mouse-down-command) x y &key (started nil) (finished nil))  (Page 96)

process the possibly modified mouse coordinates

Methods of superclasses:

[o ] commit ((cmd command) undone)  (Page 92)

free resources used by the command

[o ] doit ((cmd command))  (Page 90)

execute the effect of the command

[o ] executable ((cmd command))  (Page 90)

check if the command is executable

[o ] redoit ((cmd command))  (Page 91)

repeat effect of the command

[  ] scroll-before-redo ((cmd command))  (Page 91)

do the scrolling necessary so that the effect of REDO can be seen

[  ] scroll-before-undo ((cmd command))  (Page 90)

do the scrolling necessary so that the effect of UNDO can be seen

[ c] submit ((cmd command))  (Page 89)

store command in the document and call doit

[o ] undoit ((cmd command))  (Page 91)

undo effect of the command

10.2.1 make-mouse-down-command Function

Purpose: create a mouse-down-command object.

(defun make-mouse-down-command (document view start-x start-y &key
                                (cursor :hand) (class 'mouse-down-command)
                                (initargs nil)))

document: the document changed by the command view: the view where the mouse feedback is shown start-x: view coordinate where the mouse button went down start-y: view coordinate where the mouse button went down cursor: number or keyword class: ’mouse-down-command or any subclass of it initargs: further initializations for command subclass

This is the constructor function for class mouse-down-command. The returned value is a newly created object of class mouse-down-command. You can call this function. It is sometimes called by GINA. Cursor can be the result of a call to xtk:create-font-cursor or xtk:create-pixmap-cursor or a keyword like :hand, :arrow ... (xtk:all-cursors) lists all available keywords.

10.2.2 constrain-mouse Method

Purpose: modify x and y position of mouse pointer.

(defmethod constrain-mouse ((cmd mouse-down-command) x y))

x: current mouse position y: current mouse position The returned value is x and y as multiple values. You override this method to constrain the mouse to certain locations in the view. The default version returns x and y unmodified. Normally, you do not call this method. It is called by GINA before mouse feedback is drawn. It is never overridden by GINA.

Related methods:

[  ] constrain-mouse ((cmd object-mover) x y)  (Page 101)

use the result of constrain-position of the moved object

[  ] constrain-mouse ((cmd object-resizer) x y)  (Page 106)

call constrain-size of the object and ensure handle-size

10.2.3 draw-feedback Method

Purpose: draw mouse feedback during commands.

(defmethod draw-feedback ((cmd mouse-down-command) x y &key clear))

x: current mouse position y: current mouse position clear: flag whether feedback has to be drawn or cleared

You override this method to define a special application dependent feedback. The default version draws a rubberband line from the start- to the current mouse position. Normally, you do not call this method. It is called by GINA each time the mouse has moved. It is overridden by GINA in the predefined commands for direct manipulation. :function boole-xor is set in gcontext before this method is called.

Related methods:

[  ] draw-feedback :around ((cmd mouse-down-command) x y &key clear)  (Page 95)

set xor-mode and foreground in the view’s gcontext

[  ] draw-feedback ((cmd object-selector) x y &key clear)  (Page 111)

draw rectangular dashed feedback

[  ] draw-feedback ((cmd object-mover) x y &key clear)  (Page 101)

draw mouse feedback while object is moved

[  ] draw-feedback ((cmd object-resizer) x y &key clear)  (Page 107)

draw outline feedback while resizing if desired

10.2.4 draw-feedback :around Method

Purpose: set xor-mode and foreground in the view’s gcontext.

(defmethod draw-feedback :around ((cmd mouse-down-command) x y &key clear))

x: current mouse position y: current mouse position clear: flag whether feedback has to be drawn or cleared

Deamon installed by GINA.

Related methods:

[o ] draw-feedback ((cmd mouse-down-command) x y &key clear)  (Page 95)

draw mouse feedback during commands

[  ] draw-feedback ((cmd object-selector) x y &key clear)  (Page 111)

draw rectangular dashed feedback

[  ] draw-feedback ((cmd object-mover) x y &key clear)  (Page 101)

draw mouse feedback while object is moved

[  ] draw-feedback ((cmd object-resizer) x y &key clear)  (Page 107)

draw outline feedback while resizing if desired

10.2.5 track-mouse Method

Purpose: process the possibly modified mouse coordinates.

(defmethod track-mouse ((cmd mouse-down-command) x y &key (started nil) (finished
nil)))

x: current mouse position y: current mouse position started: flag whether this is the first call of track-mouse finished: flag whether this is the last call of track-mouse

You override this method if each intermediate coordinate is important (e.g. for freehand drawing). The default version does not do anything. Normally, you do not call this method. It is called by GINA each time the mouse has moved. It is overridden by GINA in the predefined commands for direct manipulation.

Related methods:

[  ] track-mouse ((cmd object-mover) x y &key (started nil) (finished nil))  (Page 102)

immediately move the object if desired

[  ] track-mouse ((cmd object-resizer) x y &key (started nil) (finished nil)) (Page 107)

immediately resize the object if desired

10.2.6 mouse-idle Method

Purpose: react to timeout during mouse command.

(defmethod mouse-idle ((cmd mouse-down-command) x y))

x: current mouse position y: current mouse position

You override this method to define what happens when the mouse button is held down. The default version does not do anything. Normally, you do not call this method. It is called by GINA each time the mouse did not move for some time. It is never overridden by GINA.

10.2.7 not-submitted Method

Purpose: react to the fact that command was not submitted.

(defmethod not-submitted ((cmd mouse-down-command)))

You override this method to define what happens instead of submitting the command. The default version does not do anything. Normally, you do not call this method. It is called by GINA if the command is not submitted when the button goes up, because call-doit is nil. It is never overridden by GINA.

Related methods:

[o ] not-submitted ((cmd drag-command))  (Page 116)

react to the fact that command was not submitted

[  ] not-submitted ((cmd object-selector))  (Page 112)

only a click, deselect all selected objects

10.2.8 scroll-before-redo Method

Purpose: do the scrolling necessary so that the effect of REDO can be seen.

(defmethod scroll-before-redo ((cmd mouse-down-command)))

You rarely override this method or add deamons. The default version moves the point where the mouse-button was released into the view. Normally, you do not call this method. It is called by GINA before method redoit is called. It is never overridden by GINA. This method overrides the default behaviour inherited by class command

[  ] scroll-before-redo ((cmd command))  (Page 91)

do the scrolling necessary so that the effect of REDO can be seen

10.2.9 mouse-rectangle Method

Purpose: calculate the positive rectangle between start and x,y.

(defmethod mouse-rectangle ((cmd mouse-down-command) x y))

The returned value is x, y, positive width, positive height as multiple values. You rarely override this method or add deamons. The default version is sufficient for most cases. You can call this method when a mouse-command may flip over its start. It is called by GINA when appropriate. It is never overridden by GINA.

10.3 object-mover Class

An instance of class object-mover is a mouse-down-command to move a direct-manipulation-object. It is a subclass of mouse-down-command and command. You can define a subclass of this class. GINA does not define subclasses of this class. You can create an instance of this class.

Shared Slots:

object-mover: name overrides default name of class mouse-down-command

                       Default: "Move Object"

hysteresis mouse must be moved at least 5 pixels to drag an object

Default: 5

mouse-down-command: hysteresis minimum mouse movement before command is submitted

Default: 0

auto-scrolling flag whether automatic scrolling is desired

Default: t

idle-timeout seconds before mouse-idle is called and auto-scrolling is done when mouse is not moved

Default: 0.25

call-doit flag whether command should really be submitted

Default: t

name overrides slot of class command

                       Default: "Mouse Command"

\underline{command:} name identification shown in the history scroller

                       Default: "Command"

clock-cursor flag whether clock cursor is shown during doit

Default: nil

undoable flag whether an UNDO is possible

Default: t

causes-change flag whether the command modifies the document Default: t

Local Slots:

object-mover: move-object the object being moved x-off point within object where mouse goes down y-off point within object where mouse goes down new-x view coordinates where object is moved to new-y view coordinates where object is moved to mouse-down-command: start-x view coordinate where the mouse button went down start-y view coordinate where the mouse button went down timer-id id for xtk:change-timer and friends

Default: nil

mouse-already-moved flag if hysteresis has been reached

Default: nil

last-x view coordinate of last mouse position last-y view coordinate of last mouse position \underline{command:} document the document changed by the command view the view which shows the effect of the command view-x-offset scroll position of the view when command was issued view-y-offset scroll position of the view when command was issued

Methods of class object-mover:

[  ] constrain-mouse ((cmd object-mover) x y)  (Page 101)

use the result of constrain-position of the moved object

[  ] doit ((cmd object-mover))  (Page 102)

finally move the specified view-object

[  ] draw-feedback ((cmd object-mover) x y &key clear)  (Page 101)

draw mouse feedback while object is moved

[  ] redoit ((cmd object-mover))  (Page 103)

move the view-object forward again

[  ] track-mouse ((cmd object-mover) x y &key (started nil) (finished nil))  (Page 102)

immediately move the object if desired

[  ] undoit ((cmd object-mover))  (Page 103)

move back the view-object

Methods of superclasses:

[o ] commit ((cmd command) undone)  (Page 92)

free resources used by the command

[o ] constrain-mouse ((cmd mouse-down-command) x y)  (Page 94)

modify x and y position of mouse pointer

[o ] doit ((cmd command))  (Page 90)

execute the effect of the command

[  ] draw-feedback :around ((cmd mouse-down-command) x y &key clear)  (Page 95)

set xor-mode and foreground in the view’s gcontext

[o ] draw-feedback ((cmd mouse-down-command) x y &key clear)  (Page 95)

draw mouse feedback during commands

[o ] executable ((cmd command))  (Page 90)

check if the command is executable

[o ] mouse-idle ((cmd mouse-down-command) x y)  (Page 97)

react to timeout during mouse command

[ c] mouse-rectangle ((cmd mouse-down-command) x y)  (Page 98)

calculate the positive rectangle between start and x,y

[o ] not-submitted ((cmd mouse-down-command))  (Page 97)

react to the fact that command was not submitted

[o ] redoit ((cmd command))  (Page 91)

repeat effect of the command

[  ] scroll-before-redo ((cmd mouse-down-command))  (Page 97)

do the scrolling necessary so that the effect of REDO can be seen

[  ] scroll-before-redo ((cmd command))  (Page 91)

do the scrolling necessary so that the effect of REDO can be seen

[  ] scroll-before-undo ((cmd command))  (Page 90)

do the scrolling necessary so that the effect of UNDO can be seen

[ c] submit ((cmd command))  (Page 89)

store command in the document and call doit

[o ] track-mouse ((cmd mouse-down-command) x y &key (started nil) (finished nil))  (Page 96)

process the possibly modified mouse coordinates

[o ] undoit ((cmd command))  (Page 91)

undo effect of the command

10.3.1 make-object-mover Function

Purpose: create a new mouse-down-command object to move the specified object.

(defun make-object-mover (obj x y &key (class 'object-mover) (initargs nil)))

obj: the object being moved x: point within object where mouse goes down y: point within object where mouse goes down

This is the constructor function for class object-mover. The returned value is a newly created object of class object-mover. You can call this function. It is sometimes called by GINA.

10.3.2 constrain-mouse Method

Purpose: use the result of constrain-position of the moved object.

(defmethod constrain-mouse ((cmd object-mover) x y))

You rarely override this method or add deamons. The default version is sufficient for most cases. Normally, you do not call this method. It is called by GINA each time the mouse has moved. It is never overridden by GINA.

Related methods:

[  ] constrain-mouse ((cmd object-resizer) x y)  (Page 106)

call constrain-size of the object and ensure handle-size

[o ] constrain-mouse ((cmd mouse-down-command) x y)  (Page 94)

modify x and y position of mouse pointer

10.3.3 draw-feedback Method

Purpose: draw mouse feedback while object is moved.

(defmethod draw-feedback ((cmd object-mover) x y &key clear))

x: current mouse position y: current mouse position clear: flag whether feedback has to be drawn or cleared

You rarely override this method or add deamons. The default version is sufficient for most cases. Normally, you do not call this method. It is called by GINA each time the mouse has moved. It is never overridden by GINA. This methods overrides the default method inherited by class mouse-down-command.

Related methods:

[o ] draw-feedback ((cmd mouse-down-command) x y &key clear)  (Page 95)

draw mouse feedback during commands

[  ] draw-feedback :around ((cmd mouse-down-command) x y &key clear)  (Page 95)

set xor-mode and foreground in the view’s gcontext

[  ] draw-feedback ((cmd object-selector) x y &key clear)  (Page 111)

draw rectangular dashed feedback

[  ] draw-feedback ((cmd object-resizer) x y &key clear)  (Page 107)

draw outline feedback while resizing if desired

10.3.4 track-mouse Method

Purpose: immediately move the object if desired.

(defmethod track-mouse ((cmd object-mover) x y &key (started nil) (finished
nil)))

You rarely override this method or add deamons. The default version is sufficient for most cases. Normally, you do not call this method. It is called by GINA each time the mouse has moved. It is never overridden by GINA. This methods overrides the default method inherited by class mouse-down-command.

Related methods:

[o ] track-mouse ((cmd mouse-down-command) x y &key (started nil) (finished nil))  (Page 96)

process the possibly modified mouse coordinates

[  ] track-mouse ((cmd object-resizer) x y &key (started nil) (finished nil)) (Page 107)

immediately resize the object if desired

10.3.5 doit Method

Purpose: finally move the specified view-object.

(defmethod doit ((cmd object-mover)))

You rarely override this method or add deamons. The default version is sufficient for most cases. Normally, you do not call this method. It is called by GINA when appropriate. It is never overridden by GINA.

Related methods:

[  ] doit ((cmd object-resizer))  (Page 108)

finally resize the specified object

[o ] doit ((cmd command))  (Page 90)

execute the effect of the command

[  ] doit ((cmd object-selector))  (Page 112)

select all captured view objects

10.3.6 undoit Method

Purpose: move back the view-object.

(defmethod undoit ((cmd object-mover)))

You rarely override this method or add deamons. The default version is sufficient for most cases. Normally, you do not call this method. It is called by GINA when appropriate. It is never overridden by GINA.

Related methods:

[  ] undoit ((cmd object-resizer))  (Page 108)

give the object the original size again

[o ] undoit ((cmd command))  (Page 91)

undo effect of the command

10.3.7 redoit Method

Purpose: move the view-object forward again.

(defmethod redoit ((cmd object-mover)))

You rarely override this method or add deamons. The default version is sufficient for most cases. Normally, you do not call this method. It is called by GINA when appropriate. It is never overridden by GINA.

Related methods:

[  ] redoit ((cmd object-resizer))  (Page 108)

resize the object again

[o ] redoit ((cmd command))  (Page 91)

repeat effect of the command

10.4 object-resizer Class

An instance of class object-resizer is a mouse-down-command to resize a direct-manipulation-object. It is a subclass of mouse-down-command and command. You can define a subclass of this class. GINA does not define subclasses of this class. You can create an instance of this class.

Shared Slots:

object-resizer: name overrides default name of class mouse-down-command

                       Default: "Resize Object"

hysteresis mouse must be moved at least 2 pixels to drag an object

Default: 2

mouse-down-command: hysteresis minimum mouse movement before command is submitted

Default: 0

auto-scrolling flag whether automatic scrolling is desired

Default: t

idle-timeout seconds before mouse-idle is called and auto-scrolling is done when mouse is not moved

Default: 0.25

call-doit flag whether command should really be submitted

Default: t

name overrides slot of class command

                       Default: "Mouse Command"

\underline{command:} name identification shown in the history scroller

                       Default: "Command"

clock-cursor flag whether clock cursor is shown during doit

Default: nil

undoable flag whether an UNDO is possible

Default: t

causes-change flag whether the command modifies the document Default: t

Local Slots:

object-resizer: size-object the object being resized old-x original position of object being resized old-y original position of object being resized old-width original size of object being resized old-height original size of object being resized move-x flag whether x-coordinate of the objects position is changed move-y flag whether y-coordinate of the objects position is changed new-x new position of object being resized new-y new position of object being resized new-width new size of object being resized new-height new size of object being resized mouse-down-command: start-x view coordinate where the mouse button went down start-y view coordinate where the mouse button went down timer-id id for xtk:change-timer and friends

Default: nil

mouse-already-moved flag if hysteresis has been reached

Default: nil

last-x view coordinate of last mouse position last-y view coordinate of last mouse position \underline{command:} document the document changed by the command view the view which shows the effect of the command view-x-offset scroll position of the view when command was issued view-y-offset scroll position of the view when command was issued

Methods of class object-resizer:

[  ] constrain-mouse ((cmd object-resizer) x y)  (Page 106)

call constrain-size of the object and ensure handle-size

[  ] doit ((cmd object-resizer))  (Page 108)

finally resize the specified object

[  ] draw-feedback ((cmd object-resizer) x y &key clear)  (Page 107)

draw outline feedback while resizing if desired

[  ] redoit ((cmd object-resizer))  (Page 108)

resize the object again

[  ] track-mouse ((cmd object-resizer) x y &key (started nil) (finished nil)) (Page 107)

immediately resize the object if desired

[  ] undoit ((cmd object-resizer))  (Page 108)

give the object the original size again

Methods of superclasses:

[o ] commit ((cmd command) undone)  (Page 92)

free resources used by the command

[o ] constrain-mouse ((cmd mouse-down-command) x y)  (Page 94)

modify x and y position of mouse pointer

[o ] doit ((cmd command))  (Page 90)

execute the effect of the command

[  ] draw-feedback :around ((cmd mouse-down-command) x y &key clear)  (Page 95)

set xor-mode and foreground in the view’s gcontext

[o ] draw-feedback ((cmd mouse-down-command) x y &key clear)  (Page 95)

draw mouse feedback during commands

[o ] executable ((cmd command))  (Page 90)

check if the command is executable

[o ] mouse-idle ((cmd mouse-down-command) x y)  (Page 97)

react to timeout during mouse command

[ c] mouse-rectangle ((cmd mouse-down-command) x y)  (Page 98)

calculate the positive rectangle between start and x,y

[o ] not-submitted ((cmd mouse-down-command))  (Page 97)

react to the fact that command was not submitted

[o ] redoit ((cmd command))  (Page 91)

repeat effect of the command

[  ] scroll-before-redo ((cmd mouse-down-command))  (Page 97)

do the scrolling necessary so that the effect of REDO can be seen

[  ] scroll-before-redo ((cmd command))  (Page 91)

do the scrolling necessary so that the effect of REDO can be seen

[  ] scroll-before-undo ((cmd command))  (Page 90)

do the scrolling necessary so that the effect of UNDO can be seen

[ c] submit ((cmd command))  (Page 89)

store command in the document and call doit

[o ] track-mouse ((cmd mouse-down-command) x y &key (started nil) (finished nil))  (Page 96)

process the possibly modified mouse coordinates

[o ] undoit ((cmd command))  (Page 91)

undo effect of the command

10.4.1 make-object-resizer Function

Purpose: create a new mouse-down command object to resize the specified object.

(defun make-object-resizer (obj x y handle &key (class 'object-resizer)
                            (initargs nil)))

obj: the object being resized x: point within object where mouse went down y: point within object where mouse went down handle: 1, 2, 3, or 4 for the four corners

This is the constructor function for class object-resizer. The returned value is a newly created object of class object-resizer. You can call this function. It is sometimes called by GINA.

10.4.2 constrain-mouse Method

Purpose: call constrain-size of the object and ensure handle-size.

(defmethod constrain-mouse ((cmd object-resizer) x y))

You rarely override this method or add deamons. The default version is sufficient for most cases. Normally, you do not call this method. It is called by GINA when appropriate. It is never overridden by GINA.

Related methods:

[  ] constrain-mouse ((cmd object-mover) x y)  (Page 101)

use the result of constrain-position of the moved object

[o ] constrain-mouse ((cmd mouse-down-command) x y)  (Page 94)

modify x and y position of mouse pointer

10.4.3 draw-feedback Method

Purpose: draw outline feedback while resizing if desired.

(defmethod draw-feedback ((cmd object-resizer) x y &key clear))

You rarely override this method or add deamons. The default version is sufficient for most cases. Normally, you do not call this method. It is called by GINA when appropriate. It is never overridden by GINA.

Related methods:

[o ] draw-feedback ((cmd mouse-down-command) x y &key clear)  (Page 95)

draw mouse feedback during commands

[  ] draw-feedback :around ((cmd mouse-down-command) x y &key clear)  (Page 95)

set xor-mode and foreground in the view’s gcontext

[  ] draw-feedback ((cmd object-selector) x y &key clear)  (Page 111)

draw rectangular dashed feedback

[  ] draw-feedback ((cmd object-mover) x y &key clear)  (Page 101)

draw mouse feedback while object is moved

10.4.4 track-mouse Method

Purpose: immediately resize the object if desired.

(defmethod track-mouse ((cmd object-resizer) x y &key (started nil) (finished
nil)))

You rarely override this method or add deamons. The default version is sufficient for most cases. Normally, you do not call this method. It is called by GINA when appropriate. It is never overridden by GINA.

Related methods:

[o ] track-mouse ((cmd mouse-down-command) x y &key (started nil) (finished nil))  (Page 96)

process the possibly modified mouse coordinates

[  ] track-mouse ((cmd object-mover) x y &key (started nil) (finished nil))  (Page 102)

immediately move the object if desired

10.4.5 doit Method

Purpose: finally resize the specified object.

(defmethod doit ((cmd object-resizer)))

You rarely override this method or add deamons. The default version is sufficient for most cases. Normally, you do not call this method. It is called by GINA when appropriate. It is never overridden by GINA.

Related methods:

[  ] doit ((cmd object-mover))  (Page 102)

finally move the specified view-object

[o ] doit ((cmd command))  (Page 90)

execute the effect of the command

[  ] doit ((cmd object-selector))  (Page 112)

select all captured view objects

10.4.6 undoit Method

Purpose: give the object the original size again.

(defmethod undoit ((cmd object-resizer)))

You rarely override this method or add deamons. The default version is sufficient for most cases. Normally, you do not call this method. It is called by GINA when appropriate. It is never overridden by GINA.

Related methods:

[  ] undoit ((cmd object-mover))  (Page 103)

move back the view-object

[o ] undoit ((cmd command))  (Page 91)

undo effect of the command

10.4.7 redoit Method

Purpose: resize the object again.

(defmethod redoit ((cmd object-resizer)))

You rarely override this method or add deamons. The default version is sufficient for most cases. Normally, you do not call this method. It is called by GINA when appropriate. It is never overridden by GINA.

Related methods:

[  ] redoit ((cmd object-mover))  (Page 103)

move the view-object forward again

[o ] redoit ((cmd command))  (Page 91)

repeat effect of the command

10.5 object-selector Class

An instance of class object-selector is a mouse-down-command to select direct-manipulation-objects. It is a subclass of mouse-down-command and command. You can define a subclass of this class. GINA does not define subclasses of this class. You can create an instance of this class.

Shared Slots:

object-selector: name overrides default name of class mouse-down-command

                       Default: "Select Objects"

hysteresis mouse must be moved to select an object

Default: 2

undoable no UNDO is possible (nor necessary) for this command

Default: nil

causes-change this command does not modify the document

Default: nil

mouse-down-command: hysteresis minimum mouse movement before command is submitted

Default: 0

auto-scrolling flag whether automatic scrolling is desired

Default: t

idle-timeout seconds before mouse-idle is called and auto-scrolling is done when mouse is not moved

Default: 0.25

call-doit flag whether command should really be submitted

Default: t

name overrides slot of class command

                       Default: "Mouse Command"

\underline{command:} name identification shown in the history scroller

                       Default: "Command"

clock-cursor flag whether clock cursor is shown during doit Default: nil undoable flag whether an UNDO is possible

Default: t

causes-change flag whether the command modifies the document Default: t

Local Slots:

object-selector: extend button used (:select :extend :toggle) mouse-down-command: start-x view coordinate where the mouse button went down start-y view coordinate where the mouse button went down timer-id id for xtk:change-timer and friends

Default: nil

mouse-already-moved flag if hysteresis has been reached

Default: nil

last-x view coordinate of last mouse position last-y view coordinate of last mouse position \underline{command:} document the document changed by the command view the view which shows the effect of the command view-x-offset scroll position of the view when command was issued view-y-offset scroll position of the view when command was issued

Methods of class object-selector:

[  ] doit ((cmd object-selector))  (Page 112)

select all captured view objects

[  ] draw-feedback ((cmd object-selector) x y &key clear)  (Page 111)

draw rectangular dashed feedback

[  ] not-submitted ((cmd object-selector))  (Page 112)

only a click, deselect all selected objects

Methods of superclasses:

[o ] commit ((cmd command) undone)  (Page 92)

free resources used by the command

[o ] constrain-mouse ((cmd mouse-down-command) x y)  (Page 94)

modify x and y position of mouse pointer

[o ] doit ((cmd command))  (Page 90)

execute the effect of the command

[  ] draw-feedback :around ((cmd mouse-down-command) x y &key clear)  (Page 95)

set xor-mode and foreground in the view’s gcontext

[o ] draw-feedback ((cmd mouse-down-command) x y &key clear)  (Page 95)

draw mouse feedback during commands

[o ] executable ((cmd command))  (Page 90)

check if the command is executable

[o ] mouse-idle ((cmd mouse-down-command) x y)  (Page 97)

react to timeout during mouse command

[ c] mouse-rectangle ((cmd mouse-down-command) x y)  (Page 98)

calculate the positive rectangle between start and x,y

[o ] not-submitted ((cmd mouse-down-command))  (Page 97)

react to the fact that command was not submitted

[o ] redoit ((cmd command))  (Page 91)

repeat effect of the command

[  ] scroll-before-redo ((cmd mouse-down-command))  (Page 97)

do the scrolling necessary so that the effect of REDO can be seen

[  ] scroll-before-redo ((cmd command))  (Page 91)

do the scrolling necessary so that the effect of REDO can be seen

[  ] scroll-before-undo ((cmd command))  (Page 90)

do the scrolling necessary so that the effect of UNDO can be seen

[ c] submit ((cmd command))  (Page 89)

store command in the document and call doit

[o ] track-mouse ((cmd mouse-down-command) x y &key (started nil) (finished nil))  (Page 96)

process the possibly modified mouse coordinates

[o ] undoit ((cmd command))  (Page 91)

undo effect of the command

10.5.1 make-object-selector Function

Purpose: create a new mouse-down-command object to select objects.

(defun make-object-selector (view x y extend))

view: the view where the mouse went down x: mouse down position y: mouse down position extend: button used for selection

This is the constructor function for class object-selector. The returned value is a newly created object of class object-selector. You can call this function. It is sometimes called by GINA.

10.5.2 draw-feedback Method

Purpose: draw rectangular dashed feedback.

(defmethod draw-feedback ((cmd object-selector) x y &key clear))

You rarely override this method or add deamons. The default version is sufficient for most cases. Normally, you do not call this method. It is called by GINA when appropriate. It is never overridden by GINA.

[o ] draw-feedback ((cmd mouse-down-command) x y &key clear)  (Page 95)

draw mouse feedback during commands

[  ] draw-feedback :around ((cmd mouse-down-command) x y &key clear)  (Page 95)

set xor-mode and foreground in the view’s gcontext

[  ] draw-feedback ((cmd object-mover) x y &key clear)  (Page 101)

draw mouse feedback while object is moved

[  ] draw-feedback ((cmd object-resizer) x y &key clear)  (Page 107)

draw outline feedback while resizing if desired

10.5.3 doit Method

Purpose: select all captured view objects.

(defmethod doit ((cmd object-selector)))

You rarely override this method or add deamons. The default version is sufficient for most cases. Normally, you do not call this method. It is called by GINA when appropriate. It is never overridden by GINA.

Related methods:

[  ] doit ((cmd object-mover))  (Page 102)

finally move the specified view-object

[  ] doit ((cmd object-resizer))  (Page 108)

finally resize the specified object

[o ] doit ((cmd command))  (Page 90)

execute the effect of the command

10.5.4 not-submitted Method

Purpose: only a click, deselect all selected objects.

(defmethod not-submitted ((cmd object-selector)))

You rarely override this method or add deamons. The default version is sufficient for most cases. Normally, you do not call this method. It is called by GINA when appropriate. It is never overridden by GINA.

[o ] not-submitted ((cmd drag-command))  (Page 116)

react to the fact that command was not submitted

[o ] not-submitted ((cmd mouse-down-command))  (Page 97)

react to the fact that command was not submitted

10.6 drag-command Class

An instance of class drag-command is a command class to implement drag and drop across windows. It is a subclass of command. You must define a subclass of this class. GINA does not define subclasses of this class. You never create an instance of this class.

Shared Slots:

drag-command: protocol-id a unique id string for inter-app communication

Default: :drag

hysteresis minimum mouse movement before command is submitted

Default: 0

do-tracking whether continuous tracking is performed

Default: t

lazy-tracking whether track-target is called only once per target

Default: nil

call-doit flag whether command should really be submitted

Default: t

\underline{command:} name identification shown in the history scroller

                       Default: "Command"

clock-cursor flag whether clock cursor is shown during doit

Default: nil

undoable flag whether an UNDO is possible

Default: t

causes-change flag whether the command modifies the document Default: t

Local Slots:

drag-command: target-list a list of window-widget-value tripels of poss. targets shell-to-move an override shell to be moved as feedback received-from nil or an x-window from another document mouse-already-moved flag if hysteresis has been reached

Default: nil

source-x the starting x position relative to the source source-y the starting y position relative to the source target-x the current x position relative to the target target-y the current y position relative to the target current-target the current target, if any

Default: nil

current-value the current value, if any

Default: nil

transfer-value a value returned from the target application \underline{command:} document the document changed by the command view the view which shows the effect of the command view-x-offset scroll position of the view when command was issued view-y-offset scroll position of the view when command was issued

Methods of class drag-command:

[o ] draw-target-feedback ((cmd drag-command) widget rel-x rel-y value &key (clear nil)) (Page 115)

draw feedback in the target

[o ] not-submitted ((cmd drag-command))  (Page 116)

react to the fact that command was not submitted

[o ] track-target ((cmd drag-command) widget rel-x rel-y value)  (Page 115)

track mouse motion

Methods of superclasses:

[o ] commit ((cmd command) undone)  (Page 92)

free resources used by the command

[o ] doit ((cmd command))  (Page 90)

execute the effect of the command

[o ] executable ((cmd command))  (Page 90)

check if the command is executable

[o ] redoit ((cmd command))  (Page 91)

repeat effect of the command

[  ] scroll-before-redo ((cmd command))  (Page 91)

do the scrolling necessary so that the effect of REDO can be seen

[  ] scroll-before-undo ((cmd command))  (Page 90)

do the scrolling necessary so that the effect of UNDO can be seen

[ c] submit ((cmd command))  (Page 89)

store command in the document and call doit

[o ] undoit ((cmd command))  (Page 91)

undo effect of the command

10.6.1 make-drag-command Function

Purpose: create a drag-command object.

(defun make-drag-command (document source rel-x rel-y target-list &key
                          (x-off 0) (y-off 0) (received-from nil)
                          (cursor :dotbox) (shell-to-move nil)

                          (transfer-value nil) (class 'drag-command)
                          (initargs nil)))

document: the document modified by the command source: a widget that receives motion events rel-x: the relative x position where the command starts rel-y: the relative y position where the command starts target-list: a list of widget-value pairs belonging to this doc x-off: x offset between shell and source y-off: y offset between shell and source transfer-value: the value to transfer to target

This is the constructor function for class drag-command. The returned value is a newly created object of class drag-command. You can call this function. It is never called by GINA.

10.6.2 draw-target-feedback Method

Purpose: draw feedback in the target.

(defmethod draw-target-feedback ((cmd drag-command) widget rel-x rel-y value &key
(clear nil)))

widget: one of the widgets from target-list rel-x: x position relative to widget rel-y: y position relative to widget value: corresponding value from target-list

You override this method to define individual feedback drawing with xor. The default version does not do anything. Normally, you do not call this method. It is called by GINA on pointer motion when over target widget. It is never overridden by GINA.

10.6.3 track-target Method

Purpose: track mouse motion.

(defmethod track-target ((cmd drag-command) widget rel-x rel-y value))

widget: one of the widgets from target-list, or nil if outside rel-x: x position relative to widget (or nil) rel-y: y position relative to widget (or nil) value: corresponding value from target-list You override this method to execute individual mouse tracking. The default version does not do anything. Normally, you do not call this method. It is called by GINA on pointer motion when over target widget, or when just left target. It is never overridden by GINA. The positions are inaccurate if lazy-tracking is enabled. Outside a target it is called only once with nil parameters, until a new target is entered, regardless of lazy-tracking.

10.6.4 not-submitted Method

Purpose: react to the fact that command was not submitted.

(defmethod not-submitted ((cmd drag-command)))

You override this method to define what happens instead of submitting the command. The default version does not do anything. Normally, you do not call this method. It is called by GINA on button-release, if no target hit or call-doit is nil. It is never overridden by GINA.

Related methods:

[o ] not-submitted ((cmd mouse-down-command))  (Page 97)

react to the fact that command was not submitted

[  ] not-submitted ((cmd object-selector))  (Page 112)

only a click, deselect all selected objects

The Class WIDGET and its Subclasses

11.1 widget Class

The class widget is the abstract superclass of all CLOS-Objects encapsulating Motif widgets. You rarely define subclasses of this class. GINA defines subclasses of this class: all Motif widgets are subclasses. You never create an instance of this class.

Local Slots:

widget-id integer returned by CLM create-widget call group-widget-id id used when the whole group is meant widget-id-for-sons may be different from widget-id in compound widgets parent the parent widget object in the hierarchy name name string for resource database lookup width total width in pixels height total height in pixels x-pos the x-coordinate relative to the parent y-pos the y-coordinate relative to the parent

Resource slots:

y-pos x-pos height width

Methods of class widget:

[ c] add-event-handler ((w widget) mask function-or-callback)  (Page 119)

add an event handler for some basic X event

[ c] add-to-tab-group ((widget widget))  (Page 124)

add widget to the tab-group of its shell

[ c] define-cursor ((widget widget) cursor-nr-or-keyword)  (Page 126)

permanently set the cursor for a widget

[ c] destroy ((w widget))  (Page 121)

destroy the widget objects and all its sons

[ c] enclosing-shell ((widget widget))  (Page 125)

walk up widget tree until shell

[  ] get-clx-window ((w widget))  (Page 123)

get the CLX window id of a widget

[ c] get-motif-resources ((w widget) &rest resources)  (Page 120)

get up-to-date motif-resources from toolkit

[  ] inspect-clicked ((w widget) &rest parm-list)  (Page 119)

the widget is clicked, check for inspect click for debugging

[ c] manage ((w widget))  (Page 121)

make widget managed

[ c] move ((widget widget) new-x new-y &key &allow-other-keys)  (Page 122)

change x and y coordinates

[ c] point-inside ((widget widget) x y)  (Page 124)

test whether point lies inside a widget

[ c] remove-from-tab-group ((widget widget))  (Page 124)

remove widget from the tab-group of its shell

[ c] resize ((widget widget) new-width new-height &key &allow-other-keys)  (Page 123)

change width and height

[ c] root-coordinates ((w widget) &key (x 0) (y 0))  (Page 123)

translate coordinates relative to root window

[ c] set-keyboard-focus ((widget widget))  (Page 125)

try to set the keyboard focus to a widget

[ c] set-motif-resources ((w widget) &rest resource-pairs)  (Page 120)

set motif-resources later than at initialization

[ c] set-sensitivity ((widget widget) new-value)  (Page 125)

set the sensitivity, i.e. whether widget reacts to mouse clicks

[  ] son-created ((w widget) son)  (Page 119)

parent is informed that a new son is created

[ c] unmanage ((w widget))  (Page 122)

make widget unmanaged

[ c] update-slots ((w widget))  (Page 122)

ask the toolkit server for current size and position values

11.1.1 make-widget Function

Purpose: create a new CLOS Object representing a widget.

(defun make-widget (parent &key (class 'widget) (initargs nil)
                    (motif-widget-class :push-button) (managed t) (name class)
                    (motif-resources nil)))

parent: the parent widget

This is the constructor function for class widget. The returned value is a newly created object of class widget. You can call this function in the constructor of subclasses. It is called by GINA whenever any kind of widget is created.

11.1.2 add-event-handler Method

Purpose: add an event handler for some basic X event.

(defmethod add-event-handler ((w widget) mask function-or-callback))

mask: logical or of CLX event masks

You rarely override this method or add deamons. The default version is sufficient for most cases. You can call this method if more specific events are desired. It is called by GINA to install event handlers for the most important events. It is never overridden by GINA. mask :no-event-mask registers all non-maskable events

11.1.3 inspect-clicked Method

Purpose: the widget is clicked, check for inspect click for debugging.

(defmethod inspect-clicked ((w widget) &rest parm-list))

You rarely override this method or add deamons. The default version is sufficient for most cases. Normally, you do not call this method. It is called by GINA if inspect-click flag in application enabled. It is never overridden by GINA. parm-list: type x y root-x root-y state button

11.1.4 son-created Method

Purpose: parent is informed that a new son is created.

(defmethod son-created ((w widget) son))

You rarely override this method or add deamons. The default version does not do anything. Normally, you do not call this method. It is called by GINA whenever a son of this widget is created. It is never overridden by GINA.

Related methods:

[  ] son-created ((scroller scroller) son)  (Page 178)

in this case the scroller is informed that the work-area is created

11.1.5 get-motif-resources Method

Purpose: get up-to-date motif-resources from toolkit.

(defmethod get-motif-resources ((w widget) &rest resources))

The returned value is list of requested resource values. You rarely override this method or add deamons. The default version is sufficient for most cases. You can call this method to find out unusual resource values. It is called by GINA rarely. It is never overridden by GINA.

Example

(get-motif-resources frame :shadow-thickness :shadow-type)

returns (2 :etched-in)

11.1.6 set-motif-resources Method

Purpose: set motif-resources later than at initialization.

(defmethod set-motif-resources ((w widget) &rest resource-pairs))

You rarely override this method or add deamons. The default version is sufficient for most cases. You can call this method to set non-slot resources in the Motif server. It is called by GINA rarely. It is never overridden by GINA.

Example

(set-motif-resources frame :shadow-thickness 4 :shadow-type :etched-out)

11.1.7 more-initargs Macro

Purpose: append more initarg-pairs to local variable initargs

(defmacro more-initargs (&rest initarg-pairs))

You can call this macro in the constructor of a new subclass of a widget. It is called by GINA in constructor-functions of widgets.

Example

(let ((initargs '(:a 3 :b 7))) (more-initargs :x 5 :y (+ 3 4)))

returns (:a 3 :b 7 :x 5 :y 7)

11.1.8 more-motif-resources Macro

Purpose: prepend more resource-pairs to local variable motif-resources

(defmacro more-motif-resources (&rest resource-pairs))

You can call this macro in the constructor of a new subclass of a widget. It is called by GINA in constructor-functions of widgets.

Example

(let ((motif-resources '(:a 3 :b 7))) (more-motif-resources :x 5 :y (+ 3 4)))

returns (:x 5 :y :7 a 3 :b 7)

11.1.9 destroy Method

Purpose: destroy the widget objects and all its sons.

(defmethod destroy ((w widget)))

You rarely override this method or add deamons. The default version is sufficient for most cases. You can call this method to destroy widgets no longer needed. It is called by GINA when appropriate. It is never overridden by GINA.

Related methods:

[ c] destroy ((shell toplevel-shell))  (Page 132)

destroy the shell and all its children

[  ] destroy :before ((shell basic-document-shell))  (Page 141)

update list of toplevel-shells of the document

11.1.10 manage Method

Purpose: make widget managed.

(defmethod manage ((w widget)))

You rarely override this method or add deamons. The default version is sufficient for most cases. You can call this method to make a widget visible. It is called by GINA when appropriate. It is never overridden by GINA.

11.1.11 unmanage Method

Purpose: make widget unmanaged.

(defmethod unmanage ((w widget)))

You rarely override this method or add deamons. The default version is sufficient for most cases. You can call this method to make a widget temporarily invisible. It is called by GINA when appropriate. It is never overridden by GINA.

11.1.12 update-slots Method

Purpose: ask the toolkit server for current size and position values.

(defmethod update-slots ((w widget)))

You rarely override this method or add deamons. The default version is sufficient for most cases. You can call this method to bring the cached slots up to date. It is called by GINA when appropriate. It is never overridden by GINA.

11.1.13 move Method

Purpose: change x and y coordinates.

(defmethod move ((widget widget) new-x new-y &key &allow-other-keys))

You rarely override this method or add deamons. The default version is sufficient for most cases. You can call this method to reposition a widget. It is called by GINA when appropriate. It is never overridden by GINA.

Related methods:

[ c] move ((view-object view-object) new-x new-y &key (redraw t) &allow-other-keys)  (Page 60)

change x and y coordinates

11.1.14 resize Method

Purpose: change width and height.

(defmethod resize ((widget widget) new-width new-height &key &allow-other-keys))

You rarely override this method or add deamons. The default version is sufficient for most cases. You can call this method to resize a widget. It is called by GINA when appropriate. It is never overridden by GINA.

Related methods:

[ c] resize ((view-object view-object) new-width new-height &key (redraw t) &allow-other-keys) (Page 60)

change width and height

11.1.15 root-coordinates Method

Purpose: translate coordinates relative to root window.

(defmethod root-coordinates ((w widget) &key (x 0) (y 0)))

The returned value is (values x y). You rarely override this method or add deamons. The default version is sufficient for most cases. You can call this method to get the absolute position of a point in a widget. It is called by GINA when appropriate. It is never overridden by GINA.

11.1.16 get-clx-window Method

Purpose: get the CLX window id of a widget.

(defmethod get-clx-window ((w widget)))

The returned value is a CLX window. You rarely override this method or add deamons. The default version is sufficient for most cases. Normally, you do not call this method. It is called by GINA when appropriate. It is never overridden by GINA.

11.1.17 point-inside Method

Purpose: test whether point lies inside a widget.

(defmethod point-inside ((widget widget) x y))

x: x-pos relative to parent widget y: y-pos relative to parent widget

The returned value is flag whether inside. You rarely override this method or add deamons. The default version is sufficient for most cases. You can call this method. It is called by GINA when appropriate. It is never overridden by GINA.

Related methods:

[oc] point-inside ((view-object view-object) x y)  (Page 59)

check if given point in view coordinates is inside the object

[  ] point-inside ((icon movable-icon) x y)  (Page 84)

check if given point in view coordinates is inside the icon

11.1.18 add-to-tab-group Method

Purpose: add widget to the tab-group of its shell.

(defmethod add-to-tab-group ((widget widget)))

You rarely override this method or add deamons. The default version is sufficient for most cases. You can call this method to add other widgets to the shells tab-group. It is called by GINA to add text-widgets to the shells tab-group. It is never overridden by GINA.

11.1.19 remove-from-tab-group Method

Purpose: remove widget from the tab-group of its shell.

(defmethod remove-from-tab-group ((widget widget)))

You rarely override this method or add deamons. The default version is sufficient for most cases. You can call this method to remove a widget from the tab-group. It is called by GINA when appropriate. It is never overridden by GINA.

11.1.20 set-keyboard-focus Method

Purpose: try to set the keyboard focus to a widget.

(defmethod set-keyboard-focus ((widget widget)))

The returned value is T if focus could be transferred, else NIL. You rarely override this method or add deamons. The default version is sufficient for most cases. You can call this method to enable keyboard input, e.g. in a view. It is called by GINA when appropriate. It is never overridden by GINA.

11.1.21 set-sensitivity Method

Purpose: set the sensitivity, i.e. whether widget reacts to mouse clicks.

(defmethod set-sensitivity ((widget widget) new-value))

You rarely override this method or add deamons. The default version is sufficient for most cases. You can call this method to mark temporarily inapplicable widgets or groups. It is called by GINA when appropriate. It is never overridden by GINA.

11.1.22 enclosing-shell Method

Purpose: walk up widget tree until shell.

(defmethod enclosing-shell ((widget widget)))

You rarely override this method or add deamons. The default version is sufficient for most cases. You can call this method to find out the shell in which this widgets lies. It is called by GINA when appropriate. It is overridden by GINA for shell-widgets, which just return themself.

Related methods:

[  ] enclosing-shell ((shell shell))  (Page 129)

override to return shell itself

11.1.23 define-cursor Method

Purpose: permanently set the cursor for a widget.

(defmethod define-cursor ((widget widget) cursor-nr-or-keyword))

cursor-nr-or-keyword: number or keyword for the cursor

You rarely override this method or add deamons. The default version is sufficient for most cases. You can call this method. It is called by GINA when appropriate. It is never overridden by GINA. Cursor can be the result of a call to xtk:create-font-cursor or xtk:create-pixmap-cursor or a keyword like :hand, :arrow ... (print (xtk:all-cursors)) lists all available keywords.

Example

(with-application-stopped
  (define-cursor (main-view (first (document-list *application*))) :hand))
(with-application-stopped
  (define-cursor
    (main-view (first (document-list *application*)))
    (xtk:create-pixmap-cursor
      "/home/spenke/pixmaps/term"
      "/home/spenke/pixmaps/term")))

11.2 shell Class

The class shell is the abstract superclass of all Motif-shells. It is a subclass of widget. You rarely define subclasses of this class. GINA defines subclasses of this class. You never create an instance of this class.

Callbacks:

popup-callback  ()

Local Slots:

\underline{shell:} title title string views all views within the shell

Default: nil

document the document belonging to the shell, or nil Default: nil drag-protocols a list of keywords of accepted drag-commands

Default: nil

\underline{widget:} widget-id integer returned by CLM create-widget call group-widget-id id used when the whole group is meant widget-id-for-sons may be different from widget-id in compound widgets parent the parent widget object in the hierarchy name name string for resource database lookup width total width in pixels height total height in pixels x-pos the x-coordinate relative to the parent y-pos the y-coordinate relative to the parent

Resource slots:

title

Methods of class shell:

[  ] enclosing-shell ((shell shell))  (Page 129)

override to return shell itself

[o ] handle-button-press ((shell shell) &rest event-data)  (Page 128)

low level event handler for button-press events

[ c] pop-down ((shell shell))  (Page 129)

popdown the underlying widget

[ c] pop-up ((shell shell))  (Page 128)

popup the underlying widget

11.2.1 make-shell Function

Purpose: create a new CLOS Object representing a shell.

(defun make-shell (parent title &key (class 'shell) (initargs nil)
                   (motif-widget-class :shell) (name class)
                   (motif-resources nil)))

parent: the parent widget title: the title string

This is the constructor function for class shell. The returned value is a newly created object of class shell. You can call this function in constructors of app-defined subclasses. It is called by GINA in the constructors for subclasses.

11.2.2 handle-button-press Method

Purpose: low level event handler for button-press events.

(defmethod handle-button-press ((shell shell) &rest event-data))

event-data: a list of event details

You override this method if you are interested in special event details. The default version propagates command creation to document. Normally, you do not call this method. It is called by GINA in response to foreign drop events. It is never overridden by GINA.

Related methods:

[o ] handle-button-press ((view view) &rest event-data)  (Page 43)

low level event handler for button-press events

11.2.3 pop-up Method

Purpose: popup the underlying widget.

(defmethod pop-up ((shell shell)))

You rarely override this method or add deamons. The default version is sufficient for most cases. You can call this method to make a secondary window visible. It is called by GINA when appropriate. It is overridden by GINA in some shell subclasses.

Related methods:

[ c] pop-up ((shell modeless-dialog-shell))  (Page 135)

popup the underlying widget

[ c] pop-up ((box modal-dialog-box))  (Page 207)

bring up the modal dialog

[  ] pop-up :after ((shell toplevel-shell))  (Page 131)

register shell at the application

[ c] pop-up ((box modeless-dialog-box))  (Page 204)

show the modeless dialog box

[ c] pop-up ((box tool-dialog-box))  (Page 210)

show the tool dialog box

11.2.4 pop-down Method

Purpose: popdown the underlying widget.

(defmethod pop-down ((shell shell)))

You rarely override this method or add deamons. The default version is sufficient for most cases. You can call this method to make a secondary window disappear. It is called by GINA when appropriate. It is overridden by GINA in some shell subclasses.

Related methods:

[ c] pop-down ((box tool-dialog-box))  (Page 211)

hide the tool dialog box

[ c] pop-down ((box modeless-dialog-box))  (Page 205)

hide the modeless dialog box

[ c] pop-down ((box modal-dialog-box))  (Page 208)

end the modal dialog

[ c] pop-down ((shell modeless-dialog-shell))  (Page 136)

popdown the underlying widget

11.2.5 enclosing-shell Method

Purpose: override to return shell itself.

(defmethod enclosing-shell ((shell shell)))

You rarely override this method or add deamons. The default version is sufficient for most cases. Normally, you do not call this method. It is called by GINA when appropriate. It is never overridden by GINA.

Related methods:

[ c] enclosing-shell ((widget widget))  (Page 125)

walk up widget tree until shell

11.3 toplevel-shell Class

The class toplevel-shell is the abstract superclass of all document-shells and modeless dialog boxes. It is a subclass of shell and widget. You rarely define subclasses of this class. GINA defines subclasses of this class. You never create an instance of this class.

Callbacks:

popup-callback  ()

Local Slots:

\underline{shell:} title title string views all views within the shell

Default: nil

document the document belonging to the shell, or nil

Default: nil

drag-protocols a list of keywords of accepted drag-commands

Default: nil

\underline{widget:} widget-id integer returned by CLM create-widget call group-widget-id id used when the whole group is meant widget-id-for-sons may be different from widget-id in compound widgets parent the parent widget object in the hierarchy name name string for resource database lookup width total width in pixels height total height in pixels x-pos the x-coordinate relative to the parent y-pos the y-coordinate relative to the parent

Methods of class toplevel-shell:

[o ] closed-by-wm ((shell toplevel-shell))  (Page 132)

shell is being closed by the window manager

[ c] destroy ((shell toplevel-shell))  (Page 132)

destroy the shell and all its children

[ c] expose ((shell toplevel-shell))  (Page 132)

bring window to front and set input focus

[  ] pop-up :after ((shell toplevel-shell))  (Page 131)

register shell at the application

[o ] resized-by-user ((shell toplevel-shell))  (Page 131)

hook for reaction to user resizing the shell

Methods of superclasses:

[  ] enclosing-shell ((shell shell))  (Page 129)

override to return shell itself

[o ] handle-button-press ((shell shell) &rest event-data)  (Page 128)

low level event handler for button-press events

[ c] pop-down ((shell shell))  (Page 129)

popdown the underlying widget

[ c] pop-up ((shell shell))  (Page 128)

popup the underlying widget

11.3.1 make-toplevel-shell Function

Purpose: create a new CLOS Object representing a toplevel-shell.

(defun make-toplevel-shell (title &key (parent nil) (allow-shell-resize nil)
                            (class 'toplevel-shell) (initargs nil)
                            (motif-widget-class :toplevel-shell) (name class)
                            (motif-resources nil)))

title: the title string parent: default: directly under invisible app-shell allow-shell-resize: whether resizable by changing children

This is the constructor function for class toplevel-shell. The returned value is a newly created object of class toplevel-shell. You can call this function. It is called by GINA in the constructors for subclasses.

11.3.2 pop-up :after Method

Purpose: register shell at the application.

(defmethod pop-up :after ((shell toplevel-shell)))

Deamon installed by GINA.

Related methods:

[ c] pop-up ((shell modeless-dialog-shell))  (Page 135)

popup the underlying widget

[ c] pop-up ((box modal-dialog-box))  (Page 207)

bring up the modal dialog

[ c] pop-up ((box modeless-dialog-box))  (Page 204)

show the modeless dialog box

[ c] pop-up ((box tool-dialog-box))  (Page 210)

show the tool dialog box

[ c] pop-up ((shell shell))  (Page 128)

popup the underlying widget

11.3.3 resized-by-user Method

Purpose: hook for reaction to user resizing the shell.

(defmethod resized-by-user ((shell toplevel-shell)))

You can override this method. The default version calls update-slots. Normally, you do not call this method. It is called by GINA when appropriate. It is never overridden by GINA. May currently be called even if size unchanged

11.3.4 expose Method

Purpose: bring window to front and set input focus.

(defmethod expose ((shell toplevel-shell)))

You rarely override this method or add deamons. The default version is sufficient for most cases. You can call this method to focus attention on a secondary window. It is called by GINA when appropriate. It is never overridden by GINA. Should be called only by the process owning the shell.

11.3.5 destroy Method

Purpose: destroy the shell and all its children.

(defmethod destroy ((shell toplevel-shell)))

You rarely override this method or add deamons. The default version is sufficient for most cases. You can call this method to destroy a secondary window. It is called by GINA when appropriate. It is never overridden by GINA.

Related methods:

[ c] destroy ((w widget))  (Page 121)

destroy the widget objects and all its sons

[  ] destroy :before ((shell basic-document-shell))  (Page 141)

update list of toplevel-shells of the document

11.3.6 closed-by-wm Method

Purpose: shell is being closed by the window manager.

(defmethod closed-by-wm ((shell toplevel-shell)))

You can override this method. The default version calls destroy. Normally, you do not call this method. It is called by GINA when appropriate. It is overridden by GINA in some subclasses.

Related methods:

[  ] closed-by-wm ((shell modal-dialog-shell))  (Page 138)

modal-dialog-shells cannot be closed by the window manager

[o ] closed-by-wm ((shell basic-document-shell))  (Page 142)

closing a document shell means closing its document

[o ] closed-by-wm ((box dialog-box))  (Page 202)

dialog-box is being closed by the window manager

11.3.7 with-cursor Macro

Purpose: use cursor for the execution of body in all application windows

(defmacro with-cursor ((cursor) &body body))

You can call this macro. It is called by GINA when appropriate.

Example

(with-cursor (:circle) (sleep 10))

11.3.8 with-clock-cursor Macro

Purpose: use clock cursor for the execution of body in all application windows

(defmacro with-clock-cursor (&body body))

You can call this macro to signal a time-consuming operation. It is called by GINA when appropriate.

Example

(with-clock-cursor (sleep 10))

11.4 modeless-dialog-shell Class

The class modeless-dialog-shell is the Motif dialog-shell widget used for modeless dialogs. It is a subclass of toplevel-shell, shell and widget. You rarely define subclasses of this class. GINA does not define subclasses of this class. You can create an instance of this class.

popup-callback  ()

Local Slots:

modeless-dialog-shell: dialog-box its child, must be set after creation \underline{shell:} title title string views all views within the shell

Default: nil

document the document belonging to the shell, or nil

Default: nil

drag-protocols a list of keywords of accepted drag-commands

Default: nil

\underline{widget:} widget-id integer returned by CLM create-widget call group-widget-id id used when the whole group is meant widget-id-for-sons may be different from widget-id in compound widgets parent the parent widget object in the hierarchy name name string for resource database lookup width total width in pixels height total height in pixels x-pos the x-coordinate relative to the parent y-pos the y-coordinate relative to the parent

Methods of class modeless-dialog-shell:

[ c] pop-down ((shell modeless-dialog-shell))  (Page 136)

popdown the underlying widget

[ c] pop-up ((shell modeless-dialog-shell))  (Page 135)

popup the underlying widget

Methods of superclasses:

[o ] closed-by-wm ((shell toplevel-shell))  (Page 132)

shell is being closed by the window manager

[ c] destroy ((shell toplevel-shell))  (Page 132)

destroy the shell and all its children

[  ] enclosing-shell ((shell shell))  (Page 129)

override to return shell itself

[ c] expose ((shell toplevel-shell))  (Page 132)

bring window to front and set input focus

[o ] handle-button-press ((shell shell) &rest event-data)  (Page 128)

low level event handler for button-press events

[ c] pop-down ((shell shell))  (Page 129)

popdown the underlying widget

[  ] pop-up :after ((shell toplevel-shell))  (Page 131)

register shell at the application

[ c] pop-up ((shell shell))  (Page 128)

popup the underlying widget

[o ] resized-by-user ((shell toplevel-shell))  (Page 131)

hook for reaction to user resizing the shell

11.4.1 make-modeless-dialog-shell Function

Purpose: create CLOS Object for a dialog-shell for modeless dialogs.

(defun make-modeless-dialog-shell (title &key
                                   (parent-shell
                                    (main-shell (first
                                                  (document-list
                                                   *application*))))
                                   (allow-shell-resize nil)
                                   (class 'modeless-dialog-shell)
                                   (initargs nil)
                                   (motif-widget-class :dialog-shell)
                                   (name class) (motif-resources nil)))

title: the title string parent-shell: default: main-shell of first document of application allow-shell-resize: whether resizable by changing children

This is the constructor function for class modeless-dialog-shell. The returned value is a newly created object of class modeless-dialog-shell. You can call this function. It is sometimes called by GINA.

11.4.2 pop-up Method

Purpose: popup the underlying widget.

(defmethod pop-up ((shell modeless-dialog-shell)))

You rarely override this method or add deamons. The default version is sufficient for most cases. You can call this method to make a secondary window visible. It is called by GINA when appropriate. It is overridden by GINA in some shell subclasses.

Related methods:

[ c] pop-up ((box modal-dialog-box))  (Page 207)

bring up the modal dialog

[  ] pop-up :after ((shell toplevel-shell))  (Page 131)

register shell at the application

[ c] pop-up ((box modeless-dialog-box))  (Page 204)

show the modeless dialog box

[ c] pop-up ((box tool-dialog-box))  (Page 210)

show the tool dialog box

[ c] pop-up ((shell shell))  (Page 128)

popup the underlying widget

11.4.3 pop-down Method

Purpose: popdown the underlying widget.

(defmethod pop-down ((shell modeless-dialog-shell)))

You rarely override this method or add deamons. The default version is sufficient for most cases. You can call this method to make a secondary window disappear. It is called by GINA when appropriate. It is overridden by GINA in some shell subclasses.

Related methods:

[ c] pop-down ((shell shell))  (Page 129)

popdown the underlying widget

[ c] pop-down ((box tool-dialog-box))  (Page 211)

hide the tool dialog box

[ c] pop-down ((box modeless-dialog-box))  (Page 205)

hide the modeless dialog box

[ c] pop-down ((box modal-dialog-box))  (Page 208)

end the modal dialog

11.5 modal-dialog-shell Class

The class modal-dialog-shell is the Motif dialog-shell widget used for modal dialogs. It is a subclass of shell and widget. You rarely define subclasses of this class. GINA does not define subclasses of this class. You can create an instance of this class.

Callbacks:

popup-callback  ()

Local Slots:

\underline{shell:} title title string views all views within the shell

Default: nil

document the document belonging to the shell, or nil

Default: nil

drag-protocols a list of keywords of accepted drag-commands

Default: nil

\underline{widget:} widget-id integer returned by CLM create-widget call group-widget-id id used when the whole group is meant widget-id-for-sons may be different from widget-id in compound widgets parent the parent widget object in the hierarchy name name string for resource database lookup width total width in pixels height total height in pixels x-pos the x-coordinate relative to the parent y-pos the y-coordinate relative to the parent

Methods of class modal-dialog-shell:

[  ] closed-by-wm ((shell modal-dialog-shell))  (Page 138)

modal-dialog-shells cannot be closed by the window manager

Methods of superclasses:

[  ] enclosing-shell ((shell shell))  (Page 129)

override to return shell itself

[o ] handle-button-press ((shell shell) &rest event-data)  (Page 128)

low level event handler for button-press events

[ c] pop-down ((shell shell))  (Page 129)

popdown the underlying widget

[ c] pop-up ((shell shell))  (Page 128)

popup the underlying widget

11.5.1 make-modal-dialog-shell Function

Purpose: create CLOS Object for a dialog-shell for modal dialogs.

(defun make-modal-dialog-shell (title &key
                                (parent-shell
                                 (main-shell (first
                                               (document-list *application*))))
                                (allow-shell-resize nil)
                                (class 'modal-dialog-shell) (initargs nil)
                                (motif-widget-class :dialog-shell) (name class)
                                (motif-resources nil)))

title: the title string parent-shell: default: main shell of first document of application allow-shell-resize: whether resizable by changing children

This is the constructor function for class modal-dialog-shell. The returned value is a newly created object of class modal-dialog-shell. You can call this function. It is sometimes called by GINA.

11.5.2 closed-by-wm Method

Purpose: modal-dialog-shells cannot be closed by the window manager.

(defmethod closed-by-wm ((shell modal-dialog-shell)))

You rarely override this method or add deamons. The default version just beeps. Normally, you do not call this method. It is called by GINA when appropriate. It is never overridden by GINA.

Related methods:

[o ] closed-by-wm ((shell toplevel-shell))  (Page 132)

shell is being closed by the window manager

[o ] closed-by-wm ((shell basic-document-shell))  (Page 142)

closing a document shell means closing its document

[o ] closed-by-wm ((box dialog-box))  (Page 202)

dialog-box is being closed by the window manager

11.6 menu-shell Class

The class menu-shell is the Motif menu-shell widget. It is a subclass of shell and widget. You rarely define subclasses of this class. GINA does not define subclasses of this class. You can create an instance of this class.

Callbacks:

popup-callback  ()

\underline{shell:} title title string views all views within the shell

Default: nil

document the document belonging to the shell, or nil

Default: nil

drag-protocols a list of keywords of accepted drag-commands

Default: nil

\underline{widget:} widget-id integer returned by CLM create-widget call group-widget-id id used when the whole group is meant widget-id-for-sons may be different from widget-id in compound widgets parent the parent widget object in the hierarchy name name string for resource database lookup width total width in pixels height total height in pixels x-pos the x-coordinate relative to the parent y-pos the y-coordinate relative to the parent

Methods of superclasses:

[  ] enclosing-shell ((shell shell))  (Page 129)

override to return shell itself

[o ] handle-button-press ((shell shell) &rest event-data)  (Page 128)

low level event handler for button-press events

[ c] pop-down ((shell shell))  (Page 129)

popdown the underlying widget

[ c] pop-up ((shell shell))  (Page 128)

popup the underlying widget

11.6.1 make-menu-shell Function

Purpose: create a new CLOS Object representing a menu-shell.

(defun make-menu-shell (menubar &key (class 'menu-shell) (initargs nil)
                        (motif-widget-class :menu-shell) (name class)
                        (motif-resources nil)))

menubar: the parent widget, a menu bar or menu shell

This is the constructor function for class menu-shell. The returned value is a newly created object of class menu-shell. You can call this function. It is sometimes called by GINA.

11.7 basic-document-shell Class

An instance of class basic-document-shell is a toplevel-shell for a document without a menubar. It is a subclass of toplevel-shell, shell and widget. You rarely define subclasses of this class. GINA does not define subclasses of this class. You can create an instance of this class.

Callbacks:

popup-callback  ()

Local Slots:

basic-document-shell: document the document the shell belongs to x-window the window to send messages to

Default: nil

\underline{shell:} title title string views all views within the shell

Default: nil

document the document belonging to the shell, or nil

Default: nil

drag-protocols a list of keywords of accepted drag-commands

Default: nil

\underline{widget:} widget-id integer returned by CLM create-widget call group-widget-id id used when the whole group is meant widget-id-for-sons may be different from widget-id in compound widgets parent the parent widget object in the hierarchy name name string for resource database lookup width total width in pixels height total height in pixels x-pos the x-coordinate relative to the parent y-pos the y-coordinate relative to the parent

Methods of class basic-document-shell:

[o ] closed-by-wm ((shell basic-document-shell))  (Page 142)

closing a document shell means closing its document

[  ] destroy :before ((shell basic-document-shell))  (Page 141)

update list of toplevel-shells of the document

Methods of superclasses:

[o ] closed-by-wm ((shell toplevel-shell))  (Page 132)

shell is being closed by the window manager

[ c] destroy ((shell toplevel-shell))  (Page 132)

destroy the shell and all its children

[  ] enclosing-shell ((shell shell))  (Page 129)

override to return shell itself

[ c] expose ((shell toplevel-shell))  (Page 132)

bring window to front and set input focus

[o ] handle-button-press ((shell shell) &rest event-data)  (Page 128)

low level event handler for button-press events

[ c] pop-down ((shell shell))  (Page 129)

popdown the underlying widget

[  ] pop-up :after ((shell toplevel-shell))  (Page 131)

register shell at the application

[ c] pop-up ((shell shell))  (Page 128)

popup the underlying widget

[o ] resized-by-user ((shell toplevel-shell))  (Page 131)

hook for reaction to user resizing the shell

11.7.1 make-basic-document-shell Function

Purpose: create a new toplevel-shell for a document without a menubar.

(defun make-basic-document-shell (document &key (width :auto) (height :auto)
                                  (title (name *application*))
                                  (allow-shell-resize nil)
                                  (drag-protocols (drag-protocols document))
                                  (class 'basic-document-shell) (initargs nil)
                                  (motif-widget-class :toplevel-shell)
                                  (name class) (motif-resources nil)))

document: the document object width: :auto or fixed width height: :auto or fixed height title: title string allow-shell-resize: whether resizable by changing children drag-protocols: keyword list of accepted drag-commands

This is the constructor function for class basic-document-shell. The returned value is a newly created object of class basic-document-shell. You can call this function. It is sometimes called by GINA.

11.7.2 destroy :before Method

Purpose: update list of toplevel-shells of the document.

(defmethod destroy :before ((shell basic-document-shell)))

Deamon installed by GINA.

[ c] destroy ((shell toplevel-shell))  (Page 132)

destroy the shell and all its children

[ c] destroy ((w widget))  (Page 121)

destroy the widget objects and all its sons

11.7.3 closed-by-wm Method

Purpose: closing a document shell means closing its document.

(defmethod closed-by-wm ((shell basic-document-shell)))

You can override this method. The default version closes the document. Normally, you do not call this method. It is called by GINA when appropriate. It is never overridden by GINA.

Related methods:

[  ] closed-by-wm ((shell modal-dialog-shell))  (Page 138)

modal-dialog-shells cannot be closed by the window manager

[o ] closed-by-wm ((shell toplevel-shell))  (Page 132)

shell is being closed by the window manager

[o ] closed-by-wm ((box dialog-box))  (Page 202)

dialog-box is being closed by the window manager

11.8 document-shell Class

An instance of class document-shell is a toplevel-shell with a main-menu, representing a document. It is a subclass of basic-document-shell, toplevel-shell, shell and widget. You define a subclass of this class for application-specific main windows. GINA defines subclasses of this class. You can create an instance of this class.

Callbacks:

popup-callback  ()

Local Slots:

document-shell: main-window automatically created main window main-menu automatically created menu with default entries basic-document-shell: document the document the shell belongs to x-window the window to send messages to

Default: nil

\underline{shell:} title title string views all views within the shell

Default: nil

document the document belonging to the shell, or nil

Default: nil

drag-protocols a list of keywords of accepted drag-commands

Default: nil

\underline{widget:} widget-id integer returned by CLM create-widget call group-widget-id id used when the whole group is meant widget-id-for-sons may be different from widget-id in compound widgets parent the parent widget object in the hierarchy name name string for resource database lookup width total width in pixels height total height in pixels x-pos the x-coordinate relative to the parent y-pos the y-coordinate relative to the parent

Methods of class document-shell:

[o ] standard-menu-items ((document document) (shell document-shell))  (Page 29)

create the standard menu entries for this document

Methods of superclasses:

[o ] closed-by-wm ((shell basic-document-shell))  (Page 142)

closing a document shell means closing its document

[o ] closed-by-wm ((shell toplevel-shell))  (Page 132)

shell is being closed by the window manager

[  ] destroy :before ((shell basic-document-shell))  (Page 141)

update list of toplevel-shells of the document

[ c] destroy ((shell toplevel-shell))  (Page 132)

destroy the shell and all its children

[  ] enclosing-shell ((shell shell))  (Page 129)

override to return shell itself

[ c] expose ((shell toplevel-shell))  (Page 132)

bring window to front and set input focus

[o ] handle-button-press ((shell shell) &rest event-data)  (Page 128)

low level event handler for button-press events

[ c] pop-down ((shell shell))  (Page 129)

popdown the underlying widget

[  ] pop-up :after ((shell toplevel-shell))  (Page 131)

register shell at the application

[ c] pop-up ((shell shell))  (Page 128)

popup the underlying widget

[o ] resized-by-user ((shell toplevel-shell))  (Page 131)

hook for reaction to user resizing the shell

11.8.1 make-document-shell Function

Purpose: create toplevel-shell with a menu-bar, representing a document.

(defun make-document-shell (document &key (width :auto) (height :auto)
                            (is-main-shell t) (with-menu t)
                            (allow-shell-resize nil)
                            (drag-protocols (drag-protocols document))
                            (class 'document-shell) (initargs nil)
                            (motif-widget-class :toplevel-shell) (name class)
                            (motif-resources nil)))

document: the document object width: :auto or fixed width height: :auto or fixed height is-main-shell: whether register as main shell of document with-menu: whether create the standard menu bar allow-shell-resize: whether resizable by changing children drag-protocols: keyword list of accepted drag-commands

This is the constructor function for class document-shell. The returned value is a newly created object of class document-shell. You can call this function. It is sometimes called by GINA.

11.9 document-shell-with-scroller Class

An instance of class document-shell-with-scroller is a document-shell with a single scroller. It is a subclass of document-shell, basic-document-shell, toplevel-shell, shell and widget. You rarely define subclasses of this class. GINA does not define subclasses of this class. You can create an instance of this class.

Callbacks:

popup-callback  ()

Local Slots:

document-shell-with-scroller: scroller automatically created scroller as main window child document-shell: main-window automatically created main window main-menu automatically created menu with default entries basic-document-shell: document the document the shell belongs to x-window the window to send messages to

Default: nil

\underline{shell:} title title string views all views within the shell

Default: nil

document the document belonging to the shell, or nil

Default: nil

drag-protocols a list of keywords of accepted drag-commands

Default: nil

\underline{widget:} widget-id integer returned by CLM create-widget call group-widget-id id used when the whole group is meant widget-id-for-sons may be different from widget-id in compound widgets parent the parent widget object in the hierarchy name name string for resource database lookup width total width in pixels height total height in pixels x-pos the x-coordinate relative to the parent y-pos the y-coordinate relative to the parent

Methods of superclasses:

[o ] closed-by-wm ((shell basic-document-shell))  (Page 142)

closing a document shell means closing its document

[o ] closed-by-wm ((shell toplevel-shell))  (Page 132)

shell is being closed by the window manager

[  ] destroy :before ((shell basic-document-shell))  (Page 141)

update list of toplevel-shells of the document

[ c] destroy ((shell toplevel-shell))  (Page 132)

destroy the shell and all its children

[  ] enclosing-shell ((shell shell))  (Page 129)

override to return shell itself

[ c] expose ((shell toplevel-shell))  (Page 132)

bring window to front and set input focus

[o ] handle-button-press ((shell shell) &rest event-data)  (Page 128)

low level event handler for button-press events

[ c] pop-down ((shell shell))  (Page 129)

popdown the underlying widget

[  ] pop-up :after ((shell toplevel-shell))  (Page 131)

register shell at the application

[ c] pop-up ((shell shell))  (Page 128)

popup the underlying widget

[o ] resized-by-user ((shell toplevel-shell))  (Page 131)

hook for reaction to user resizing the shell

[o ] standard-menu-items ((document document) (shell document-shell))  (Page 29)

create the standard menu entries for this document

11.9.1 make-document-shell-with-scroller Function

Purpose: create a new document-shell with a single scroller.

(defun make-document-shell-with-scroller (document
                                          &key
                                          (width :auto)
                                          (height :auto)
                                          (allow-shell-resize nil)
                                          (drag-protocols
                                            (drag-protocols document))
                                          (class 'document-shell-with-scroller)
                                          (initargs nil)
                                          (motif-widget-class :toplevel-shell)
                                          (name class)
                                          (motif-resources nil)))

document: the document object width: :auto or fixed width height: :auto or fixed height allow-shell-resize: whether resizable by changing children drag-protocols: keyword list of accepted drag-commands

This is the constructor function for class document-shell-with-scroller. The returned value is a newly created object of class document-shell-with-scroller. You can call this function. It is sometimes called by GINA.

11.10 label Class

The class label is the Motif label widget. It is a subclass of widget. You rarely define subclasses of this class. GINA defines subclasses of this class. You can create an instance of this class.

Local Slots:

Resource slots:

\underline{label:} label-string the string shown label-type either :string or :pixmap \underline{widget:} widget-id integer returned by CLM create-widget call group-widget-id id used when the whole group is meant widget-id-for-sons may be different from widget-id in compound widgets parent the parent widget object in the hierarchy name name string for resource database lookup width total width in pixels height total height in pixels x-pos the x-coordinate relative to the parent y-pos the y-coordinate relative to the parent label-type label-string

11.10.1 make-label Function

Purpose: create a new label widget.

(defun make-label (parent label-string &key (alignment :center)
                   (recompute-size t) (label-type :string) (sensitive t)
                   (class 'label) (initargs nil) (motif-widget-class :label)
                   (name class) (managed t) (motif-resources nil)))

parent: the parent widget label-string: the label string alignment: :center :end :beginning recompute-size: whether request new size if label string changed label-type: if :pixmap, label-string is regarded as filename

This is the constructor function for class label. The returned value is a newly created object of class label. You can call this function. It is sometimes called by GINA.

11.11 drag-label Class

An instance of class drag-label is a picture label for drag and drop. It is a subclass of label and widget. You rarely define subclasses of this class. GINA does not define subclasses of this class. You can create an instance of this class.

Callbacks:

activate-callback  (x y)

Local Slots:

\underline{drag-label:} drag-shell a shell with duplicate image to move around cursor a cursor created from the label pixmap

Default: :dotbox

\underline{label:} label-string the string shown label-type either :string or :pixmap \underline{widget:} widget-id integer returned by CLM create-widget call group-widget-id id used when the whole group is meant widget-id-for-sons may be different from widget-id in compound widgets parent the parent widget object in the hierarchy name name string for resource database lookup width total width in pixels height total height in pixels x-pos the x-coordinate relative to the parent y-pos the y-coordinate relative to the parent

11.11.1 make-drag-label Function

Purpose: create a new drag label.

(defun make-drag-label (parent document pixmap &key (cursor-mask nil)
                        (activate-callback nil) (sensitive t)
                        (class 'drag-label) (initargs nil)
                        (motif-widget-class :label) (name class) (managed t)
                        (motif-resources nil)
                        (shell-resources '(:border-width 1))))

document: the document to register commands with pixmap: name of a bitmap file cursor-mask: a bitmap file as cursor mask, or nil activate-callback: a callback that creates a drag-command

This is the constructor function for class drag-label. The returned value is a newly created object of class drag-label. You can call this function. It is sometimes called by GINA.

11.12 toggle-button Class

The class toggle-button is the Motif toggle button widget. It is a subclass of label and widget. You rarely define subclasses of this class. GINA does not define subclasses of this class. You can create an instance of this class.

Callbacks:

value-changed-callback (value)
arm-callback  (value)
disarm-callback  (value)

toggle-button: value whether currently selected or not \underline{label:} label-string the string shown label-type either :string or :pixmap \underline{widget:} widget-id integer returned by CLM create-widget call group-widget-id id used when the whole group is meant widget-id-for-sons may be different from widget-id in compound widgets parent the parent widget object in the hierarchy name name string for resource database lookup width total width in pixels height total height in pixels x-pos the x-coordinate relative to the parent y-pos the y-coordinate relative to the parent

Resource slots:

value (corresponds to Motif-resource :set)

Methods of class toggle-button:

[o ] execute-value-changed-callback ((button toggle-button) set &optional ignore1 ignore2)  (Page 150)

semantics of a users mouse click into the toggle-button

11.12.1 make-toggle-button Function

Purpose: make a new toggle-button widget.

(defun make-toggle-button (parent string &key (indicator-type :n-of-many)
                           (label-type :string)
                           (indicator-on (eq label-type :string)) (value nil)
                           (value-changed-callback :call-method) (spacing 4)
                           (recompute-size t) (sensitive t)
                           (class 'toggle-button) (initargs nil)
                           (motif-widget-class :toggle-button) (name class)
                           (managed t) (motif-resources nil)))

parent: the parent widget string: the label-string indicator-type: :n-of-many or :one-of-many label-type: if :pixmap, label-string is regarded as filename indicator-on: if display toggle indicator value: initial value

value-changed-callback::call-method or a callback

spacing: between toggle and label recompute-size: whether request new size if label-string changed

This is the constructor function for class toggle-button. The returned value is a newly created object of class toggle-button. You can call this function. It is sometimes called by GINA.

11.12.2 execute-value-changed-callback Method

Purpose: semantics of a users mouse click into the toggle-button.

(defmethod execute-value-changed-callback ((button toggle-button) set &optional
ignore1 ignore2))

set: state of toggle

You override this method in application-specific subclasses. The default version does not do anything. Normally, you do not call this method. It is called by GINA when appropriate. It is never overridden by GINA. This method is only called if :call-method is specified on creation.

Related methods:

[o ] execute-value-changed-callback ((option-menu option-menu) new-value &optional old-value ignore) (Page 174)

reaction when a new option is selected by the user

[o ] execute-value-changed-callback ((scrollbar scrollbar) new-value &optional ignore1 ignore2)  (Page 158)

semantics of a users modification of the current value

[o ] execute-value-changed-callback ((scale scale) new-value &optional ignore1 ignore2) (Page 156)

semantics of a users modification of the current value

[o ] execute-value-changed-callback ((group toggle-button-group) new-value &optional toggled-value set)  (Page 187)

reaction when a button is toggled by the user

11.13 push-button Class

The class push-button is the Motif push button widget. It is a subclass of label and widget. You rarely define subclasses of this class. GINA does not define subclasses of this class. You can create an instance of this class.

activate-callback  ()
arm-callback  ()
disarm-callback  ()

Local Slots:

\underline{label:} label-string the string shown label-type either :string or :pixmap \underline{widget:} widget-id integer returned by CLM create-widget call group-widget-id id used when the whole group is meant widget-id-for-sons may be different from widget-id in compound widgets parent the parent widget object in the hierarchy name name string for resource database lookup width total width in pixels height total height in pixels x-pos the x-coordinate relative to the parent y-pos the y-coordinate relative to the parent

Methods of class push-button:

[o ] execute-activate-callback ((pb push-button))  (Page 152)

semantics of a users mouse click into the push-button

11.13.1 make-push-button Function

Purpose: make a new push-button widget.

(defun make-push-button (parent string &key (show-as-default 0)
                         (label-type :string) (activate-callback :call-method)
                         (alignment :center) (recompute-size t) (sensitive t)
                         (class 'push-button) (initargs nil)
                         (motif-widget-class :push-button) (name class)
                         (managed t) (motif-resources nil)))

parent: the parent widget string: the label-string show-as-default: size of frame for default buttons label-type: if :pixmap, label-string is regarded as filename activate-callback: :call-method or a callback alignment: :center :end :beginning recompute-size: whether request new size if label-string changed

This is the constructor function for class push-button. The returned value is a newly created object of class push-button.

You can call this function. It is sometimes called by GINA.

11.13.2 execute-activate-callback Method

Purpose: semantics of a users mouse click into the push-button.

(defmethod execute-activate-callback ((pb push-button)))

You override this method in application-specific subclasses. The default version does not do anything. Normally, you do not call this method. It is called by GINA when appropriate. It is never overridden by GINA. This method is only called if :call-method is specified on creation.

Related methods:

[o ] execute-activate-callback ((button dialog-dismiss-button))  (Page 212)

store result in dialog box

[o ] execute-activate-callback ((ab arrow-button))  (Page 154)

semantics of a users mouse click into the arrow-button

11.14 cascade-button Class

The class cascade-button is the Motif cascade button widget. It is a subclass of label and widget. You rarely define subclasses of this class. GINA does not define subclasses of this class. You can create an instance of this class.

Callbacks:

activate-callback  ()
cascading-callback  ()

Local Slots:

\underline{label:} label-string the string shown label-type either :string or :pixmap \underline{widget:} widget-id integer returned by CLM create-widget call group-widget-id id used when the whole group is meant widget-id-for-sons may be different from widget-id in compound widgets parent the parent widget object in the hierarchy name name string for resource database lookup width total width in pixels height total height in pixels x-pos the x-coordinate relative to the parent y-pos the y-coordinate relative to the parent

11.14.1 make-cascade-button Function

Purpose: make a new cascade-button widget.

(defun make-cascade-button (parent string submenu &key (label-type :string)
                            (sensitive t) (class 'cascade-button)
                            (initargs nil) (motif-widget-class :cascade-button)
                            (name class) (managed t) (motif-resources nil)))

parent: the parent widget string: the label string submenu: the pull-down submenu label-type: if :pixmap, label-string is regarded as filename

This is the constructor function for class cascade-button. The returned value is a newly created object of class cascade-button. You can call this function. It is sometimes called by GINA.

11.15 arrow-button Class

The class arrow-button is the Motif arrow button widget. It is a subclass of widget. You rarely define subclasses of this class. GINA does not define subclasses of this class. You can create an instance of this class.

Callbacks:

activate-callback  ()
arm-callback  ()
disarm-callback  ()

Local Slots:

\underline{widget:} widget-id integer returned by CLM create-widget call group-widget-id id used when the whole group is meant widget-id-for-sons may be different from widget-id in compound widgets parent the parent widget object in the hierarchy name name string for resource database lookup width total width in pixels height total height in pixels x-pos the x-coordinate relative to the parent y-pos the y-coordinate relative to the parent

Methods of class arrow-button:

[o ] execute-activate-callback ((ab arrow-button))  (Page 154)

semantics of a users mouse click into the arrow-button

11.15.1 make-arrow-button Function

Purpose: make a new arrow-button widget.

(defun make-arrow-button (parent &key (arrow-direction :arrow-up)
                          (activate-callback :call-method) (sensitive t)
                          (class 'arrow-button) (initargs nil)
                          (motif-widget-class :arrow-button) (name class)
                          (managed t) (motif-resources nil)))

parent: the parent widget arrow-direction: :arrow-up, :arrow-down, :arrow-left, :arrow-right activate-callback: :call-method or a callback

This is the constructor function for class arrow-button. The returned value is a newly created object of class arrow-button. You can call this function. It is sometimes called by GINA.

11.15.2 execute-activate-callback Method

Purpose: semantics of a users mouse click into the arrow-button.

(defmethod execute-activate-callback ((ab arrow-button)))

You override this method in application-specific subclasses. The default version does not do anything. Normally, you do not call this method. It is called by GINA when appropriate. It is never overridden by GINA. This method is only called if :call-method is specified on creation.

[o ] execute-activate-callback ((button dialog-dismiss-button))  (Page 212)

store result in dialog box

[o ] execute-activate-callback ((pb push-button))  (Page 152)

semantics of a users mouse click into the push-button

11.16 scale Class

The class scale is the Motif scale widget. It is a subclass of widget. You rarely define subclasses of this class. GINA does not define subclasses of this class. You can create an instance of this class.

Callbacks:

value-changed-callback (new-value)
drag-callback  (new-value)

Local Slots:

\underline{scale:} value current value between min and max maximum maximum value minimum minimum value \underline{widget:} widget-id integer returned by CLM create-widget call group-widget-id id used when the whole group is meant widget-id-for-sons may be different from widget-id in compound widgets parent the parent widget object in the hierarchy name name string for resource database lookup width total width in pixels height total height in pixels x-pos the x-coordinate relative to the parent y-pos the y-coordinate relative to the parent

Resource slots:

value

Methods of class scale:

[o ] execute-value-changed-callback ((scale scale) new-value &optional ignore1 ignore2) (Page 156)

semantics of a users modification of the current value

11.16.1 make-scale Function

Purpose: make a new scale widget.

(defun make-scale (parent &key (orientation :vertical)
                   (processing-direction
                    (if (eq orientation :vertical) :max-on-top :max-on-right))
                   (title-string "") (minimum 0) (maximum 100) (value 0)
                   (value-changed-callback :call-method) (show-value t)
                   (sensitive t) (class 'scale) (initargs nil)
                   (motif-widget-class :scale) (name class) (managed t)
                   (motif-resources nil)))

parent: the parent widget orientation: :vertical or :horizontal processing-direction: :max-on-top :max-on-right :max-on-top :max-on-bottom title-string: identifying label minimum: minimum value maximum: maximum value value: initial value

value-changed-callback::call-method or a callback

show-value: whether current value is displayed as a number

This is the constructor function for class scale. The returned value is a newly created object of class scale. You can call this function. It is sometimes called by GINA.

11.16.2 execute-value-changed-callback Method

Purpose: semantics of a users modification of the current value.

(defmethod execute-value-changed-callback ((scale scale) new-value &optional
ignore1 ignore2))

You override this method in application-specific subclasses. The default version does not do anything. Normally, you do not call this method. It is called by GINA when appropriate. It is never overridden by GINA. This method is only called if :call-method is specified on creation.

Related methods:

[o ] execute-value-changed-callback ((option-menu option-menu) new-value &optional old-value ignore) (Page 174)

reaction when a new option is selected by the user

[o ] execute-value-changed-callback ((button toggle-button) set &optional ignore1 ignore2)  (Page 150)

semantics of a users mouse click into the toggle-button

[o ] execute-value-changed-callback ((scrollbar scrollbar) new-value &optional ignore1 ignore2)  (Page 158)

semantics of a users modification of the current value

[o ] execute-value-changed-callback ((group toggle-button-group) new-value &optional toggled-value set)  (Page 187)

reaction when a button is toggled by the user

11.17 scrollbar Class

The class scrollbar is the Motif scroll bar widget. It is a subclass of widget. You rarely define subclasses of this class. GINA does not define subclasses of this class. You can create an instance of this class.

Callbacks:

value-changed-callback (new-value)
drag-callback  (new-value)
decrement-callback  (new-value)
increment-callback  (new-value)
page-decrement-callback(new-value)
page-increment-callback(new-value)

to-bottom-callback (new-value button-press-pos) to-top-callback (new-value button-press-pos)

Local Slots:

\underline{scrollbar:} value current value between min and max maximum maximum value in application-defined units minimum minimum value in application-defined units increment single-step increment in application-defined units page-increment page-step increment in application-defined units slider-size slider size in application-defined units \underline{widget:} widget-id integer returned by CLM create-widget call group-widget-id id used when the whole group is meant widget-id-for-sons may be different from widget-id in compound widgets parent the parent widget object in the hierarchy name name string for resource database lookup width total width in pixels height total height in pixels x-pos the x-coordinate relative to the parent y-pos the y-coordinate relative to the parent slider-size page-increment increment minimum maximum value

Methods of class scrollbar:

[o ] execute-value-changed-callback ((scrollbar scrollbar) new-value &optional ignore1 ignore2)  (Page 158)

semantics of a users modification of the current value

11.17.1 make-scrollbar Function

Purpose: make a new scrollbar widget.

(defun make-scrollbar (parent &key (orientation :vertical) (minimum 0)
                       (maximum 100) (value 0) (increment 1)
                       (page-increment 10) (slider-size 10)
                       (value-changed-callback :call-method) (class 'scrollbar)
                       (initargs nil) (motif-widget-class :scroll-bar)
                       (name class) (managed t) (motif-resources nil)))

parent: the parent widget orientation: :vertical or :horizontal minimum: initial minimum maximum: initial maximum value: initial value increment: initial increment page-increment: initial page-increment slider-size: initial slider-size

value-changed-callback::call-method or a callback

This is the constructor function for class scrollbar. The returned value is a newly created object of class scrollbar. You can call this function. It is sometimes called by GINA.

11.17.2 execute-value-changed-callback Method

Purpose: semantics of a users modification of the current value.

(defmethod execute-value-changed-callback ((scrollbar scrollbar) new-value
&optional ignore1 ignore2))

You override this method in application-specific subclasses. The default version does not do anything. Normally, you do not call this method. It is called by GINA when appropriate. It is never overridden by GINA. This method is only called if :call-method is specified on creation.

[o ] execute-value-changed-callback ((option-menu option-menu) new-value &optional old-value ignore) (Page 174)

reaction when a new option is selected by the user

[o ] execute-value-changed-callback ((button toggle-button) set &optional ignore1 ignore2)  (Page 150)

semantics of a users mouse click into the toggle-button

[o ] execute-value-changed-callback ((scale scale) new-value &optional ignore1 ignore2) (Page 156)

semantics of a users modification of the current value

[o ] execute-value-changed-callback ((group toggle-button-group) new-value &optional toggled-value set)  (Page 187)

reaction when a button is toggled by the user

11.18 main-menu Class

An instance of class main-menu is a menu-bar plus its popup shells. It is a subclass of menu-bar and widget. You rarely define subclasses of this class. GINA does not define subclasses of this class. You can create an instance of this class.

Local Slots:

\underline{widget:} widget-id integer returned by CLM create-widget call group-widget-id id used when the whole group is meant widget-id-for-sons may be different from widget-id in compound widgets parent the parent widget object in the hierarchy name name string for resource database lookup width total width in pixels height total height in pixels x-pos the x-coordinate relative to the parent y-pos the y-coordinate relative to the parent

Methods of class main-menu:

[ c] add-menu-command ((menu main-menu) topic item-name callback &key (separator-before nil) (accelerator nil) (acc-modifier :alt))  (Page 161)

add a button menu entry

[ c] find-menu-entry ((menu main-menu) topic-name item-name)  (Page 161)

find the entry corresponding to the named item

[ c] insert-menu-entry ((menu main-menu) topic-name item-name entry &key (before :end)) (Page 160)

create a menu entry under the named topic

[ c] remove-menu-entry ((menu main-menu) topic-name item-name)  (Page 161)

remove the menu entry

11.18.1 make-main-menu Function

Purpose: create a new main-menu widget.

(defun make-main-menu (parent &key (class 'main-menu) (initargs nil)
                       (motif-widget-class :row-column) (name class)
                       (managed t) (motif-resources nil)))

parent: the parent widget

This is the constructor function for class main-menu. The returned value is a newly created object of class main-menu. You can call this function. It is sometimes called by GINA.

11.18.2 insert-menu-entry Method

Purpose: create a menu entry under the named topic.

(defmethod insert-menu-entry ((menu main-menu) topic-name item-name entry &key
(before :end)))

topic-name: identifying string and menu title item-name: identifying string for the entry entry: object of a subclass of entry before: :end or the name of another entry

You rarely override this method or add deamons. The default version is sufficient for most cases. You can call this method to add an entry to a menu. It is called by GINA when appropriate. It is never overridden by GINA.

Example

(with-application-stopped
  (insert-menu-entry
    (main-menu (main-shell (first (document-list *application*))))
    "Edit"
    "Clear"
    (make-toggle-entry "Clear Nil" nil)
    :before
    "Undo"))

inserts an entry in the Edit menu before the Undo entry the entry is a toggle button showing ”Clear Nil” and an empty callback the entry can later be referenced by the two keys ”Edit” and ”Clear”

11.18.3 remove-menu-entry Method

Purpose: remove the menu entry.

(defmethod remove-menu-entry ((menu main-menu) topic-name item-name))

topic-name: string identifying topic item-name: string identifying entry

The returned value is the removed entry object. You rarely override this method or add deamons. The default version is sufficient for most cases. You can call this method to remove a standard menu entry. It is called by GINA when appropriate. It is never overridden by GINA.

11.18.4 find-menu-entry Method

Purpose: find the entry corresponding to the named item.

(defmethod find-menu-entry ((menu main-menu) topic-name item-name))

topic-name: string identifying topic item-name: string identifying entry

The returned value is the entry object identified by topic and item, or nil. You rarely override this method or add deamons. The default version is sufficient for most cases. You can call this method to find the entry object. It is called by GINA when appropriate. It is never overridden by GINA.

11.18.5 add-menu-command Method

Purpose: add a button menu entry.

(defmethod add-menu-command ((menu main-menu) topic item-name callback &key
(separator-before nil) (accelerator nil) (acc-modifier :alt)))

topic: string identifying topic item-name: string identifying entry callback: the callback activated by the entry You rarely override this method or add deamons. The default version is sufficient for most cases. You can call this method to add a simple menu entry. It is called by GINA when appropriate. It is never overridden by GINA. This method is a convenience interface to insert a button entry

11.19 menu-entry Class

The class menu-entry is the parent class for menu entries. You rarely define subclasses of this class. GINA defines subclasses of this class. You never create an instance of this class.

Local Slots:

sensitive the sensitivity flag

Default: t

separator-before whether create a separating line before this entry callback the callback associated with the entry

Methods of class menu-entry:

[  ] (setf sensitive) :after (new-value (entry menu-entry))  (Page 162)

set sensitivity of entry if widget exists

11.19.1 (setf sensitive) :after Method

Purpose: set sensitivity of entry if widget exists.

(defmethod (setf sensitive) :after (new-value (entry menu-entry)))

Deamon installed by GINA.

11.20 button-entry Class

An instance of class button-entry is a button entry in menus. It is a subclass of menu-entry. You rarely define subclasses of this class. GINA defines subclasses of this class. You can create an instance of this class.

callback  ()

Local Slots:

button-entry: label-string the label string shown accelerator a string denoting an accelerator key, e.g. ”F5” acc-modifier modifier, one of :alt :shift :ctrl menu-entry: sensitive the sensitivity flag

Default: t

separator-before whether create a separating line before this entry callback the callback associated with the entry

Methods of class button-entry:

[  ] (setf acc-modifier) :after (new-value (entry button-entry))  (Page 164)

propagate new modifier to widget

[  ] (setf accelerator) :after (new-value (entry button-entry))  (Page 164)

propagate new accelerator to widget

[  ] (setf label-string) :after (new-value (entry button-entry))  (Page 164)

propagate label string to widget

Methods of superclasses:

[  ] (setf sensitive) :after (new-value (entry menu-entry))  (Page 162)

set sensitivity of entry if widget exists

11.20.1 make-button-entry Function

Purpose: create a button entry instance.

(defun make-button-entry (string callback &key (separator-before nil)
                          (accelerator nil) (acc-modifier :alt)))

string: initial label string callback: to be activated by the entry

This is the constructor function for class button-entry. The returned value is a newly created object of class button-entry. You can call this function. It is sometimes called by GINA.

11.20.2 (setf label-string) :after Method

Purpose: propagate label string to widget.

(defmethod (setf label-string) :after (new-value (entry button-entry)))

Deamon installed by GINA.

11.20.3 (setf accelerator) :after Method

Purpose: propagate new accelerator to widget.

(defmethod (setf accelerator) :after (new-value (entry button-entry)))

Deamon installed by GINA.

11.20.4 (setf acc-modifier) :after Method

Purpose: propagate new modifier to widget.

(defmethod (setf acc-modifier) :after (new-value (entry button-entry)))

Deamon installed by GINA.

11.21 toggle-entry Class

An instance of class toggle-entry is a toggle button entry in menus. It is a subclass of button-entry and menu-entry. You rarely define subclasses of this class. GINA does not define subclasses of this class. You can create an instance of this class.

Callbacks:

callback  (value)

Local Slots:

toggle-entry: value the current toggle value button-entry: label-string the label string shown accelerator a string denoting an accelerator key, e.g. ”F5” acc-modifier modifier, one of :alt :shift :ctrl menu-entry: sensitive the sensitivity flag

Default: t

separator-before whether create a separating line before this entry callback the callback associated with the entry

Methods of class toggle-entry:

[  ] (setf value) :after (new-value (entry toggle-entry))  (Page 165)

propagate value changes to the widget

Methods of superclasses:

[  ] (setf acc-modifier) :after (new-value (entry button-entry))  (Page 164)

propagate new modifier to widget

[  ] (setf accelerator) :after (new-value (entry button-entry))  (Page 164)

propagate new accelerator to widget

[  ] (setf label-string) :after (new-value (entry button-entry))  (Page 164)

propagate label string to widget

[  ] (setf sensitive) :after (new-value (entry menu-entry))  (Page 162)

set sensitivity of entry if widget exists

11.21.1 make-toggle-entry Function

Purpose: create a toggle button entry instance.

(defun make-toggle-entry (string callback &key (value nil)
                          (separator-before nil) (accelerator nil)
                          (acc-modifier :alt)))

string: initial label string callback: to be activated by the entry value: initial value

This is the constructor function for class toggle-entry. The returned value is a newly created object of class toggle-entry. You can call this function. It is sometimes called by GINA.

11.21.2 (setf value) :after Method

Purpose: propagate value changes to the widget.

(defmethod (setf value) :after (new-value (entry toggle-entry)))

Deamon installed by GINA.

[  ] (setf value) :after (new-value (selection-list selection-list))  (Page 191)

the application has changed the selected value

[  ] (setf value) :after (new-value (option-menu option-menu))  (Page 175)

the value is changed by the application program, not the user

[  ] (setf value) :before (new-value (group toggle-button-group))  (Page 186)

the application has changed the selected values

[  ] (setf value) :before (new-value (group toggle-group-entry))  (Page 168)

the application has changed the selected values

11.22 toggle-group-entry Class

An instance of class toggle-group-entry is a group of toggle buttons in a menu. It is a subclass of button-entry and menu-entry. You rarely define subclasses of this class. GINA defines subclasses of this class. You can create an instance of this class.

Callbacks:

callback (value toggled-value set)

Local Slots:

toggle-group-entry: is-submenu whether use a submenu or expand in place item-list list of strings or (string value) pairs initial-value initial string or value button-resources motif-resources for buttons button-label-type label-type for buttons value a subset of value-list

Default: nil

value-list list of values extracted from item list button-entry: label-string the label string shown accelerator a string denoting an accelerator key, e.g. ”F5” acc-modifier modifier, one of :alt :shift :ctrl menu-entry: sensitive the sensitivity flag

Default: t

separator-before whether create a separating line before this entry callback the callback associated with the entry

Methods of class toggle-group-entry:

[ c] set-item-list ((group toggle-group-entry) new-item-list &key (selected-value nil))  (Page 168)

the item-list has changed

[  ] (setf value) :before (new-value (group toggle-group-entry))  (Page 168)

the application has changed the selected values

Methods of superclasses:

[  ] (setf acc-modifier) :after (new-value (entry button-entry))  (Page 164)

propagate new modifier to widget

[  ] (setf accelerator) :after (new-value (entry button-entry))  (Page 164)

propagate new accelerator to widget

[  ] (setf label-string) :after (new-value (entry button-entry))  (Page 164)

propagate label string to widget

[  ] (setf sensitive) :after (new-value (entry menu-entry))  (Page 162)

set sensitivity of entry if widget exists

11.22.1 make-toggle-group-entry Function

Purpose: create a toggle group entry instance.

(defun make-toggle-group-entry (label-string item-list callback &key
                                (separator-before nil) (is-submenu t)
                                (initial-value nil) (button-label-type :string)
                                (button-resources nil)))

label-string: label-string if submenu item-list: list of strings or (string value) pairs callback: a value-changed callback is-submenu: whether use submenu or expand in place initial-value: a subset of value-list

button-label-type:  :string or :pixmap

button-resources: motif-resources for buttons

This is the constructor function for class toggle-group-entry. The returned value is a newly created object of class toggle-group-entry. You can call this function. It is sometimes called by GINA.

Example

(make-toggle-group-entry
  "Style"
  '(("Bold" :bold) ("Italic" :italic))
  (make-callback '(lambda (value toggled-value set) nil))
  :initial-value
  '(:bold))

11.22.2 (setf value) :before Method

Purpose: the application has changed the selected values.

(defmethod (setf value) :before (new-value (group toggle-group-entry)))

Deamon installed by GINA.

Related methods:

[  ] (setf value) :after (new-value (entry toggle-entry))  (Page 165)

propagate value changes to the widget

[  ] (setf value) :after (new-value (selection-list selection-list))  (Page 191)

the application has changed the selected value

[  ] (setf value) :after (new-value (option-menu option-menu))  (Page 175)

the value is changed by the application program, not the user

[  ] (setf value) :before (new-value (group toggle-button-group))  (Page 186)

the application has changed the selected values

11.22.3 set-item-list Method

Purpose: the item-list has changed.

(defmethod set-item-list ((group toggle-group-entry) new-item-list &key
(selected-value nil)))

new-item-list: list of strings or (string value) pairs selected-value: a subset of the values in the item list

You rarely override this method or add deamons. The default version is sufficient for most cases. You can call this method to change the item list of the menu entry. It is called by GINA when appropriate. It is never overridden by GINA.

Related methods:

[ c] set-item-list ((group radio-group-entry) new-item-list &key (selected-value :use-first))  (Page 170)

the item-list has changed

[ c] set-item-list ((selection-list selection-list) new-item-list &key (selected-value :use-first)) (Page 192)

the item-list has changed

[ c] set-item-list ((option-menu option-menu) new-item-list &key (selected-value :use-first))  (Page 173)

the item-list has changed

[ c] set-item-list ((group toggle-button-group) new-item-list &key (selected-value nil) (managed t))  (Page 186)

the item-list has changed

[ c] set-item-list ((group radio-button-group) new-item-list &key (selected-value :use-first) (managed t))  (Page 189)

the item-list has changed

11.23 radio-group-entry Class

An instance of class radio-group-entry is a radio button group in a menu. It is a subclass of toggle-group-entry, button-entry and menu-entry. You rarely define subclasses of this class. GINA does not define subclasses of this class. You can create an instance of this class.

Callbacks:

callback (value old-value)

Local Slots:

toggle-group-entry: is-submenu whether use a submenu or expand in place item-list list of strings or (string value) pairs initial-value initial string or value button-resources motif-resources for buttons button-label-type label-type for buttons value a subset of value-list

Default: nil

value-list list of values extracted from item list button-entry: label-string the label string shown accelerator a string denoting an accelerator key, e.g. ”F5” acc-modifier modifier, one of :alt :shift :ctrl menu-entry: sensitive the sensitivity flag

Default: t

separator-before whether create a separating line before this entry callback the callback associated with the entry

Methods of class radio-group-entry:

[ c] set-item-list ((group radio-group-entry) new-item-list &key (selected-value :use-first))  (Page 170)

the item-list has changed

Methods of superclasses:

[  ] (setf acc-modifier) :after (new-value (entry button-entry))  (Page 164)

propagate new modifier to widget

[  ] (setf accelerator) :after (new-value (entry button-entry))  (Page 164)

propagate new accelerator to widget

[  ] (setf label-string) :after (new-value (entry button-entry))  (Page 164)

propagate label string to widget

[  ] (setf sensitive) :after (new-value (entry menu-entry))  (Page 162)

set sensitivity of entry if widget exists

[ c] set-item-list ((group toggle-group-entry) new-item-list &key (selected-value nil))  (Page 168)

the item-list has changed

[  ] (setf value) :before (new-value (group toggle-group-entry))  (Page 168)

the application has changed the selected values

11.23.1 make-radio-group-entry Function

Purpose: create a toggle group entry instance.

(defun make-radio-group-entry (label-string item-list callback &key
                               (separator-before nil) (is-submenu t)
                               (initial-value :use-first)
                               (button-label-type :string)
                               (button-resources nil)))

label-string: label-string if submenu item-list: list of strings or (string value) pairs callback: a value-changed callback is-submenu: whether use submenu or expand in place initial-value: a value from value-list or :use-first

button-label-type:  :string or :pixmap

button-resources: motif-resources for buttons

This is the constructor function for class radio-group-entry. The returned value is a newly created object of class radio-group-entry. You can call this function. It is sometimes called by GINA.

Example

(make-radio-group-entry
  "Font"
  '(("Courier" :courier) ("Times" :times))
  (make-callback '(lambda (new-value old-value) nil))
  :initial-value
  :times)

11.23.2 set-item-list Method

Purpose: the item-list has changed.

(defmethod set-item-list ((group radio-group-entry) new-item-list &key
(selected-value :use-first)))

new-item-list: list of strings or (string value) pairs selected-value: a value from value-list or :use-first

You rarely override this method or add deamons. The default version is sufficient for most cases. You can call this method to change the item list of the menu entry. It is called by GINA when appropriate. It is never overridden by GINA.

Related methods:

[ c] set-item-list ((selection-list selection-list) new-item-list &key (selected-value :use-first)) (Page 192)

the item-list has changed

[ c] set-item-list ((group toggle-group-entry) new-item-list &key (selected-value nil))  (Page 168)

the item-list has changed

[ c] set-item-list ((option-menu option-menu) new-item-list &key (selected-value :use-first))  (Page 173)

the item-list has changed

[ c] set-item-list ((group toggle-button-group) new-item-list &key (selected-value nil) (managed t))  (Page 186)

the item-list has changed

[ c] set-item-list ((group radio-button-group) new-item-list &key (selected-value :use-first) (managed t))  (Page 189)

the item-list has changed

11.24 menu-bar Class

An instance of class menu-bar is a special kind of row-column widget. It is a subclass of widget. You rarely define subclasses of this class. GINA does not define subclasses of this class. You can create an instance of this class.

Local Slots:

\underline{widget:} widget-id integer returned by CLM create-widget call group-widget-id id used when the whole group is meant widget-id-for-sons may be different from widget-id in compound widgets parent the parent widget object in the hierarchy name name string for resource database lookup width total width in pixels height total height in pixels x-pos the x-coordinate relative to the parent y-pos the y-coordinate relative to the parent

11.24.1 make-menu-bar Function

Purpose: make a new MenuBar widget.

(defun make-menu-bar (parent &key (class 'menu-bar) (initargs nil)
                      (motif-widget-class :row-column) (name class) (managed t)
                      (motif-resources nil)))

parent: the parent widget

This is the constructor function for class menu-bar. The returned value is a newly created object of class menu-bar. You can call this function. It is sometimes called by GINA.

11.25 option-menu Class

The class option-menu is the Motif option menu widget. It is a subclass of widget. You rarely define subclasses of this class. GINA does not define subclasses of this class. You can create an instance of this class.

Callbacks:

value-changed-callback (value old-value)

Local Slots:

option-menu: value the current value from the value-list

Default: nil

value-list list of values extracted from the item list

Default: nil

option-shell the menu shell for the option menu pane button-box the option menu pane option-buttons the list of buttons in the pane

Default: nil

\underline{widget:} widget-id integer returned by CLM create-widget call group-widget-id id used when the whole group is meant widget-id-for-sons may be different from widget-id in compound widgets parent the parent widget object in the hierarchy name name string for resource database lookup width total width in pixels height total height in pixels x-pos the x-coordinate relative to the parent y-pos the y-coordinate relative to the parent

Methods of class option-menu:

[o ] execute-value-changed-callback ((option-menu option-menu) new-value &optional old-value ignore) (Page 174)

reaction when a new option is selected by the user

[ c] set-item-list ((option-menu option-menu) new-item-list &key (selected-value :use-first))  (Page 173)

the item-list has changed

[  ] (setf value) :after (new-value (option-menu option-menu))  (Page 175)

the value is changed by the application program, not the user

11.25.1 make-option-menu Function

Purpose: create a new option-menu.

(defun make-option-menu (parent item-list &key (label-string nil)
                         (value-changed-callback :call-method)
                         (initial-value :use-first) (class 'option-menu)
                         (initargs nil) (motif-widget-class :row-column)
                         (name class) (managed t) (motif-resources nil)))

parent: the parent widget item-list: a list of strings or (string value) pairs label-string: the label string on the left side

value-changed-callback::call-method or a callback

initial-value: a value from the value-list or :use-first

This is the constructor function for class option-menu. The returned value is a newly created object of class option-menu. You can call this function. It is sometimes called by GINA.

11.25.2 set-item-list Method

Purpose: the item-list has changed.

(defmethod set-item-list ((option-menu option-menu) new-item-list &key
(selected-value :use-first)))

new-item-list: a list of strings or (string value) pairs selected-value: a value from the value-list or :use-first

You rarely override this method or add deamons. The default version is sufficient for most cases. You can call this method to change the list of options. It is called by GINA when appropriate. It is never overridden by GINA.

[ c] set-item-list ((group radio-group-entry) new-item-list &key (selected-value :use-first))  (Page 170)

the item-list has changed

[ c] set-item-list ((selection-list selection-list) new-item-list &key (selected-value :use-first)) (Page 192)

the item-list has changed

[ c] set-item-list ((group toggle-group-entry) new-item-list &key (selected-value nil))  (Page 168)

the item-list has changed

[ c] set-item-list ((group toggle-button-group) new-item-list &key (selected-value nil) (managed t))  (Page 186)

the item-list has changed

[ c] set-item-list ((group radio-button-group) new-item-list &key (selected-value :use-first) (managed t))  (Page 189)

the item-list has changed

11.25.3 execute-value-changed-callback Method

Purpose: reaction when a new option is selected by the user.

(defmethod execute-value-changed-callback ((option-menu option-menu) new-value
&optional old-value ignore))

You override this method in application-specific subclasses. The default version does not do anything. Normally, you do not call this method. It is called by GINA when appropriate. It is never overridden by GINA.

Related methods:

[o ] execute-value-changed-callback ((button toggle-button) set &optional ignore1 ignore2)  (Page 150)

semantics of a users mouse click into the toggle-button

[o ] execute-value-changed-callback ((scrollbar scrollbar) new-value &optional ignore1 ignore2)  (Page 158)

semantics of a users modification of the current value

[o ] execute-value-changed-callback ((scale scale) new-value &optional ignore1 ignore2) (Page 156)

semantics of a users modification of the current value

[o ] execute-value-changed-callback ((group toggle-button-group) new-value &optional toggled-value set)  (Page 187)

reaction when a button is toggled by the user

11.25.4 (setf value) :after Method

Purpose: the value is changed by the application program, not the user.

(defmethod (setf value) :after (new-value (option-menu option-menu)))

Deamon installed by GINA.

Related methods:

[  ] (setf value) :after (new-value (entry toggle-entry))  (Page 165)

propagate value changes to the widget

[  ] (setf value) :after (new-value (selection-list selection-list))  (Page 191)

the application has changed the selected value

[  ] (setf value) :before (new-value (group toggle-button-group))  (Page 186)

the application has changed the selected values

[  ] (setf value) :before (new-value (group toggle-group-entry))  (Page 168)

the application has changed the selected values

11.26 menu-pulldown Class

The class menu-pulldown is the Motif row-column widget operating as a menu pane. It is a subclass of widget. You rarely define subclasses of this class. GINA does not define subclasses of this class. You can create an instance of this class.

Local Slots:

\underline{widget:} widget-id integer returned by CLM create-widget call group-widget-id id used when the whole group is meant widget-id-for-sons may be different from widget-id in compound widgets parent the parent widget object in the hierarchy name name string for resource database lookup width total width in pixels height total height in pixels x-pos the x-coordinate relative to the parent y-pos the y-coordinate relative to the parent

11.26.1 make-menu-pulldown Function

Purpose: make a new pull-down menu widget.

(defun make-menu-pulldown (parent &key (class 'menu-pulldown) (initargs nil)
                           (motif-widget-class :row-column) (name class)
                           (motif-resources nil)))

parent: the parent widget

This is the constructor function for class menu-pulldown. The returned value is a newly created object of class menu-pulldown. You can call this function. It is sometimes called by GINA.

11.27 main-window Class

The class main-window is the Motif main-window widget. It is a subclass of widget. You rarely define subclasses of this class. GINA does not define subclasses of this class. You can create an instance of this class.

Local Slots:

\underline{widget:} widget-id integer returned by CLM create-widget call group-widget-id id used when the whole group is meant widget-id-for-sons may be different from widget-id in compound widgets parent the parent widget object in the hierarchy name name string for resource database lookup width total width in pixels height total height in pixels x-pos the x-coordinate relative to the parent y-pos the y-coordinate relative to the parent

11.27.1 make-main-window Function

Purpose: make a new main-window widget.

(defun make-main-window (parent &key (class 'main-window) (initargs nil)
                         (motif-widget-class :main-window) (name class)
                         (managed t) (motif-resources nil)))

parent: the parent widget

This is the constructor function for class main-window. The returned value is a newly created object of class main-window. You can call this function. It is sometimes called by GINA.

11.28 scroller Class

The class scroller is the Motif scrolled-window widget. It is a subclass of widget. You rarely define subclasses of this class. GINA does not define subclasses of this class. You can create an instance of this class.

Local Slots:

\underline{scroller:} horizontal-scrollbar scroll bar object or nil (read-only)

Default: nil

vertical-scrollbar scroll bar object or nil (read-only)

Default: nil

work-area the work area child (read-only)

Default: nil

\underline{widget:} widget-id integer returned by CLM create-widget call group-widget-id id used when the whole group is meant widget-id-for-sons may be different from widget-id in compound widgets parent the parent widget object in the hierarchy name name string for resource database lookup width total width in pixels height total height in pixels x-pos the x-coordinate relative to the parent y-pos the y-coordinate relative to the parent

Methods of class scroller:

[  ] point-visible ((scroller scroller) x y &key (ask-for-work-area-pos t) (ask-for-clipper-size t)) (Page 179)

check whether the specified point is visible

[ c] scroll-to ((scroller scroller) x-offset y-offset &key (x-window-only nil))  (Page 178)

initiate scrolling from the application side

[  ] show-point ((scroller scroller) x y &key (ask-for-work-area-pos t) (ask-for-clipper-size t) (x-window-only nil) (force-scrolling nil)) (Page 179)

do minimal scrolling to make the specified point visible

[  ] son-created ((scroller scroller) son)  (Page 178)

in this case the scroller is informed that the work-area is created

11.28.1 make-scroller Function

Purpose: make a new scroller widget.

(defun make-scroller (parent &key (scrolling-policy :automatic)
                      (class 'scroller) (initargs nil)

                      (motif-widget-class :scrolled-window) (name class)
                      (managed t) (motif-resources nil)))

parent: the parent widget scrolling-policy: :automatic or :application-defined

This is the constructor function for class scroller. The returned value is a newly created object of class scroller. You can call this function. It is sometimes called by GINA.

11.28.2 son-created Method

Purpose: in this case the scroller is informed that the work-area is created.

(defmethod son-created ((scroller scroller) son))

You rarely override this method or add deamons. The default version is sufficient for most cases. Normally, you do not call this method. It is called by GINA when appropriate. It is never overridden by GINA.

Related methods:

[  ] son-created ((w widget) son)  (Page 119)

parent is informed that a new son is created

11.28.3 scroll-to Method

Purpose: initiate scrolling from the application side.

(defmethod scroll-to ((scroller scroller) x-offset y-offset &key (x-window-only
nil)))

You rarely override this method or add deamons. The default version is sufficient for most cases. You can call this method to scroll to a new position. It is called by GINA when appropriate. It is never overridden by GINA.

11.28.4 show-point Method

Purpose: do minimal scrolling to make the specified point visible.

(defmethod show-point ((scroller scroller) x y &key (ask-for-work-area-pos t)
(ask-for-clipper-size t) (x-window-only nil) (force-scrolling nil)))

You rarely override this method or add deamons. The default version is sufficient for most cases. Normally, you do not call this method. It is called by GINA when appropriate. It is never overridden by GINA.

11.28.5 point-visible Method

Purpose: check whether the specified point is visible.

(defmethod point-visible ((scroller scroller) x y &key (ask-for-work-area-pos t)
(ask-for-clipper-size t)))

You rarely override this method or add deamons. The default version is sufficient for most cases. Normally, you do not call this method. It is called by GINA when appropriate. It is never overridden by GINA.

11.29 separator Class

The class separator is the Motif separator widget. It is a subclass of widget. You rarely define subclasses of this class. GINA does not define subclasses of this class. You can create an instance of this class.

Local Slots:

\underline{widget:} widget-id integer returned by CLM create-widget call group-widget-id id used when the whole group is meant widget-id-for-sons may be different from widget-id in compound widgets parent the parent widget object in the hierarchy name name string for resource database lookup width total width in pixels height total height in pixels x-pos the x-coordinate relative to the parent y-pos the y-coordinate relative to the parent

11.29.1 make-separator Function

Purpose: make a new separator widget.

(defun make-separator (parent &key (orientation :horizontal) (margin 0)
                       (separator-type :shadow-etched-in) (class 'separator)
                       (initargs nil) (motif-widget-class :separator)
                       (name class) (managed t) (motif-resources nil)))

parent: the parent widget orientation: :horizontal or :vertical margin: between end of line and end of widget

separator-type:  type of line

This is the constructor function for class separator. The returned value is a newly created object of class separator. You can call this function. It is sometimes called by GINA. separator-type may be one of: :no-line :single-line :double-line :single-dashed-line :double-dashed-line :shadow-etched-in :shadow-etched-out

11.30 frame Class

The class frame is the Motif frame widget. It is a subclass of widget. You rarely define subclasses of this class. GINA defines subclasses of this class. You can create an instance of this class.

Local Slots:

\underline{widget:} widget-id integer returned by CLM create-widget call group-widget-id id used when the whole group is meant widget-id-for-sons may be different from widget-id in compound widgets parent the parent widget object in the hierarchy name name string for resource database lookup width total width in pixels height total height in pixels x-pos the x-coordinate relative to the parent y-pos the y-coordinate relative to the parent

11.30.1 make-frame Function

Purpose: make a new frame widget.

(defun make-frame (parent &key (margin-width 0) (margin-height 0)
                   (shadow-type :in) (class 'frame) (initargs nil)
                   (motif-widget-class :frame) (name class) (managed t)
                   (motif-resources nil)))

shadow-type: :in :out :etched-in :etched-out

This is the constructor function for class frame. The returned value is a newly created object of class frame. You can call this function. It is sometimes called by GINA.

11.31 paned-window Class

The class paned-window is the Motif paned window widget. It is a subclass of widget. You rarely define subclasses of this class. GINA does not define subclasses of this class. You can create an instance of this class.

Local Slots:

\underline{widget:} widget-id integer returned by CLM create-widget call group-widget-id id used when the whole group is meant widget-id-for-sons may be different from widget-id in compound widgets parent the parent widget object in the hierarchy name name string for resource database lookup width total width in pixels height total height in pixels x-pos the x-coordinate relative to the parent y-pos the y-coordinate relative to the parent

11.31.1 make-paned-window Function

Purpose: make a new paned-window widget.

(defun make-paned-window (parent &key (spacing 8) (class 'paned-window)
                          (initargs nil) (motif-widget-class :paned-window)
                          (name class) (managed t) (motif-resources nil)))

parent: the parent widget spacing: between panes This is the constructor function for class paned-window. The returned value is a newly created object of class paned-window. You can call this function. It is sometimes called by GINA.

11.31.2 define-pane-constraint Function

Purpose: define constraint for child of a paned-window widget.

(defun define-pane-constraint (widget &key (minimum 1000 minimum-specified)
                               (maximum 1000 maximum-specified)
                               (allow-resize nil allow-resize-specified)
                               (skip-adjust nil skip-adjust-specified)))

widget: a child of the pane minimum: the minimum size of this pane maximum: the maximum size of this pane

You can call this function to set constraints for a paned-window child. It is sometimes called by GINA.

11.32 row-column Class

The class row-column is the Motif row-column widget. It is a subclass of widget. You rarely define subclasses of this class. GINA defines subclasses of this class. You can create an instance of this class.

Local Slots:

\underline{widget:} widget-id integer returned by CLM create-widget call group-widget-id id used when the whole group is meant widget-id-for-sons may be different from widget-id in compound widgets parent the parent widget object in the hierarchy name name string for resource database lookup width total width in pixels height total height in pixels x-pos the x-coordinate relative to the parent y-pos the y-coordinate relative to the parent

11.32.1 make-row-column Function

Purpose: make a new row-column widget.

(defun make-row-column (parent &key (orientation :vertical) (num-columns 1)
                        (packing nil) (entry-alignment :beginning) (spacing 1)
                        (margin-width 2) (margin-height 2) (class 'row-column)
                        (initargs nil) (motif-widget-class :row-column)
                        (name class) (managed t) (motif-resources nil)))

parent: the parent widget orientation: :vertical or :horizontal num-columns: more than one implies column packing packing: nil=dynamic, :pack-column or :pack-tight entry-alignment: :none, :beginning, :center or :end spacing: between children

This is the constructor function for class row-column. The returned value is a newly created object of class row-column. You can call this function. It is sometimes called by GINA.

11.33 labeled-frame Class

An instance of class labeled-frame is a frame with a label on top. It is a subclass of frame and widget. You rarely define subclasses of this class. GINA does not define subclasses of this class. You can create an instance of this class.

Local Slots:

labeled-frame: column automatically created row-column label automatically created label-child \underline{widget:} widget-id integer returned by CLM create-widget call group-widget-id id used when the whole group is meant widget-id-for-sons may be different from widget-id in compound widgets parent the parent widget object in the hierarchy name name string for resource database lookup width total width in pixels height total height in pixels x-pos the x-coordinate relative to the parent y-pos the y-coordinate relative to the parent

11.33.1 make-labeled-frame Function

Purpose: make a new labeled-frame widget.

(defun make-labeled-frame (parent label-string &key (shadow-type :etched-in)
                           (class 'labeled-frame) (initargs nil)
                           (motif-widget-class :frame) (name class) (managed t)
                           (motif-resources nil) (label-resources nil)
                           (column-resources nil)))

parent: the parent widget label-string: the label string shown shadow-type: :in :out :etched-in :etched-out label-resources: motif-resources for the label column-resources: motif-resources for the row-column

This is the constructor function for class labeled-frame. The returned value is a newly created object of class labeled-frame. You can call this function. It is sometimes called by GINA.

11.34 toggle-button-group Class

An instance of class toggle-button-group is a group of toggle buttons with optional label and frame. It is a subclass of row-column and widget. You rarely define subclasses of this class. GINA defines subclasses of this class. You can create an instance of this class.

Callbacks:

value-changed-callback (value toggled-value set)

Local Slots:

toggle-button-group: button-resources motif-resources for buttons button-label-type label-type for buttons value a subset of value-list

Default: nil

value-list the list of values extracted from the item list main-column the enclosing row-column

Default: nil

label the title label widget

Default: nil

frame the frame widget

Default: nil

toggle-buttons the list of toggle buttons Default: nil separators the list of separators

Default: nil

\underline{widget:} widget-id integer returned by CLM create-widget call group-widget-id id used when the whole group is meant widget-id-for-sons may be different from widget-id in compound widgets parent the parent widget object in the hierarchy name name string for resource database lookup width total width in pixels height total height in pixels x-pos the x-coordinate relative to the parent y-pos the y-coordinate relative to the parent

Methods of class toggle-button-group:

[o ] execute-value-changed-callback ((group toggle-button-group) new-value &optional toggled-value set)  (Page 187)

reaction when a button is toggled by the user

[ c] set-item-list ((group toggle-button-group) new-item-list &key (selected-value nil) (managed t))  (Page 186)

the item-list has changed

[  ] (setf value) :before (new-value (group toggle-button-group))  (Page 186)

the application has changed the selected values

11.34.1 make-toggle-button-group Function

Purpose: make new group of toggle buttons with optional label and frame.

(defun make-toggle-button-group (parent item-list &key (label-string nil)
                                 (value-changed-callback :call-method)
                                 (initial-value nil) (with-frame t)
                                 (shadow-type :etched-in) (spacing 1)
                                 (num-columns 1) (orientation :vertical)
                                 (button-label-type :string)
                                 (class 'toggle-button-group) (initargs nil)
                                 (name class) (managed t) (motif-resources nil)
                                 (button-resources nil)))

parent: the parent widget item-list: a list of strings or (string value) pairs

label-string:  as title
value-changed-callback::call-method or a callback

initial-value: subset of values in item-list with-frame: whether enclosing frame visible shadow-type: :in :out :etched-in :etched-out spacing: between buttons num-columns: for row-column orientation: :vertical or :horizontal

button-label-type:  :string or :pixmap

button-resources: motif-resources for buttons This is the constructor function for class toggle-button-group. The returned value is a newly created object of class toggle-button-group. You can call this function. It is sometimes called by GINA.

11.34.2 (setf value) :before Method

Purpose: the application has changed the selected values.

(defmethod (setf value) :before (new-value (group toggle-button-group)))

Deamon installed by GINA.

Related methods:

[  ] (setf value) :after (new-value (entry toggle-entry))  (Page 165)

propagate value changes to the widget

[  ] (setf value) :after (new-value (selection-list selection-list))  (Page 191)

the application has changed the selected value

[  ] (setf value) :after (new-value (option-menu option-menu))  (Page 175)

the value is changed by the application program, not the user

[  ] (setf value) :before (new-value (group toggle-group-entry))  (Page 168)

the application has changed the selected values

11.34.3 set-item-list Method

Purpose: the item-list has changed.

(defmethod set-item-list ((group toggle-button-group) new-item-list &key
(selected-value nil) (managed t)))

new-item-list: a list of strings or (string value) pairs selected-value: a subset of the values in item-list

You rarely override this method or add deamons. The default version is sufficient for most cases. You can call this method to change the list of items. It is called by GINA when appropriate. It is never overridden by GINA.

Example

(set-item-list
  toggle-button-group
  '(("Bold" :bold) ("Italic" :italic) ("Underline" :under))
  :selected-values
  '(:italic :under))

[ c] set-item-list ((group radio-group-entry) new-item-list &key (selected-value :use-first))  (Page 170)

the item-list has changed

[ c] set-item-list ((selection-list selection-list) new-item-list &key (selected-value :use-first)) (Page 192)

the item-list has changed

[ c] set-item-list ((group toggle-group-entry) new-item-list &key (selected-value nil))  (Page 168)

the item-list has changed

[ c] set-item-list ((option-menu option-menu) new-item-list &key (selected-value :use-first))  (Page 173)

the item-list has changed

[ c] set-item-list ((group radio-button-group) new-item-list &key (selected-value :use-first) (managed t))  (Page 189)

the item-list has changed

11.34.4 execute-value-changed-callback Method

Purpose: reaction when a button is toggled by the user.

(defmethod execute-value-changed-callback ((group toggle-button-group) new-value
&optional toggled-value set))

You can override this method. The default version does not do anything. Normally, you do not call this method. It is called by GINA when appropriate. It is never overridden by GINA.

Related methods:

[o ] execute-value-changed-callback ((option-menu option-menu) new-value &optional old-value ignore) (Page 174)

reaction when a new option is selected by the user

[o ] execute-value-changed-callback ((button toggle-button) set &optional ignore1 ignore2)  (Page 150)

semantics of a users mouse click into the toggle-button

[o ] execute-value-changed-callback ((scrollbar scrollbar) new-value &optional ignore1 ignore2)  (Page 158)

semantics of a users modification of the current value

[o ] execute-value-changed-callback ((scale scale) new-value &optional ignore1 ignore2) (Page 156)

semantics of a users modification of the current value

11.35 radio-button-group Class

An instance of class radio-button-group is a group of radio buttons with optional label and frame.

It is a subclass of toggle-button-group, row-column and widget. You rarely define subclasses of this class. GINA does not define subclasses of this class. You can create an instance of this class.

Callbacks:

value-changed-callback (value old-value)

Local Slots:

toggle-button-group: button-resources motif-resources for buttons button-label-type label-type for buttons value a subset of value-list

Default: nil

value-list the list of values extracted from the item list main-column the enclosing row-column

Default: nil

label the title label widget

Default: nil

frame the frame widget

Default: nil

toggle-buttons the list of toggle buttons

Default: nil

separators the list of separators

Default: nil

\underline{widget:} widget-id integer returned by CLM create-widget call group-widget-id id used when the whole group is meant widget-id-for-sons may be different from widget-id in compound widgets parent the parent widget object in the hierarchy name name string for resource database lookup width total width in pixels height total height in pixels x-pos the x-coordinate relative to the parent y-pos the y-coordinate relative to the parent

Methods of class radio-button-group:

[ c] set-item-list ((group radio-button-group) new-item-list &key (selected-value :use-first) (managed t))  (Page 189)

the item-list has changed

Methods of superclasses:

[o ] execute-value-changed-callback ((group toggle-button-group) new-value &optional toggled-value set)  (Page 187)

reaction when a button is toggled by the user

[ c] set-item-list ((group toggle-button-group) new-item-list &key (selected-value nil) (managed t))  (Page 186)

the item-list has changed

[  ] (setf value) :before (new-value (group toggle-button-group))  (Page 186)

the application has changed the selected values

11.35.1 make-radio-button-group Function

Purpose: make new group of toggle buttons with optional label and frame.

(defun make-radio-button-group (parent item-list &key (label-string nil)
                                (value-changed-callback :call-method)
                                (initial-value :use-first) (with-frame t)
                                (shadow-type :etched-in) (spacing 1)
                                (num-columns 1) (orientation :vertical)
                                (button-label-type :string)
                                (class 'radio-button-group) (initargs nil)
                                (name class) (managed t) (motif-resources nil)
                                (button-resources nil)))

parent: the parent widget item-list: a list of strings or (string value) pairs

label-string:  as title
value-changed-callback::call-method or a callback

initial-value: a value from the item-list or :use-first with-frame: whether enclosing frame visible shadow-type: :in :out :etched-in :etched-out spacing: between buttons num-columns: for row-column orientation: :vertical or :horizontal

button-label-type:  :string or :pixmap

button-resources: motif-resources for buttons

This is the constructor function for class radio-button-group. The returned value is a newly created object of class radio-button-group. You can call this function. It is sometimes called by GINA.

11.35.2 set-item-list Method

Purpose: the item-list has changed.

(defmethod set-item-list ((group radio-button-group) new-item-list &key
(selected-value :use-first) (managed t)))

new-item-list: a list of strings or (string value) pairs selected-value: a value from the item list or :use-first You rarely override this method or add deamons. The default version is sufficient for most cases. You can call this method to change the list of items. It is called by GINA when appropriate. It is never overridden by GINA.

Related methods:

[ c] set-item-list ((group radio-group-entry) new-item-list &key (selected-value :use-first))  (Page 170)

the item-list has changed

[ c] set-item-list ((selection-list selection-list) new-item-list &key (selected-value :use-first)) (Page 192)

the item-list has changed

[ c] set-item-list ((group toggle-group-entry) new-item-list &key (selected-value nil))  (Page 168)

the item-list has changed

[ c] set-item-list ((option-menu option-menu) new-item-list &key (selected-value :use-first))  (Page 173)

the item-list has changed

[ c] set-item-list ((group toggle-button-group) new-item-list &key (selected-value nil) (managed t))  (Page 186)

the item-list has changed

11.36 selection-list Class

The class selection-list is the Motif List widget. It is a subclass of widget. You rarely define subclasses of this class. GINA defines subclasses of this class. You can create an instance of this class.

Callbacks:

value-changed-callback (value old-value)

Local Slots:

selection-list: default-action-button button to activate on double-click selection-policy :single :multiple :browse :extended value a single value or a subset of value-list

Default: nil

value-list the list of values extracted from the item list string-list the list of strings extracted from the item list \underline{widget:} widget-id integer returned by CLM create-widget call group-widget-id id used when the whole group is meant widget-id-for-sons may be different from widget-id in compound widgets parent the parent widget object in the hierarchy name name string for resource database lookup width total width in pixels height total height in pixels x-pos the x-coordinate relative to the parent y-pos the y-coordinate relative to the parent

Methods of class selection-list:

[ c] set-item-list ((selection-list selection-list) new-item-list &key (selected-value :use-first)) (Page 192)

the item-list has changed

[ c] show-item ((selection-list selection-list) value-to-show)  (Page 193)

scroll to show item at top

[  ] (setf value) :after (new-value (selection-list selection-list))  (Page 191)

the application has changed the selected value

11.36.1 make-selection-list Function

Purpose: make a new list widget.

(defun make-selection-list (parent item-list &key (default-action-button nil)
                            (initial-value :use-first) (visible-item-count 10)
                            (width 100) (selection-policy :browse)
                            (class 'selection-list) (initargs nil)
                            (motif-widget-class :list) (name class) (managed t)
                            (motif-resources nil)))

parent: the parent widget item-list: list of strings or (string value) pairs default-action-button: button to activate on double-click initial-value: a value or subset from the value-list visible-item-count: determines the initial height width: initial width if allowed selection-policy: :single :multiple :browse :extended

This is the constructor function for class selection-list. The returned value is a newly created object of class selection-list. You can call this function. It is sometimes called by GINA.

11.36.2 (setf value) :after Method

Purpose: the application has changed the selected value.

(defmethod (setf value) :after (new-value (selection-list selection-list)))

Deamon installed by GINA.

[  ] (setf value) :after (new-value (entry toggle-entry))  (Page 165)

propagate value changes to the widget

[  ] (setf value) :after (new-value (option-menu option-menu))  (Page 175)

the value is changed by the application program, not the user

[  ] (setf value) :before (new-value (group toggle-button-group))  (Page 186)

the application has changed the selected values

[  ] (setf value) :before (new-value (group toggle-group-entry))  (Page 168)

the application has changed the selected values

11.36.3 set-item-list Method

Purpose: the item-list has changed.

(defmethod set-item-list ((selection-list selection-list) new-item-list &key
(selected-value :use-first)))

new-item-list: list of strings or (string value) pairs selected-value: a value or subset from value-list

You rarely override this method or add deamons. The default version is sufficient for most cases. You can call this method to change the list of selectable values. It is called by GINA when appropriate. It is never overridden by GINA.

Related methods:

[ c] set-item-list ((group radio-group-entry) new-item-list &key (selected-value :use-first))  (Page 170)

the item-list has changed

[ c] set-item-list ((group toggle-group-entry) new-item-list &key (selected-value nil))  (Page 168)

the item-list has changed

[ c] set-item-list ((option-menu option-menu) new-item-list &key (selected-value :use-first))  (Page 173)

the item-list has changed

[ c] set-item-list ((group toggle-button-group) new-item-list &key (selected-value nil) (managed t))  (Page 186)

the item-list has changed

[ c] set-item-list ((group radio-button-group) new-item-list &key (selected-value :use-first) (managed t))  (Page 189)

the item-list has changed

11.36.4 show-item Method

Purpose: scroll to show item at top.

(defmethod show-item ((selection-list selection-list) value-to-show))

You rarely override this method or add deamons. The default version is sufficient for most cases. You can call this method to show a certain item at the top. It is called by GINA when appropriate. It is never overridden by GINA.

11.37 scrollable-selection-list Class

An instance of class scrollable-selection-list is a selection-list inside a scroller. It is a subclass of selection-list and widget. You rarely define subclasses of this class. GINA does not define subclasses of this class. You can create an instance of this class.

Callbacks:

value-changed-callback (value old-value)

Local Slots:

scrollable-selection-list: scroller surrounding the list selection-list: default-action-button button to activate on double-click selection-policy :single :multiple :browse :extended value a single value or a subset of value-list

Default: nil

value-list the list of values extracted from the item list string-list the list of strings extracted from the item list \underline{widget:} widget-id integer returned by CLM create-widget call group-widget-id id used when the whole group is meant widget-id-for-sons may be different from widget-id in compound widgets parent the parent widget object in the hierarchy name name string for resource database lookup width total width in pixels height total height in pixels x-pos the x-coordinate relative to the parent y-pos the y-coordinate relative to the parent

Methods of superclasses:

[ c] set-item-list ((selection-list selection-list) new-item-list &key (selected-value :use-first)) (Page 192)

the item-list has changed

[ c] show-item ((selection-list selection-list) value-to-show)  (Page 193)

scroll to show item at top

[  ] (setf value) :after (new-value (selection-list selection-list))  (Page 191)

the application has changed the selected value

11.37.1 make-scrollable-selection-list Function

Purpose: make a new scroller containing a selection-list.

(defun make-scrollable-selection-list (parent item-list &key
                                       (default-action-button nil)
                                       (initial-value :use-first)
                                       (visible-item-count 10) (width 100)
                                       (selection-policy :browse)
                                       (class 'scrollable-selection-list)
                                       (initargs nil)
                                       (motif-widget-class :list) (name class)
                                       (managed t) (motif-resources nil)))

parent: the parent widget item-list: list of strings or (string value) pairs default-action-button: button to activate on double-click initial-value: a value or subset from the value-list visible-item-count: determines the initial height width: initial width if allowed selection-policy: :single :multiple :browse :extended

This is the constructor function for class scrollable-selection-list. The returned value is a newly created object of class scrollable-selection-list. You can call this function. It is sometimes called by GINA.

11.38 bulletin-board Class

The class bulletin-board is the Motif bulletin board widget. It is a subclass of widget. You rarely define subclasses of this class. GINA defines subclasses of this class. You can create an instance of this class.

Callbacks:

map-callback  ()
unmap-callback  ()

\underline{widget:} widget-id integer returned by CLM create-widget call group-widget-id id used when the whole group is meant widget-id-for-sons may be different from widget-id in compound widgets parent the parent widget object in the hierarchy name name string for resource database lookup width total width in pixels height total height in pixels x-pos the x-coordinate relative to the parent y-pos the y-coordinate relative to the parent

11.38.1 make-bulletin-board Function

Purpose: create a new CLOS Object representing a BulletinBoard.

(defun make-bulletin-board (parent &key (auto-unmanage nil)
                            (class 'bulletin-board) (initargs nil)
                            (motif-widget-class :bulletin-board) (name class)
                            (managed nil) (motif-resources nil)))

parent: the parent widget auto-unmanage: if button activation removes dialog

This is the constructor function for class bulletin-board. The returned value is a newly created object of class bulletin-board. You can call this function. It is sometimes called by GINA.

11.39 form Class

The class form is the Motif form widget. It is a subclass of bulletin-board and widget. You rarely define subclasses of this class. GINA defines subclasses of this class. You can create an instance of this class.

Callbacks:

map-callback  ()
unmap-callback  ()

\underline{widget:} widget-id integer returned by CLM create-widget call group-widget-id id used when the whole group is meant widget-id-for-sons may be different from widget-id in compound widgets parent the parent widget object in the hierarchy name name string for resource database lookup width total width in pixels height total height in pixels x-pos the x-coordinate relative to the parent y-pos the y-coordinate relative to the parent

11.39.1 make-form Function

Purpose: make a new form widget.

(defun make-form (parent &key (auto-unmanage nil) (class 'form) (initargs nil)
                  (motif-widget-class :form) (name class) (managed t)
                  (motif-resources nil)))

parent: the parent widget auto-unmanage: if button activation removes dialog

This is the constructor function for class form. The returned value is a newly created object of class form. You can call this function. It is sometimes called by GINA.

11.39.2 define-form-constraint Function

Purpose: define layout constraint for child of a form widget.

(defun define-form-constraint (widget &rest constraint-resources))

widget: a child of the form constraint-resources: list of motif constraint resources

You can call this function to define attachments for form children. It is sometimes called by GINA. Every side of a widget can be individually attached in the following ways: :none :form :opposite-form :widget :opposite-widget :position :self 2-5 use the :(dir)-offset, :position uses :(dir)-position, 4-5 use the :(dir)-widget parameters in the list

Example

(define-form-constraint
  child
  :top-attachment
  :form
  :top-offset
  4
  :left-attachment
  widget
  :left-widget
  another-child
  :right-attachment
  :position
  :right-position
  50
  :bottom-attachment
  :none)

11.40 text Class

The class text is the Motif text widget. It is a subclass of widget. You rarely define subclasses of this class. GINA defines subclasses of this class. You can create an instance of this class.

Callbacks:

value-changed-callback () but (value) for single-line texts modify-verify-callback (current-insert new-insert start-pos end-pos text length) motion-verify-callback (current-insert new-insert) losing-focus-callback (current-insert new-insert start-pos end-pos)

activate-callback  ()

Local Slots:

\underline{text:} value the current string value \underline{widget:} widget-id integer returned by CLM create-widget call group-widget-id id used when the whole group is meant widget-id-for-sons may be different from widget-id in compound widgets parent the parent widget object in the hierarchy name name string for resource database lookup width total width in pixels height total height in pixels x-pos the x-coordinate relative to the parent y-pos the y-coordinate relative to the parent value

11.40.1 make-text Function

Purpose: make a new text widget.

(defun make-text (parent &key (value "") (editable t) (columns 20) (rows 1)
                  (edit-mode :single-line-edit) (class 'text) (initargs nil)
                  (motif-widget-class :text) (name class) (managed t)
                  (motif-resources nil)))

parent: the parent widget value: initial value editable: if editable columns: determines initial width rows: determines initial height edit-mode: :single-line-edit or :multi-line-edit

This is the constructor function for class text. The returned value is a newly created object of class text. You can call this function. It is sometimes called by GINA.

11.41 scrolled-text Class

An instance of class scrolled-text is a text widget inside a scroller. It is a subclass of text and widget. You rarely define subclasses of this class. GINA does not define subclasses of this class. You can create an instance of this class.

Callbacks:

value-changed-callback () but (value) for single-line texts modify-verify-callback (current-insert new-insert start-pos end-pos text length) motion-verify-callback (current-insert new-insert) losing-focus-callback (current-insert new-insert start-pos end-pos)

activate-callback  ()

Local Slots:

scrolled-text: scroller surrounding the list \underline{text:} value the current string value \underline{widget:} widget-id integer returned by CLM create-widget call group-widget-id id used when the whole group is meant widget-id-for-sons may be different from widget-id in compound widgets parent the parent widget object in the hierarchy name name string for resource database lookup width total width in pixels height total height in pixels x-pos the x-coordinate relative to the parent y-pos the y-coordinate relative to the parent

11.41.1 make-scrolled-text Function

Purpose: make a new scroller containing a text widget.

(defun make-scrolled-text (parent &key (value "") (editable t) (columns 20)
                           (rows 10) (scroll-vertical t) (scroll-horizontal t)
                           (class 'scrolled-text) (initargs nil)
                           (motif-widget-class :text) (name class) (managed t)
                           (motif-resources nil)))

parent: the parent widget value: initial value editable: if editable columns: determines initial width rows: determines initial height scroll-vertical: if vertical scrollbar scroll-horizontal: if horizontal scrollbar

This is the constructor function for class text. The returned value is a newly created object of class text. You can call this function. It is sometimes called by GINA.

11.42 labeled-text Class

An instance of class labeled-text is a text widget with a label. It is a subclass of text and widget. You rarely define subclasses of this class. GINA does not define subclasses of this class. You can create an instance of this class.

Callbacks:

value-changed-callback () but (value) for single-line texts modify-verify-callback (current-insert new-insert start-pos end-pos text length) motion-verify-callback (current-insert new-insert) losing-focus-callback (current-insert new-insert start-pos end-pos)

activate-callback  ()

Local Slots:

labeled-text: label the label widget row-column the enclosing row-column

label-position  :top or :left

\underline{text:} value the current string value \underline{widget:} widget-id integer returned by CLM create-widget call group-widget-id id used when the whole group is meant widget-id-for-sons may be different from widget-id in compound widgets parent the parent widget object in the hierarchy name name string for resource database lookup width total width in pixels height total height in pixels x-pos the x-coordinate relative to the parent y-pos the y-coordinate relative to the parent

Methods of class labeled-text:

[  ] (setf label-position) :after (new-label-position (lt labeled-text)) (Page 201)

modify orientation of row-column

11.42.1 make-labeled-text Function

Purpose: create a new labeled text.

(defun make-labeled-text (parent label-string &key (value "") (editable t)
                          (columns 20) (edit-mode :single-line-edit)
                          (label-position :left) (class 'labeled-text)
                          (initargs nil) (motif-widget-class :text)
                          (name class) (managed t) (motif-resources nil)
                          (row-column-resources nil) (label-resources nil)))

parent: the parent widget

label-string:  the label shown

value: initial value editable: if editable columns: determines initial width edit-mode: :single-line-edit or :multi-line-edit

label-position:  :top or :left

row-column-resources: motif-resources for row-column label-resources: motif-resources for the label This is the constructor function for class labeled-text. The returned value is a newly created object of class labeled-text. You can call this function. It is sometimes called by GINA.

11.42.2 (setf label-position) :after Method

Purpose: modify orientation of row-column.

(defmethod (setf label-position) :after (new-label-position (lt labeled-text)))

Deamon installed by GINA.

11.43 dialog-box Class

An instance of class dialog-box is a superclass for gina dialog boxes. It is a subclass of form, bulletin-board and widget. You can define a subclass of this class. GINA defines subclasses of this class. You never create an instance of this class.

Callbacks:

map-callback  ()
unmap-callback  ()

Local Slots:

\underline{dialog-box:} document the document associated with the dialog box dialog-shell the shell widget around the dialog relative-widget a widget used for relative popup positioning

Default: nil

relative-x one of :center :left :left-align :right-align :right

Default: :center

relative-y one of :center :top :top-align :bottom-align :bottom

Default: :center

result value returned from modal dialog

Default: nil

\underline{widget:} widget-id integer returned by CLM create-widget call group-widget-id id used when the whole group is meant widget-id-for-sons may be different from widget-id in compound widgets parent the parent widget object in the hierarchy name name string for resource database lookup width total width in pixels height total height in pixels x-pos the x-coordinate relative to the parent y-pos the y-coordinate relative to the parent

Methods of class dialog-box:

[o ] closed-by-wm ((box dialog-box))  (Page 202)

dialog-box is being closed by the window manager

11.43.1 closed-by-wm Method

Purpose: dialog-box is being closed by the window manager.

(defmethod closed-by-wm ((box dialog-box)))

You can override this method. The default version calls pop-down. Normally, you do not call this method. It is called by GINA when appropriate. It is never overridden by GINA.

Related methods:

[  ] closed-by-wm ((shell modal-dialog-shell))  (Page 138)

modal-dialog-shells cannot be closed by the window manager

[o ] closed-by-wm ((shell toplevel-shell))  (Page 132)

shell is being closed by the window manager

[o ] closed-by-wm ((shell basic-document-shell))  (Page 142)

closing a document shell means closing its document

11.44 modeless-dialog-box Class

An instance of class modeless-dialog-box is a form with a shell around it for modeless dialogs. It is a subclass of dialog-box, form, bulletin-board and widget. You define a subclass of this class for application-specific modeless dialogs. GINA does not define subclasses of this class. You can create an instance of this class.

Callbacks:

map-callback  ()
unmap-callback  ()

modeless-dialog-box: default-button the default button in the dialog, if any

Default: nil

\underline{dialog-box:} document the document associated with the dialog box dialog-shell the shell widget around the dialog relative-widget a widget used for relative popup positioning

Default: nil

relative-x one of :center :left :left-align :right-align :right

Default: :center

relative-y one of :center :top :top-align :bottom-align :bottom

Default: :center

result value returned from modal dialog

Default: nil

\underline{widget:} widget-id integer returned by CLM create-widget call group-widget-id id used when the whole group is meant widget-id-for-sons may be different from widget-id in compound widgets parent the parent widget object in the hierarchy name name string for resource database lookup width total width in pixels height total height in pixels x-pos the x-coordinate relative to the parent y-pos the y-coordinate relative to the parent

Methods of class modeless-dialog-box:

[  ] (setf default-button) :after (new-default-button (box modeless-dialog-box))  (Page 204)

set default-button resource in the toolkit

[ c] pop-down ((box modeless-dialog-box))  (Page 205)

hide the modeless dialog box

[ c] pop-up ((box modeless-dialog-box))  (Page 204)

show the modeless dialog box

Methods of superclasses:

[o ] closed-by-wm ((box dialog-box))  (Page 202)

dialog-box is being closed by the window manager

11.44.1 make-modeless-dialog-box Function

Purpose: make a form with a shell around it for modeless dialogs.

(defun make-modeless-dialog-box (title &key
                                 (document (first

                                             (document-list *application*)))
                                 (resize nil) (allow-shell-resize nil)
                                 (return-is-accelerator t) (drag-protocols nil)
                                 (class 'modeless-dialog-box) (initargs nil)
                                 (motif-widget-class :form) (name class)
                                 (motif-resources nil)
                                 (dialog-shell-resources nil)))

title: the title string document: default: first document of application resize: whether include resize handles allow-shell-resize: whether resizeable by changing children return-is-accelerator: whether return activates default button drag-protocols: keyword list of accepted drag-commands dialog-shell-resources:motif-resources for dialog-shell

This is the constructor function for class modeless-dialog-box. The returned value is a newly created object of class modeless-dialog-box. You can call this function. It is sometimes called by GINA.

11.44.2 (setf default-button) :after Method

Purpose: set default-button resource in the toolkit.

(defmethod (setf default-button) :after (new-default-button (box
modeless-dialog-box)))

Deamon installed by GINA.

Related methods:

[  ] (setf default-button) :after (new-default-button (box modal-dialog-box))  (Page 207)

set default button resource in the toolkit

11.44.3 pop-up Method

Purpose: show the modeless dialog box.

(defmethod pop-up ((box modeless-dialog-box)))

You rarely override this method or add deamons. The default version is sufficient for most cases. You can call this method to make a dialog appear. It is called by GINA when appropriate. It is never overridden by GINA.

[ c] pop-up ((shell modeless-dialog-shell))  (Page 135)

popup the underlying widget

[ c] pop-up ((box modal-dialog-box))  (Page 207)

bring up the modal dialog

[  ] pop-up :after ((shell toplevel-shell))  (Page 131)

register shell at the application

[ c] pop-up ((box tool-dialog-box))  (Page 210)

show the tool dialog box

[ c] pop-up ((shell shell))  (Page 128)

popup the underlying widget

11.44.4 pop-down Method

Purpose: hide the modeless dialog box.

(defmethod pop-down ((box modeless-dialog-box)))

You rarely override this method or add deamons. The default version is sufficient for most cases. You can call this method to make a dialog disappear. It is called by GINA when appropriate. It is never overridden by GINA.

Related methods:

[ c] pop-down ((shell shell))  (Page 129)

popdown the underlying widget

[ c] pop-down ((box tool-dialog-box))  (Page 211)

hide the tool dialog box

[ c] pop-down ((box modal-dialog-box))  (Page 208)

end the modal dialog

[ c] pop-down ((shell modeless-dialog-shell))  (Page 136)

popdown the underlying widget

11.45 modal-dialog-box Class

An instance of class modal-dialog-box is a form with a shell around it for modal dialogs. It is a subclass of dialog-box, form, bulletin-board and widget. You define a subclass of this class for application-specific modal dialogs. GINA does not define subclasses of this class. You can create an instance of this class.

map-callback  ()
unmap-callback  ()

Local Slots:

modal-dialog-box: default-button the default button in the dialog, if any

Default: nil

\underline{dialog-box:} document the document associated with the dialog box dialog-shell the shell widget around the dialog relative-widget a widget used for relative popup positioning

Default: nil

relative-x one of :center :left :left-align :right-align :right

Default: :center

relative-y one of :center :top :top-align :bottom-align :bottom

Default: :center

result value returned from modal dialog

Default: nil

\underline{widget:} widget-id integer returned by CLM create-widget call group-widget-id id used when the whole group is meant widget-id-for-sons may be different from widget-id in compound widgets parent the parent widget object in the hierarchy name name string for resource database lookup width total width in pixels height total height in pixels x-pos the x-coordinate relative to the parent y-pos the y-coordinate relative to the parent

Methods of class modal-dialog-box:

[  ] (setf default-button) :after (new-default-button (box modal-dialog-box))  (Page 207)

set default button resource in the toolkit

[ c] pop-down ((box modal-dialog-box))  (Page 208)

end the modal dialog

[ c] pop-up ((box modal-dialog-box))  (Page 207)

bring up the modal dialog

Methods of superclasses:

[o ] closed-by-wm ((box dialog-box))  (Page 202)

dialog-box is being closed by the window manager

11.45.1 make-modal-dialog-box Function

Purpose: make a form with a shell around it for modal dialogs.

(defun make-modal-dialog-box (title &key
                              (document (first (document-list *application*)))
                              (resize nil) (allow-shell-resize nil)
                              (return-is-accelerator t) (drag-protocols nil)
                              (class 'modal-dialog-box) (initargs nil)
                              (motif-widget-class :form) (name class)
                              (motif-resources nil)
                              (dialog-shell-resources nil)))

title: the title string document: default: the first document of application resize: whether include resize handles allow-shell-resize: whether resized by changing children return-is-accelerator: whether return activates default button drag-protocols: keyword list of accepted drag-commands dialog-shell-resources:motif-resources for dialog-shell

This is the constructor function for class modal-dialog-box. The returned value is a newly created object of class modal-dialog-box. You can call this function. It is sometimes called by GINA.

11.45.2 (setf default-button) :after Method

Purpose: set default button resource in the toolkit.

(defmethod (setf default-button) :after (new-default-button (box
modal-dialog-box)))

Deamon installed by GINA.

Related methods:

[  ] (setf default-button) :after (new-default-button (box modeless-dialog-box))  (Page 204)

set default-button resource in the toolkit

11.45.3 pop-up Method

Purpose: bring up the modal dialog.

(defmethod pop-up ((box modal-dialog-box)))

The returned value is the result slot. You rarely override this method or add deamons. The default version is sufficient for most cases. You can call this method to show a modal dialog and wait for the result. It is called by GINA when appropriate. It is never overridden by GINA.

Related methods:

[ c] pop-up ((shell modeless-dialog-shell))  (Page 135)

popup the underlying widget

[  ] pop-up :after ((shell toplevel-shell))  (Page 131)

register shell at the application

[ c] pop-up ((box modeless-dialog-box))  (Page 204)

show the modeless dialog box

[ c] pop-up ((box tool-dialog-box))  (Page 210)

show the tool dialog box

[ c] pop-up ((shell shell))  (Page 128)

popup the underlying widget

11.45.4 pop-down Method

Purpose: end the modal dialog.

(defmethod pop-down ((box modal-dialog-box)))

You rarely override this method or add deamons. The default version is sufficient for most cases. You can call this method to end the modal dialog. It is called by GINA when appropriate. It is never overridden by GINA.

Related methods:

[ c] pop-down ((shell shell))  (Page 129)

popdown the underlying widget

[ c] pop-down ((box tool-dialog-box))  (Page 211)

hide the tool dialog box

[ c] pop-down ((box modeless-dialog-box))  (Page 205)

hide the modeless dialog box

[ c] pop-down ((shell modeless-dialog-shell))  (Page 136)

popdown the underlying widget

11.46 tool-dialog-box Class

An instance of class tool-dialog-box is a form with a shell around it for tool dialogs with a menu.

It is a subclass of dialog-box, form, bulletin-board and widget. You rarely define subclasses of this class. GINA does not define subclasses of this class. You can create an instance of this class.

Callbacks:

map-callback  ()
unmap-callback  ()

Local Slots:

tool-dialog-box: main-menu the automatically created menu bar \underline{dialog-box:} document the document associated with the dialog box dialog-shell the shell widget around the dialog relative-widget a widget used for relative popup positioning

Default: nil

relative-x one of :center :left :left-align :right-align :right

Default: :center

relative-y one of :center :top :top-align :bottom-align :bottom

Default: :center

result value returned from modal dialog

Default: nil

\underline{widget:} widget-id integer returned by CLM create-widget call group-widget-id id used when the whole group is meant widget-id-for-sons may be different from widget-id in compound widgets parent the parent widget object in the hierarchy name name string for resource database lookup width total width in pixels height total height in pixels x-pos the x-coordinate relative to the parent y-pos the y-coordinate relative to the parent

Methods of class tool-dialog-box:

[ c] pop-down ((box tool-dialog-box))  (Page 211)

hide the tool dialog box

[ c] pop-up ((box tool-dialog-box))  (Page 210)

show the tool dialog box

Methods of superclasses:

[o ] closed-by-wm ((box dialog-box))  (Page 202)

dialog-box is being closed by the window manager

11.46.1 make-tool-dialog-box Function

Purpose: make a form with a shell an a menu bar for tool dialogs.

(defun make-tool-dialog-box (title &key
                             (document (first (document-list *application*)))
                             (allow-shell-resize nil) (drag-protocols nil)
                             (class 'tool-dialog-box) (initargs nil)
                             (motif-widget-class :form) (name class)
                             (motif-resources nil)
                             (dialog-shell-resources nil)))

title: the title string document: default: first document of application allow-shell-resize: whether resized by changing children drag-protocols: keyword list of accepted drag-commands dialog-shell-resources:motif-resources for dialog shell

This is the constructor function for class tool-dialog-box. The returned value is a newly created object of class tool-dialog-box. You can call this function. It is sometimes called by GINA.

11.46.2 pop-up Method

Purpose: show the tool dialog box.

(defmethod pop-up ((box tool-dialog-box)))

You rarely override this method or add deamons. The default version is sufficient for most cases. You can call this method to make a tool dialog appear. It is called by GINA when appropriate. It is never overridden by GINA.

Related methods:

[ c] pop-up ((shell modeless-dialog-shell))  (Page 135)

popup the underlying widget

[ c] pop-up ((box modal-dialog-box))  (Page 207)

bring up the modal dialog

[  ] pop-up :after ((shell toplevel-shell))  (Page 131)

register shell at the application

[ c] pop-up ((box modeless-dialog-box))  (Page 204)

show the modeless dialog box

[ c] pop-up ((shell shell))  (Page 128)

popup the underlying widget

11.46.3 pop-down Method

Purpose: hide the tool dialog box.

(defmethod pop-down ((box tool-dialog-box)))

You rarely override this method or add deamons. The default version is sufficient for most cases. You can call this method to make a tool dialog disappear. It is called by GINA when appropriate. It is never overridden by GINA.

Related methods:

[ c] pop-down ((shell shell))  (Page 129)

popdown the underlying widget

[ c] pop-down ((box modeless-dialog-box))  (Page 205)

hide the modeless dialog box

[ c] pop-down ((box modal-dialog-box))  (Page 208)

end the modal dialog

[ c] pop-down ((shell modeless-dialog-shell))  (Page 136)

popdown the underlying widget

11.47 dialog-dismiss-button Class

An instance of class dialog-dismiss-button is a push-button to dismiss a dialog box. It is a subclass of push-button, label and widget. You rarely define subclasses of this class. GINA does not define subclasses of this class. You can create an instance of this class.

Callbacks:

activate-callback  ()
arm-callback  ()
disarm-callback  ()

Local Slots:

dialog-dismiss-button: dialog-box modal dialog box containing the button result assigned to result-variable when button clicked \underline{label:} label-string the string shown label-type either :string or :pixmap \underline{widget:} widget-id integer returned by CLM create-widget call group-widget-id id used when the whole group is meant widget-id-for-sons may be different from widget-id in compound widgets parent the parent widget object in the hierarchy name name string for resource database lookup width total width in pixels height total height in pixels x-pos the x-coordinate relative to the parent y-pos the y-coordinate relative to the parent

Methods of class dialog-dismiss-button:

[o ] execute-activate-callback ((button dialog-dismiss-button))  (Page 212)

store result in dialog box

Methods of superclasses:

[o ] execute-activate-callback ((pb push-button))  (Page 152)

semantics of a users mouse click into the push-button

11.47.1 make-dialog-dismiss-button Function

Purpose: make a new dialog-dismiss-button widget.

(defun make-dialog-dismiss-button (parent string &key (dialog-box parent)
                                   (default-button nil) (result string)
                                   (class 'dialog-dismiss-button)
                                   (initargs nil)
                                   (motif-widget-class :push-button)
                                   (name class) (managed t)
                                   (motif-resources nil)))

parent: the parent widget string: the label string dialog-box: the dialog box to be notified default-button: whether it is the default button result: the result value to assign

This is the constructor function for class dialog-dismiss-button. The returned value is a newly created object of class dialog-dismiss-button. You can call this function. It is sometimes called by GINA.

11.47.2 execute-activate-callback Method

Purpose: store result in dialog box.

(defmethod execute-activate-callback ((button dialog-dismiss-button)))

You can override this method. The default version assigns result and removes the dialog. Normally, you do not call this method. It is called by GINA when appropriate. It is never overridden by GINA.

Related methods:

[o ] execute-activate-callback ((pb push-button))  (Page 152)

semantics of a users mouse click into the push-button

[o ] execute-activate-callback ((ab arrow-button))  (Page 154)

semantics of a users mouse click into the arrow-button

11.48 dialog-dismiss-button-row Class

An instance of class dialog-dismiss-button-row is a row of dialog-dismiss-buttons with the leftmost as default. It is a subclass of row-column and widget. You rarely define subclasses of this class. GINA does not define subclasses of this class. You can create an instance of this class.

Local Slots:

dialog-dismiss-button-row: buttons the list of buttons \underline{widget:} widget-id integer returned by CLM create-widget call group-widget-id id used when the whole group is meant widget-id-for-sons may be different from widget-id in compound widgets parent the parent widget object in the hierarchy name name string for resource database lookup width total width in pixels height total height in pixels x-pos the x-coordinate relative to the parent y-pos the y-coordinate relative to the parent

11.48.1 make-dialog-dismiss-button-row Function

Purpose: make row of dialog-dismiss-buttons with the leftmost as default.

(defun make-dialog-dismiss-button-row (parent &key
                                       (item-list
                                        '(("  Yes " :yes)
                                          ("  No  " :no)
                                          ("Cancel" :cancel)))

                                       (dialog-box parent) (spacing 30)
                                       (class 'dialog-dismiss-button-row)
                                       (initargs nil)
                                       (motif-widget-class :row-column)
                                       (name class) (managed t)
                                       (motif-resources nil)))

parent: the parent widget item-list: a list of strings or (string value) pairs dialog-box: the dialog box to be notified spacing: between buttons

This is the constructor function for class dialog-dismiss-button-row. The returned value is a newly created object of class dialog-dismiss-button-row. You can call this function. It is sometimes called by GINA.

Predefined Standard Dialogs

12.1 warning-dialog Function

Purpose: pop a a warning message as a modal dialog.

(defun warning-dialog (message &key
                   (document (first (document-list *application*)))
                   (modal t) (dialog-title "Warning")
                   (icon-pixmap "default_xm_error")))

icon-pixmap: icon used (error warning information question working)

You can call this function. It is sometimes called by GINA.

Example

(with-application-stopped (warning-dialog "Error: CPU not found!"))
(with-application-stopped
(warning-dialog
"Be very very careful !!"
:modal
nil
:icon-pixmap
"default_xm_information"))

12.2 question-dialog Function

Purpose: request an input string from the user.

(defun question-dialog (prompt &key
                    (document (first (document-list *application*)))
                    (dialog-title "Question") (default "")
                    (icon-pixmap "default_xm_question")))

icon-pixmap: icon used (error warning information question working)

The returned value is the string entered by the user or NIL if cancelled. You can call this function. It is sometimes called by GINA.

Example

(with-application-stopped (question-dialog "Filename:" :default "Untitled"))

12.3 confirm-dialog Function

Purpose: ask the user to confirm or reject.

(defun confirm-dialog (prompt &key
                       (document (first (document-list *application*)))
                       (dialog-title "Confirm")
                       (icon-pixmap "default_xm_question")))

icon-pixmap: icon used (error warning information question working)

The returned value is T or NIL. You can call this function. It is sometimes called by GINA.

Example

(with-application-stopped (confirm-dialog "Reformat disk?"))

12.4 alternative-dialog Function

Purpose: ask the user yes , no or cancel.

(defun alternative-dialog (prompt &key
                           (document (first (document-list *application*)))
                           (dialog-title "Alternative")
                           (icon-pixmap "default_xm_question")))

icon-pixmap: icon used (error warning information question working)

The returned value is one of :yes :no and :cancel. You can call this function. It is sometimes called by GINA.

Example

(with-application-stopped (alternative-dialog "Save Document ?"))

12.5 select-dialog Function

Purpose: let the user select from a list of strings.

(defun select-dialog (prompt item-list &key
                      (document (first (document-list *application*)))
                      (dialog-title "Select")))

The returned value is the selected value or NIL if cancelled. You can call this function. It is sometimes called by GINA.

Example

(with-application-stopped
  (select-dialog
    "Open which file?"
    '("File 1" "Brief" "Untitled" "Ordner" "Ordner1" "Ordner2" "Ordner3"
      "Ordner4" "Ordner5" "Ordner6" "Ordner7" "Ordner8")))

12.6 make-open-dialog-box Function

Purpose: create a modal dialog box to select an existing file.

(defun make-open-dialog-box (wildcard &key (file-type :wild)
                             (document (first (document-list *application*)))
                             (class 'open-dialog-box)))

You can call this function. It is sometimes called by GINA.

Example

(with-application-stopped
  (pop-up (make-open-dialog-box "W1:>GINA>documents>*.*.newest")))

12.7 make-save-dialog-box Function

Purpose: create a modal dialog box to select a new file.

(defun make-save-dialog-box (wildcard default-name &key (file-type :wild)
                             (document (first (document-list *application*)))
                             (class 'save-dialog-box)))

You can call this function. It is sometimes called by GINA.

Example

(with-application-stopped
  (pop-up (make-save-dialog-box "W1:>GINA>documents>*.*.newest" "Untitled")))

12.8 *inspected-object* Variable

Value: the last object inspected. Default: nil Normally, you do not modify this variable. It is modified each time any object is inspected.

12.9 inspect-dialog Function

Purpose: create a dialog box displaying the object’s slots.

(defun inspect-dialog (object &key
                       (document (first (document-list *application*)))
                       (last-box nil)))

You can call this function. It is sometimes called by GINA.

Example

(with-application-stopped (inspect-dialog *application*))

inspect the current application object

(with-application-stopped (inspect-dialog '(1 2 3 4 5 6)))

inspect a any lisp object

Background Processes

13.1 in-background-process Macro

Purpose: execute body in a background process

(defmacro in-background-process ((document &key (terminate-on-error t)) &body
body))

You can call this macro. It is never called by GINA. It returns the background process created. See also method kill-background-process of class document

Example

(with-application-stopped
  (in-background-process
    ((first (document-list *application*)))
    (replay-history (first (document-list *application*)))))

13.2 kill-background-process Method

Purpose: kill process, but wait until he is out of critical sections.

(defmethod kill-background-process ((doc document) process))

You rarely override this method or add deamons. The default version is sufficient for most cases. You can call this method. It is never called by GINA. It is never overridden by GINA.

13.3 kill-all-background-processes Method

Purpose: kill all background processes and wait for them to die.

(defmethod kill-all-background-processes ((doc document)))

You rarely override this method or add deamons. The default version is sufficient for most cases. You can call this method. It is called by GINA when the document is closed. It is never overridden by GINA.

13.4 with-application Macro

Purpose: execute body with exclusive access to the application

(defmacro with-application (&body body))

You can call this macro. It is called by GINA when appropriate.

Example

(with-application (print (eval (semaphor *application*))))

13.5 with-document Macro

Purpose: execute body with exclusive access to the document

(defmacro with-document ((document) &body body))

You can call this macro. It is called by GINA when appropriate.

Example

(with-document ((first (document-list *application*))) (print "Hallo"))

13.6 with-clm-connection Macro

Purpose: prevent clm calls by other processes for body

(defmacro with-clm-connection (&body body))

You can call this macro. It is called by GINA when appropriate.

13.7 with-progress-bar Macro

Purpose: execute body while displaying a progress bar

(defmacro with-progress-bar ((document &key (modal t) (title "Progress Bar")
(message "Performing your request ...") (abortable t) (kill-on-abort nil)
(centered t) (with-scale t)) &body body))

You can call this macro. It is never called by GINA. modal: whether all other input is blocked title: title string of the dialog box message: message displayed in the box abortable: whether user can abort the action kill-on-abort: whether process is killed or abort flag is set only centered: whether dialog box is centered over the document with-scale: whether a scale indicating progress is displayed

Example

(with-application-stopped
  (with-progress-bar
    ((first (document-list *application*)) :kill-on-abort t :centered nil)
    (loop for
          i
          from
          1
          to
          100
          do
          (sleep 0.1)
          (indicate-progress
            i
            :new-message
            (format nil "~d more steps to go ..." (- 100 i))))))
(with-application-stopped
  (with-progress-bar
    ((first (document-list *application*)) :kill-on-abort nil)
    (loop for
          i
          from
          1
          to
          10
          until
          (progress-bar-aborted)
          do
          (sleep 1)
          (indicate-progress (* 10 i)))))

13.8 progress-bar-aborted Function

Purpose: test whether progress bar has already been aborted.

(defun progress-bar-aborted ())

The returned value is whether ABORT has been pressed. You can call this function inside a WITH-PROGRESS-BAR macro. It is never called by GINA.

13.9 indicate-progress Function

Purpose: set scale to indicate the current progress.

(defun indicate-progress (percent &key (new-message nil)))

percent: percent of action already performed new-message: new label string displayed in dialog box

The returned value is whether ABORT has been pressed. You can call this function inside a WITH-PROGRESS-BAR macro. It is never called by GINA.

Chapter 14

Some Utilities for File System Handling

14.1 name-and-type Function

Purpose: extract name and type components of a pathname.

(defun name-and-type (pathname))

pathname: pathname object or string The returned value is a string. You can call this function. It is called by GINA in open/save dialogs.

Example

(name-and-type "w1:>gina>documents>four-rects.hello.3")

returns ”FOUR-RECTS.HELLO”

(name-and-type "xpssun:/home/spenke")

returns ”SPENKE”

14.2 current-directory-wildcard Function

Purpose: return wildcard for the current directory or a sensible alternative.

(defun current-directory-wildcard (&key (alternative :root)))

alternative: :root or :homedir The returned value is a pathname object. You can call this function. It is called by GINA sometimes.

14.3 directory-wildcard Function

Purpose: build a wildcard for the directory where the file is located.

(defun directory-wildcard (file-pathname &optional (file-type :wild)))

file-pathname: pathname object or string

The returned value is a pathname object. You can call this function. It is called by GINA in open/save dialogs.

Example

(directory-wildcard "w1:>gina>documents>four-rects.hello.3" "xxx")

returns #P”W1:>gina>documents>*.XXX.newest”

(directory-wildcard "w1:>gina>documents>four-rects.hello.3")

returns #P”W1:>gina>documents>*.*.newest”

(directory-wildcard "xpssun:/home/spenke/four-rects.hello")

returns #P”XPSSUN:/home/spenke/*”

14.4 subdirectory-wildcard Function

Purpose: build a wildcard for the directory this file denotes.

(defun subdirectory-wildcard (pathname &optional (file-type :wild)))

pathname: pathname object or string

The returned value is a pathname object. You can call this function. It is called by GINA in open/save dialogs.

Example

(subdirectory-wildcard "w1:>gina>documents.directory.1")

returns #P”W1:>gina>documents>*.*.newest”

(parent-directory-wildcard "xpssun:/GINA/documents/*.lisp")

returns #P”XPSSUN:/GINA/*.lisp”

(subdirectory-wildcard "w1:>gina>documents" "hello")

returns #P”W1:>gina>documents>*.HELLO.newest”

14.5 parent-directory-wildcard Function

Purpose: build a similar wildcard for the parent directory of this wildcard.

(defun parent-directory-wildcard (wildcard))

wildcard: pathname object or string

The returned value is a pathname object. You can call this function. It is called by GINA in open/save dialogs.

Example

(parent-directory-wildcard "w1:>gina>documents>*.*.newest")

returns #P”W1:>gina>*.*.newest”

14.6 parent-directory-wildcards Function

Purpose: build a list of wildcards for the parent directories.

(defun parent-directory-wildcards (pathname))

pathname: pathname object or string

The returned value is a list of pathname objects. You can call this function. It is called by GINA in open/save dialogs.

Example

(parent-directory-wildcards "w1:>gina>*.*.newest")

returns (#P”W1:>gina>*.*.newest” #P”W1:>*.*.newest”)

14.7 parent-directory Function

Purpose: build a pathname for the parent directory.

(defun parent-directory (pathname))

pathname: pathname object or string

The returned value is a pathname object. You can call this function. It is called by GINA in open/save dialogs.

Example

(parent-directory "w1:>gina>documents>*.*.newest")

returns #P”W1:>gina>documents.DIRECTORY”

14.8 parent-directories Function

Purpose: build a list of pathnames for the parent directories.

(defun parent-directories (pathname))

pathname: pathname object or string

The returned value is a list of pathname objects. You can call this function. It is called by GINA in open/save dialogs.

Example

(parent-directories "w1:>gina>documents>*.gredit.newest")

returns (#P”W1:>gina>documents.DIRECTORY” #P”W1:>gina.DIRECTORY”)

(parent-directories "w1:>*.gredit.newest")

returns nil

14.9 root-directory-p Function

Purpose: check if directory component denotes the root directory.

(defun root-directory-p (pathname))

pathname: pathname object or string

The returned value is T or NIL. You can call this function. It is called by GINA in open/save dialogs.

14.10 root-directory-wildcard Function

Purpose: build a wildcard for the root directory.

(defun root-directory-wildcard ())

The returned value is a pathname object. You can call this function. It is called by GINA in open/save dialogs.

14.11 directoryp Function

Purpose: check if pathname denotes a directory.

(defun directoryp (pathname))

pathname: pathname object or string

The returned value is T or NIL. You can call this function. It is called by GINA in open/save dialogs.

Example

(directoryp "w1:>mike.directory")

returns t

(directoryp "w1:>documents>four-rects.gredit.newest")

returns nil

(directoryp "tom:/home/spenke")

returns t

14.12 pathname-equal Function

Purpose: determine equality of two pathnames.

(defun pathname-equal (pathname1 pathname2))

The returned value is T or NIL. You can call this function. It is called by GINA in open/save dialogs.

Example

(pathname-equal
  "w1:>documents>four-rects.gredit.newest"
  "w1:>documents>four-rects.gredit.2")

returns t

(pathname-equal
  "W1:>DOCUMENTS>four-rects.GREDIT"
  "w1:>documents>four-rects.gredit.2")

returns t

(pathname-equal "W1:>DOCUMENTS>four-rects.GREDIT" nil)

returns nil

14.13 pathname-name< Function

Purpose: determine lexicographical order of the name component.

(defun pathname-name< (pathname1 pathname2))

You can call this function. It is called by GINA in open/save dialogs.

Example

(pathname-name< "/home/spenke/aaa.hello" "/home/spenke/bbb.hello")
(print (sort (directory "/home/spenke/") #'pathname-name<))

14.14 file-exists Function

Purpose: check if pathname denotes an existing file.

(defun file-exists (pathname))

The returned value is T or NIL. You can call this function. It is called by GINA in open/save dialogs.

Example

(file-exists "fdhgdfgfdg")

returns nil

14.15 replace-returns Function

Purpose: replace return for use in text widgets.

(defun replace-returns (string))

You can call this function. It is sometimes called by GINA.

14.16 unreplace-returns Function

Purpose: unreplace return for use in text widgets.

(defun unreplace-returns (string))

You can call this function. It is sometimes called by GINA.

14.17 find-bitmap Function

Purpose: search for a bitmap in gina:*bitmap-directories*.

(defun find-bitmap (bitmap-name &key (for-clm nil)))

for-clm: T if result is passed to CLM

The returned value is the absolute pathname as a string or bitmap-name when not found. You can call this function. It is called by GINA when setting label bitmaps. The second value (T or NIL) indicates whether found.

14.18 shell-command Function

Purpose: execute a string as a UNIX command.

(defun shell-command (command-string))

You can call this function. It is sometimes called by GINA.

Calling GINA Functions from the Editor

15.1 with-application-stopped Macro

Purpose: stop an application temporarily and use its connections

(defmacro with-application-stopped (&body body))

You can call this macro to execute some code from the editor. It is never called by GINA. Within the body you can use *application*, *display* and xtk:*motif-connection*. Using this macro, code to create and modify windows can be executed from the editor.

Example

(with-application-stopped
  (pop-up (make-modeless-dialog-box "Test Dialog" :resize t)))

pops up an empty dialog box

15.2 rotate-applications Function

Purpose: bring the next application to front of *running-applications*.

(defun rotate-applications ())

You can call this function to use another application by with-application-stopped. It is never called by GINA.

15.3 focus-application Function

Purpose: bring another application to front of *running-applications*.

(defun focus-application (&optional (number 1)))

You can call this function to set *application* or use another application by with-application-stopped. It is never called by GINA.

Example

(focus-application 3)

focusses on the third running application

15.4 defginapackage Macro

Purpose: define a new package using at least GINA and CL

(defmacro defginapackage (package &rest defpackage-options))

You can call this macro once at the beginning of your application. It is called by GINA only in the demo applications. This macro calls defpackage with implementation dependent parms.

Index

*application* (Variable), 15 *bitmap-directories* (Variable), 14 *clx-synchronous* (Variable), 16 *debug-menu* (Variable), 16 *default-display-host* (Variable), 14 *default-display-number* (Variable), 14 *default-screen-number* (Variable), 15 *default-toolkit-host* (Variable), 14 *display* (Variable), 15 *drag-n-drop-transfer-value* (Variable), 16 *inspect-click* (Variable), 16 *inspected-object* (Variable), 218 *loaded-applications* (Variable), 17 *running-applications* (Variable), 15

add-event-handler (Method), 119 add-menu-command (Method), 161 add-to-tab-group (Method), 124 alternative-dialog (Function), 216 application (Class), 19 arrow-button (Class), 153

basic-document-shell (Class), 140 bitmap-print (Method), 37 bulletin-board (Class), 194 button-entry (Class), 162 button-press (Method), 44, 63 button-press :around (Method), 43

callback (Class), 85 cascade-button (Class), 152 cleanup-actions (Method), 22 clear-area (Method), 46, 70 closed-by-wm (Method), 132, 138, 142, 202 command (Class), 88 command-executed (Method), 33 command-executed :after (Method), 33 commit (Method), 92 confirm-dialog (Function), 216 constrain-mouse (Method), 94, 101, 106 constrain-position (Method), 65 constrain-size (Method), 65 create-checkpoint (Method), 36 create-drop-command (Method), 38 create-handle-command (Method), 66 create-windows (Method), 29 current-directory-wildcard (Function), 223

defginapackage (Macro), 231 define-cursor (Method), 126 define-form-constraint (Function), 196 define-pane-constraint (Function), 182 deinstall (Method), 58 destroy (Method), 121, 132 destroy :before (Method), 141 destroy-windows (Method), 29 destroyed (Method), 42 determine-window-id (Method), 42 dialog-box (Class), 201 dialog-dismiss-button (Class), 211 dialog-dismiss-button-row (Class), 213 direct-manipulation-object (Class), 74 directory-wildcard (Function), 224 directoryp (Function), 227 display-empty (Method), 36 display-history-scroller (Method), 37 do-close (Method), 33 do-open (Method), 31 document (Class), 25 document-shell (Class), 142 document-shell-with-scroller (Class), 144 doit (Method), 90, 102, 108, 112 double-clicked (Method), 63 drag-command (Class), 113 drag-label (Class), 147 draw (Method), 46, 62, 82 draw :around (Method), 47 draw-arc (Method), 52, 72 draw-arcs (Method), 53, 72 draw-feedback (Method), 95, 101, 107, 111 draw-feedback :around (Method), 95 draw-glyph (Method), 53, 73 draw-glyphs (Method), 54, 74 draw-line (Method), 49, 68 draw-lines (Method), 50, 69 draw-outline (Method), 65, 83 draw-point (Method), 48, 67 draw-points (Method), 49, 68 draw-rectangle (Method), 51, 71 draw-rectangles (Method), 51, 71 draw-segments (Method), 50, 69 draw-selected (Method), 64, 83 draw-target-feedback (Method), 115

enclosing-shell (Method), 125, 129 executable (Method), 90 execute (Method), 87 execute-activate-callback (Method), 152, 154,

212 execute-value-changed-callback (Method), 150,

156, 158, 174, 187 expose (Method), 132

file-exists (Function), 228 find-bitmap (Function), 229 find-menu-entry (Method), 161 focus-application (Function), 231 force-redraw (Method), 45, 62 form (Class), 195 frame (Class), 180

get-clx-window (Method), 123 get-motif-resources (Method), 120 get-refresh-candidates (Method), 47

handle-button-press (Method), 43, 128 handle-error (Method), 23 handle-selection (Method), 67

idle-action (Method), 23 image->image-z (Method), 81 image->pixmap (Method), 82 in-background-process (Macro), 219 indicate-progress (Function), 222 initialize-instance :after (Method), 21, 28 insert-menu-entry (Method), 160 inside-rectangle (Method), 59 inspect-clicked (Method), 119 inspect-dialog (Function), 218 install (Method), 58 invalidate-rectangle (Method), 45, 61 irreversible-change (Method), 34

key-press (Method), 44 key-release (Method), 45 kill-all-background-processes (Method), 220 kill-background-process (Method), 219

label (Class), 146 labeled-frame (Class), 183 labeled-text (Class), 199 main-menu (Class), 159 main-window (Class), 176 make-application (Function), 21 make-arrow-button (Function), 154 make-basic-document-shell (Function), 141 make-bulletin-board (Function), 195 make-button-entry (Function), 163 make-callback (Function), 86 make-cascade-button (Function), 153 make-command (Function), 89 make-dialog-dismiss-button (Function), 212 make-dialog-dismiss-button-row (Function), 213 make-direct-manipulation-object (Function),

77 make-document-shell (Function), 144 make-document-shell-with-scroller (Function),

146 make-drag-command (Function), 114 make-drag-label (Function), 148 make-form (Function), 196 make-frame (Function), 181 make-label (Function), 147 make-labeled-frame (Function), 184 make-labeled-text (Function), 200 make-main-menu (Function), 160 make-main-window (Function), 176 make-menu-bar (Function), 172 make-menu-pulldown (Function), 175 make-menu-shell (Function), 139 make-modal-dialog-box (Function), 207 make-modal-dialog-shell (Function), 137 make-modeless-dialog-box (Function), 203 make-modeless-dialog-shell (Function), 135 make-mouse-down-command (Function), 94 make-movable-icon (Function), 80 make-object (Function), 16 make-object-mover (Function), 100 make-object-resizer (Function), 106 make-object-selector (Function), 111 make-open-dialog-box (Function), 217 make-option-menu (Function), 173 make-paned-window (Function), 181 make-push-button (Function), 151 make-radio-button-group (Function), 189 make-radio-group-entry (Function), 170 make-row-column (Function), 183 make-save-dialog-box (Function), 217 make-scale (Function), 156 make-scrollable-selection-list (Function), 194 make-scrollbar (Function), 158 make-scrolled-text (Function), 199 make-scroller (Function), 177 make-selection-list (Function), 191 make-separator (Function), 180 make-shell (Function), 127 make-text (Function), 198 make-toggle-button (Function), 149 make-toggle-button-group (Function), 185 make-toggle-entry (Function), 165 make-toggle-group-entry (Function), 167 make-tool-dialog-box (Function), 210 make-toplevel-shell (Function), 131 make-view (Function), 41 make-view-object (Function), 57 make-widget (Function), 118 manage (Method), 121 menu-bar (Class), 171 menu-entry (Class), 162 menu-pulldown (Class), 175 menu-shell (Class), 138 minifinder (Method), 31 modal-dialog-box (Class), 205 modal-dialog-shell (Class), 136 modeless-dialog-box (Class), 202 modeless-dialog-shell (Class), 133 more-initargs (Macro), 120 more-motif-resources (Macro), 121 mouse-down-command (Class), 92 mouse-idle (Method), 97 mouse-rectangle (Method), 98 movable-icon (Class), 77 move (Method), 60, 122

name-and-type (Function), 223 new (Method), 31 not-submitted (Method), 97, 112, 116

object-mover (Class), 98 object-resizer (Class), 103 object-selector (Class), 109 option-menu (Class), 172

paned-window (Class), 181 parent-directories (Function), 226 parent-directory (Function), 226 parent-directory-wildcard (Function), 225 parent-directory-wildcards (Function), 225 pathname->image (Method), 81 pathname-equal (Function), 228 pathname-name< (Function), 228 point-inside (Method), 59, 84, 124 point-inside-rectangle (Macro), 59 point-visible (Method), 179 pop-down (Method), 129, 136, 205, 208, 211 pop-up (Method), 128, 135, 204, 207, 210 pop-up :after (Method), 131 postscript-print (Method), 37 print-object (Method), 21, 28, 85 print-parms (Function), 86 progress-bar-aborted (Function), 221 push-button (Class), 150

question-dialog (Function), 215

quit-app (Method), 24

radio-button-group (Class), 187 radio-group-entry (Class), 169 read-from-file (Method), 35 read-from-stream (Method), 36 read-header-from-stream (Method), 35 reconfigure (Method), 61 reconfigured-by-user (Method), 66 rectangles-overlap (Function), 60 redo (Method), 34 redoit (Method), 91, 103, 108 redraw-views (Method), 30 register-application (Function), 17 remove-from-tab-group (Method), 124 remove-menu-entry (Method), 161 rename (Method), 30 replace-returns (Function), 229 replay-history (Method), 34 resize (Method), 60, 123 resize-windows (Method), 30 resized (Method), 48 resized-by-user (Method), 131 restart-timer (Method), 23 restore-checkpoint (Method), 37 revert (Method), 32 root-coordinates (Method), 123 root-directory-p (Function), 226 root-directory-wildcard (Function), 227 rotate-applications (Function), 230 row-column (Class), 182

save (Method), 32 save-as (Method), 32 scale (Class), 155 scroll-before-redo (Method), 91, 97 scroll-before-undo (Method), 90 scroll-to (Method), 178 scrollable-selection-list (Class), 193 scrollbar (Class), 157 scrolled-text (Class), 198 scroller (Class), 177 select-dialog (Function), 217 select-new-file (Method), 29 select-old-file (Method), 31 selection-list (Class), 190 send-message (Method), 24 separator (Class), 179 set-item-list (Method), 168, 170, 173, 186,

189, 192 set-keyboard-focus (Method), 125 set-motif-resources (Method), 120 set-sensitivity (Method), 125 setf acc-modifier :after (Method), 164 setf accelerator :after (Method), 164 setf default-button :after (Method), 204, 207 setf idle-timeout :after (Method), 23 setf label-position :after (Method), 201 setf label-string :after (Method), 164 setf modified :before (Method), 28 setf selected (Method), 64 setf sensitive :after (Method), 162 setf value :after (Method), 165, 175, 191 setf value :before (Method), 168, 186 setf view-objects :after (Method), 48 shell (Class), 126 shell-command (Function), 229 show-item (Method), 193 show-point (Method), 179 son-created (Method), 119, 178 standard-menu-items (Method), 29 start-file (Function), 18 startup-actions (Method), 22 subdirectory-wildcard (Function), 224 submit (Method), 89

test-callback (Method), 38 text (Class), 197 toggle-button (Class), 148 toggle-button-group (Class), 184 toggle-entry (Class), 164 toggle-group-entry (Class), 166 tool-dialog-box (Class), 208 toplevel-shell (Class), 129 track-mouse (Method), 96, 102, 107 track-target (Method), 115

undo (Method), 34 undoit (Method), 91, 103, 108 unmanage (Method), 122 unreplace-returns (Function), 229 update-slots (Method), 122

view (Class), 39 view-object (Class), 55

warning-dialog (Function), 215 which-resize-handle (Method), 66 widget (Class), 117 with-application (Macro), 220 with-application-stopped (Macro), 230 with-clm-connection (Macro), 220 with-clock-cursor (Macro), 133 with-cursor (Macro), 133 with-document (Macro), 220 with-progress-bar (Macro), 221 write-header-to-stream (Method), 35 write-to-file (Method), 35 write-to-stream (Method), 36

xor-foreground (Method), 42