aboutsummaryrefslogtreecommitdiffhomepage
path: root/src/events/event-handler.lisp
diff options
context:
space:
mode:
authorColin Okay <colin@cicadas.surf>2022-07-08 11:00:07 -0500
committerColin Okay <colin@cicadas.surf>2022-07-08 11:00:07 -0500
commit8bf0e572ee084e6659f56b2fecd44a54e2775b6c (patch)
tree5c7324babdd7007f9bd6865f2cb4c3390f47c40c /src/events/event-handler.lisp
parentdd354e5caee002be931501062bf3aaa68f1d63e6 (diff)
[docs] added docstrings to exports
Diffstat (limited to 'src/events/event-handler.lisp')
-rw-r--r--src/events/event-handler.lisp147
1 files changed, 120 insertions, 27 deletions
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