From 8bf0e572ee084e6659f56b2fecd44a54e2775b6c Mon Sep 17 00:00:00 2001 From: Colin Okay Date: Fri, 8 Jul 2022 11:00:07 -0500 Subject: [docs] added docstrings to exports --- src/application.lisp | 25 +++++-- src/events/event-handler.lisp | 147 ++++++++++++++++++++++++++++++++++-------- src/interactive/sprite.lisp | 3 +- src/package.lisp | 6 +- src/protocol.lisp | 18 ++++-- 5 files changed, 154 insertions(+), 45 deletions(-) diff --git a/src/application.lisp b/src/application.lisp index d2da8ef..c4ad9b0 100644 --- a/src/application.lisp +++ b/src/application.lisp @@ -4,21 +4,31 @@ (defclass/std application (container interactive) - ((title :with :std "Wheelwork App") + ((title :with :ri :std "Wheelwork App") (asset-root :ri :std #P"./" :doc "Directory under which assets are stored.") (asset-classifiers :std '(("png" png) ("ttf" font)) :doc "ALIST of (EXT CLASS). EXT is a string, file estension. CLASS is a symbol, class name.") (assets :with :a :std (make-hash-table :test 'equal) :doc "maps asset names to asset instances.") - (scale :with :std 1.0) - (width height :with :std 800) + (scale :with :std 1.0 + :doc "Scale factor applied before all + rendering. Affects sizes of all object as well as the + coordinates of mouse events.") + (width height :with :std 800 :doc "Window dimensions in real pixels.") (projection :with :a :doc "The projection matrix for the scene. Orthographic by default.") (window :with :a) - (refocus-on-mousedown-p :std t) + (refocus-on-mousedown-p + :std t + :doc "When T, clicking on a visible object will set the + application focus to that object.") (focus last-motion-target :with :a) (fps :std 30 :doc "Frames Per Second") - (frame-wait :r))) + (frame-wait :r)) + (:documentation "The application contains the information and data + structures necessary for creating a window, adding display units to + it, handling events, and loading resources. You should sublcass + this and write your own BOOT method.")) (defun can-set-projection-p (app) (and (slot-boundp app 'width) @@ -38,8 +48,9 @@ left 0 bottom 0 top (/ height scale) - right (/ width scale) - ))) + right (/ width scale)))) + + (defun fire-blur-event-on (thing) (when-let (blur-handlers (and thing (get-handlers-for thing 'blur))) diff --git a/src/events/event-handler.lisp b/src/events/event-handler.lisp index c8b83d0..a7f1b1b 100644 --- a/src/events/event-handler.lisp +++ b/src/events/event-handler.lisp @@ -27,7 +27,16 @@ can be redefined using this form to support interactive development." (defmacro on-perframe ((&optional (target 'target) (time 'time)) &body body) - "Creates a handler for 'PERFRAME events" + "Creates a handler for 'PERFRAME events. + + All variable arguments supplied to this handler form are + optional. You may supply your own variables to use in your BODY or + you may just refer to the defaults - they will be interned in the + appropriate package. + + TARGET - the object currently handling the event + TIME - The current time in milliseconds +" `(make-instance 'event-handler :event-type 'wheelwork::perframe @@ -40,12 +49,19 @@ can be redefined using this form to support interactive development." (defmacro on-keydown ((&optional (target 'target) (scancode 'scancode) (modifiers 'modifiers)) &body body) "Creates a lambda suitable for the value of a keydown event - handler. The function accepts two positional arguments TARGET and - SCANCODE and one &REST argument MODIFIERS. + handler. - SCANCODE will be a keyword of the form :SCANCODE-A, :SCANCODE-B ... + All variable arguments supplied to this handler form are + optional. You may supply your own variables to use in your BODY or + you may just refer to the defaults - they will be interned in the + appropriate package. - The members of MODIFIERS look like :LSHIFT, :RCTRL, RALT, etc" + The function accepts two positional arguments TARGET and SCANCODE and + one &REST argument MODIFIERS. + + SCANCODE will be a keyword of the form :SCANCODE-A, :SCANCODE-B ... + + The members of MODIFIERS look like :LSHIFT, :RCTRL, RALT, etc" `(make-instance 'event-handler :event-type 'wheelwork::keydown @@ -60,7 +76,15 @@ can be redefined using this form to support interactive development." (defmacro on-keyup ((&optional (target 'target) (scancode 'scancode) (modifiers 'modifiers)) &body body) "Creates a lambda suitable for the value of a keyup event - handler. The function accepts two positional arguments TARGET and + handler. + + All variable arguments supplied to this handler form are + optional. You may supply your own variables to use in your BODY or + you may just refer to the defaults - they will be interned in the + appropriate package. + + + The function accepts two positional arguments TARGET and SCANCODE and one &REST argument MODIFIERS. SCANCODE will be a keyword of the form :SCANCODE-A, :SCANCODE-B ... @@ -86,18 +110,19 @@ can be redefined using this form to support interactive development." (win-x 'win-x) (win-y 'win-y) (win-xrel 'win-xrel) (win-yrel 'win-yrel)) &body body) - "ON-MOUSEMOTION defines a mouse motion event handler. All -variable arguments supplied the the ON-MOUSEDOWN handler form are -optional. You may supply your own variables to use in your BODY or you -may just refer to the defaults - they will be interned in the -appropriate package. - -- TARGET is the object ontowhich the handler was installed -- X and Y are the scaled screen coordinates -- XREL and YREL are the relative motion of the X and Y positions since - the last event, in scaled coordinates -- STATE is the button state, see the SDL2 docs -- WIN-* variables are the unscaled event values, if you require them. + "ON-MOUSEMOTION defines a mouse motion event handler. + + All variable arguments supplied to this handler form are optional. You + may supply your own variables to use in your BODY or you may just + refer to the defaults - they will be interned in the appropriate + package. + + - TARGET is the object ontowhich the handler was installed + - X and Y are the scaled screen coordinates + - XREL and YREL are the relative motion of the X and Y positions since + the last event, in scaled coordinates + - STATE is the button state, see the SDL2 docs + - WIN-* variables are the unscaled event values, if you require them. " `(make-instance @@ -131,7 +156,19 @@ appropriate package. (clicks 'clicks) (button 'button) (win-x 'win-x) (win-y 'win-y)) &body body) - "Creates a handler for MOUSEDOWN events" + "Creates a handler for MOUSEDOWN events. + + All variable arguments supplied to this handler form are + optional. You may supply your own variables to use in your BODY or + you may just refer to the defaults - they will be interned in the + appropriate package. + + - TARGET is the object ontowhich the handler was installed + - X and Y are the scaled screen coordinates + - BUTTON is a code for the mouse button pressed (see sdl docs) + - CLICKS is the number of clicks 1 for single, 2 for double. + - WIN-* variables are the unscaled event values, if you require them. +" `(make-instance 'event-handler :event-type 'wheelwork::mousedown @@ -159,7 +196,20 @@ appropriate package. (clicks 'clicks) (button 'button) (win-x 'win-x) (win-y 'win-y)) &body body) - "Creates a handler for MOUSEUP events" + "Creates a handler for MOUSEUP events + + All variable arguments supplied to this handler form are + optional. You may supply your own variables to use in your BODY or + you may just refer to the defaults - they will be interned in the + appropriate package. + + - TARGET is the object ontowhich the handler was installed + - X and Y are the scaled screen coordinates + - BUTTON is a code for the mouse button pressed (see sdl docs) + - CLICKS is the number of clicks 1 for single, 2 for double. + - WIN-* variables are the unscaled event values, if you require them. + +" `(make-instance 'event-handler :event-type 'wheelwork::mouseup @@ -183,7 +233,18 @@ appropriate package. (defmacro on-mousewheel ((&optional (target 'target) (horiz 'horiz) (vert 'vert) (dir 'dir)) &body body) - "Creates a handler for MOUSEWHEEL events" + "Creates a handler for MOUSEWHEEL events + + All variable arguments supplied to this handler form are + optional. You may supply your own variables to use in your BODY or + you may just refer to the defaults - they will be interned in the + appropriate package. + + - TARGET is the object ontowhich the handler was installed + - HORIZ, VERT are 1 or -1 + - DIR is normal or flipped, see https://wiki.libsdl.org/SDL_MouseWheelEvent + +" `(make-instance 'event-handler :event-type 'wheelwork::mousewheel @@ -202,7 +263,14 @@ appropriate package. (defmacro on-blur ((&optional (target 'target)) &body body) "Creates a handler for BLUR events. BLUR is a psuedo event that -fires whenever an object loses focus." +fires whenever an object loses focus. + + All variable arguments supplied to this handler form are + optional. You may supply your own variables to use in your BODY or + you may just refer to the defaults - they will be interned in the + appropriate package. + +" `(make-instance 'event-handler :event-type 'wheelwork::blur @@ -216,6 +284,12 @@ fires whenever an object loses focus." ((&optional (target 'target)) &body body) "Creates a handler for a FOCUS event. FOCUS is a pusedo event that fires when the FOCUS slot of the current APPLICATION instance is changed. + + All variable arguments supplied to this handler form are + optional. You may supply your own variables to use in your BODY or + you may just refer to the defaults - they will be interned in the + appropriate package. + " `(make-instance 'event-handler @@ -229,7 +303,14 @@ fires when the FOCUS slot of the current APPLICATION instance is changed. (defmacro on-before-dropped ((&optional (target 'target)) &body body) "Creates a handler for BEFORE-DROPPED events, which fire before a - unit is removed from its container." + unit is removed from its container. + + All variable arguments supplied to this handler form are + optional. You may supply your own variables to use in your BODY or + you may just refer to the defaults - they will be interned in the + appropriate package. + +" `(make-instance 'event-handler :event-type 'wheelwork::before-dropped @@ -240,9 +321,15 @@ fires when the FOCUS slot of the current APPLICATION instance is changed. ,@body))) (defmacro on-before-added - ((&optional (container 'container) (target 'target)) &body body) + ((&optional (target 'target) (container 'container)) &body body) "Creates a handler for BEFORE-ADDED events, which fire before a unit - is added to a container." + TARGET is added to CONTAINER. + + All variable arguments supplied to this handler form are + optional. You may supply your own variables to use in your BODY or + you may just refer to the defaults - they will be interned in the + appropriate package. +" `(make-instance 'event-handler :event-type 'wheelwork::before-added @@ -257,9 +344,15 @@ fires when the FOCUS slot of the current APPLICATION instance is changed. (defmacro on-after-added - ((&optional (container 'container) (target 'target)) &body body) + ((&optional (target 'target) (container 'container)) &body body) "Creates a handler for AFTER-ADDED events, which fire after a unit - is added to a container." + is added to a container. + + All variable arguments supplied to this handler form are + optional. You may supply your own variables to use in your BODY or + you may just refer to the defaults - they will be interned in the + appropriate package. +" `(make-instance 'event-handler :event-type 'wheelwork::after-added diff --git a/src/interactive/sprite.lisp b/src/interactive/sprite.lisp index e478d37..22c6be4 100644 --- a/src/interactive/sprite.lisp +++ b/src/interactive/sprite.lisp @@ -4,9 +4,10 @@ (defclass/std sprite (unit interactive) ((framesets :with :doc "A PLIST whose values are framesets.") - (frameset-key :with))) + (frameset-key :with :doc "The current name of the frameset being displayed."))) (defun current-frameset (sprite) + "Returns the current FRAMESET instance being displayed on SRPITE." (getf (sprite-framesets sprite) (sprite-frameset-key sprite))) diff --git a/src/package.lisp b/src/package.lisp index 5258d78..29093db 100644 --- a/src/package.lisp +++ b/src/package.lisp @@ -51,9 +51,6 @@ ;; Event Handler API #:add-handler - #:after-added - #:before-added - #:before-dropped #:defhandler #:on-after-added #:on-before-added @@ -68,7 +65,8 @@ #:on-perframe #:remove-handler - ;; Event Names + ;; Event Names, useful for dropping whole classes of events from a + ;; unit #:after-added #:before-added #:before-dropped diff --git a/src/protocol.lisp b/src/protocol.lisp index df3c170..002aad6 100644 --- a/src/protocol.lisp +++ b/src/protocol.lisp @@ -46,17 +46,23 @@ (defgeneric (setf height) (new-height thing) (:documentation "sets the effective height of thing to new-height")) -(defgeneric rotation (thing)) +(defgeneric rotation (thing) + (:documentation "Rotational angle of thing in radians about its center.")) (defgeneric (setf rotation) (newval thing)) -(defgeneric x (thing)) +(defgeneric x (thing) + (:documentation "X position of the bottom left corner in scaled coordinates")) (defgeneric (setf x) (newval thing)) -(defgeneric y (thing)) +(defgeneric y (thing) + (:documentation "Y position of bottom left corner in scaled coordinates")) (defgeneric (setf y) (newval thing)) -(defgeneric scale-x (thing)) +(defgeneric scale-x (thing) + (:documentation "Horizontal scale factor")) (defgeneric (setf scale-x) (newvval thing)) -(defgeneric scale-y (thing)) +(defgeneric scale-y (thing) + (:documentation "Vertical Scale Vactor")) (defgeneric (setf scale-y) (newval thing)) + (defgeneric get-rect (affine) (:documentation "Returns a list of vectors representing the path of the smallest rectangle that encloses the affine-unit. The rectangle - is scaled and rotated.")) + is scaled and rotated. These vectors have been made using 3D-VECTORS:VEC")) -- cgit v1.2.3