From ddf57d433426812b432a46d65f4c583ed70b7bdf Mon Sep 17 00:00:00 2001 From: David Botton Date: Fri, 22 Jan 2021 12:25:16 -0500 Subject: [PATCH] Start on internal docs --- clog-base.lisp | 6 +- clog-docs.lisp | 60 ++++++++++++++++++- clog-element.lisp | 2 +- clog-window.lisp | 2 +- clog.lisp | 4 +- doc/clog-manual.html | 140 +++++++++++++++++++++++++++++++++++++++++-- 6 files changed, 201 insertions(+), 13 deletions(-) diff --git a/clog-base.lisp b/clog-base.lisp index b21d575..cfbaf7a 100644 --- a/clog-base.lisp +++ b/clog-base.lisp @@ -107,7 +107,7 @@ result. (Private)")) ;;;;;;;;;;;;; (defgeneric execute (clog-obj method) - (:documentation "Execute the js METHOD on OBJ. Result is + (:documentation "Execute the JavaScript METHOD on OBJ. Result is dicarded. (Private)")) (defmethod execute ((obj clog-obj) method) @@ -119,7 +119,7 @@ dicarded. (Private)")) ;;;;;;;;;;; (defgeneric query (clog-obj method) - (:documentation "Execute the js query METHOD on OBJ and return + (:documentation "Execute the JavaScript query METHOD on OBJ and return result. (Private)")) (defmethod query ((obj clog-obj) method) @@ -788,7 +788,7 @@ ON-TOUCH-CANCEL-HANDLER is nil unbind the event.")) (defgeneric set-on-character (clog-obj on-character-handler) (:documentation "Set the ON-CHARACTER-HANDLER for CLOG-OBJ. If ON-CHARACTER-HANDLER is nil unbind the event. Setting this event -will replace a on-key-press")) +will replace a on-key-down")) (defmethod set-on-character ((obj clog-obj) handler) (set-event obj "keypress" diff --git a/clog-docs.lisp b/clog-docs.lisp index 49723dc..bafb206 100644 --- a/clog-docs.lisp +++ b/clog-docs.lisp @@ -56,7 +56,7 @@ regulary with SCBL on Linux, Windows and Intel MacBook. It should in theory work on any system QuickLisp and CLACK will load on to. CLOG will be in QuickSlip in the next update, but a good idea, -since I am still adding code daily, is to cloan the github repo +since I am still adding code daily, is to clone the github repo in to your ~/common-lisp directory: ``` @@ -79,3 +79,61 @@ Work your way through the tutorials. You will see how quick and easy it is to be a CLOGer. ") + +(defsection @clog-internals (:title "CLOG Framework internals and extensions") +"## Responding to new java script DOM events: + +If there is no data for the event just changing the name of the event is +sufficient in this example: + +```lisp +(defmethod set-on-click ((obj clog-obj) handler) + (set-event obj \"click\" + (when handler + (lambda (data) + (declare (ignore data)) + (funcall handler obj))))) +``` + +If there is data for the event an additional string containing the needed +java-script to return the even data and a function to parse out the data. + +Replace the event name with the correct name, parse-keyboard-even with the +parse function and the string containing the needed JavaScrip replaces +keyboard-event-script: + +* The event handlers setter + +```lisp +(defmethod set-on-key-down ((obj clog-obj) handler) + (set-event obj \"keydown\" + (when handler + (lambda (data) + (funcall handler obj (parse-keyboard-event data)))) + :call-back-script keyboard-event-script)) +``` + +* The script + +```lisp +(defparameter keyboard-event-script + \"+ e.keyCode + ':' + e.charCode + ':' + e.altKey + ':' + e.ctrlKey + ':' + + e.shiftKey + ':' + e.metaKey\") +``` + +* The event parser + +```lisp +(defun parse-keyboard-event (data) + (let ((f (ppcre:split \":\" data))) + (list + :event-type :keyboard + :key-code (parse-integer (nth 0 f) :junk-allowed t) + :char-code (parse-integer (nth 1 f) :junk-allowed t) + :alt-key (js-true-p (nth 2 f)) + :ctrl-key (js-true-p (nth 3 f)) + :shift-key (js-true-p (nth 4 f)) + :meta-key (js-true-p (nth 5 f))))) +``` + +") diff --git a/clog-element.lisp b/clog-element.lisp index b6ddb64..49603e7 100644 --- a/clog-element.lisp +++ b/clog-element.lisp @@ -1617,7 +1617,7 @@ A list of standard cursor types can be found at: ;;;;;;;;;;;;;;;;;;;;; (defgeneric remove-from-dom (clog-element) - (:documentation "remove-from-dom.")) + (:documentation "Remove CLOG-Element from the DOM.")) (defmethod remove-from-dom ((obj clog-element)) (jquery-execute obj "remove()")) diff --git a/clog-window.lisp b/clog-window.lisp index 54ea8ab..1e4eccb 100644 --- a/clog-window.lisp +++ b/clog-window.lisp @@ -495,7 +495,7 @@ on-storage event is fired for changes to :local storage keys.")) ;; storage-length ;; ;;;;;;;;;;;;;;;;;;;; -(deftype storage-type '(member local session)) +(deftype storage-type () '(member local session)) (defgeneric storage-length (clog-window storage-type) (:documentation "Number of entries in browser STORAGE-TYPE. diff --git a/clog.lisp b/clog.lisp index 9093b77..c16a0ff 100644 --- a/clog.lisp +++ b/clog.lisp @@ -39,7 +39,8 @@ embedded in a native template application.)" (@clog-window section) (@clog-document section) (@clog-location section) - (@clog-navigator section)) + (@clog-navigator section) + (@clog-internals section)) (defsection @clog-system (:title "CLOG System") "CLOG Startup and Shutdown" @@ -471,6 +472,7 @@ embedded in a native template application.)" (scroll-to generic-function) (close-window generic-function) (close-connection generic-function) + (storage-type type) (storage-length generic-function) (storage-key generic-function) (storage-remove generic-function) diff --git a/doc/clog-manual.html b/doc/clog-manual.html index 425f7c4..69590a6 100644 --- a/doc/clog-manual.html +++ b/doc/clog-manual.html @@ -47,6 +47,7 @@
  • 11 CLOG Document Objects
  • 12 CLOG Location Objects
  • 13 CLOG Navigator Objects
    • +
  • 14 CLOG Framework internals and extensions
    • [in package CLOG]
    @@ -103,6 +104,33 @@ an active soft realtime connection. For most CLOG applications all programming logic, events and decisions are done on the server which can be local or remote over the web.

    +

    CLOG is developed on an M1 MacBook with ECL, it is tested fairly +regulary with SCBL on Linux, Windows and Intel MacBook. It should +in theory work on any system QuickLisp and CLACK will load on to.

    + +

    CLOG will be in QuickSlip in the next update, but a good idea, +since I am still adding code daily, is to clone the github repo +in to your ~/common-lisp directory:

    + +
    cd ~/common-lisp
+git clone https://github.com/rabbibotton/clog.git
    + +

    To load this package and work through tutorials (assuming you +have QuickSlip configured):

    + +
      +

    1. cd to the CLOG dir (the dir should be one used by QuickLisp ex. ~/common-lisp/)

      2. +

    2. Start emacs/slime or your common lisp "repl" in that directory.

      3. +

    3. In the REPL run:

      4. +
    + +

    CL-USER> (ql:quickload :clog) +CL-USER> (load "~/common-lisp/clog/tutorial/01-tutorial.lisp") +CL-USER> (clog-user:start-tutorial)

    + +

    Work your way through the tutorials. You will see how quick and easy it is +to be a CLOGer.

    +

    ← ↑ → ↺

    @@ -568,7 +596,7 @@ is nil unbind the event.

    Set the ON-CHARACTER-HANDLER for CLOG-OBJ. If ON-CHARACTER-HANDLER is nil unbind the event. Setting this event -will replace a on-key-press

    +will replace a on-key-down

    @@ -1594,7 +1622,7 @@ A list of standard cursor types can be found at:

    @@ -3134,6 +3162,47 @@ events and messages may not be trasmitted on most browsers.

    Close connection to browser with out closing browser.

    +

    + + + +

    + + + +

    + + + +

    + + + +

    + + +

    CLOG-Window - Events

    @@ -3186,8 +3255,8 @@ If ON-ORIENTATION-CHANGE-HANDLER is nil unbind the event.

    @@ -3451,7 +3520,7 @@ If ON-ORIENTATION-CHANGE-HANDLER is nil unbind the event.

    @@ -3474,7 +3543,7 @@ If ON-ORIENTATION-CHANGE-HANDLER is nil unbind the event.

    -

    ← ↑ ↺

    +

    ← ↑ → ↺

    13 CLOG Navigator Objects

    @@ -3521,6 +3590,65 @@ If ON-ORIENTATION-CHANGE-HANDLER is nil unbind the event.

    Get browser vendor.

    + +

    + +

    ← ↑ ↺

    + +

    14 CLOG Framework internals and extensions

    + +

    Responding to new java script DOM events:

    + +

    If there is no data for the event just changing the name of the event is +sufficient in this example:

    + +
    (defmethod set-on-click ((obj clog-obj) handler)
+  (set-event obj "click"
+         (when handler
+           (lambda (data)
+         (declare (ignore data))
+         (funcall handler obj)))))
    + +

    If there is data for the event an additional string containing the needed +java-script to return the even data and a function to parse out the data.

    + +

    Replace the event name with the correct name, parse-keyboard-even with the +parse function and the string containing the needed JavaScrip replaces +keyboard-event-script:

    + + + +
    (defmethod set-on-key-down ((obj clog-obj) handler)
+  (set-event obj "keydown"
+         (when handler
+           (lambda (data)
+         (funcall handler obj (parse-keyboard-event data))))
+         :call-back-script keyboard-event-script))
    + + + +
    (defparameter keyboard-event-script
+  "+ e.keyCode + ':' + e.charCode + ':' + e.altKey + ':' + e.ctrlKey + ':' +
+     e.shiftKey + ':' + e.metaKey")
    + + + +
    (defun parse-keyboard-event (data)
+  (let ((f (ppcre:split ":" data)))
+    (list
+     :event-type :keyboard
+     :key-code   (parse-integer (nth 0 f) :junk-allowed t)
+     :char-code  (parse-integer (nth 1 f) :junk-allowed t)
+     :alt-key    (js-true-p (nth 2 f))
+     :ctrl-key   (js-true-p (nth 3 f))
+     :shift-key  (js-true-p (nth 4 f))
+     :meta-key   (js-true-p (nth 5 f)))))