From 8ac1508f76b63d9db8596587486b30ad76516ee3 Mon Sep 17 00:00:00 2001 From: David Botton Date: Sun, 24 Jan 2021 01:41:17 -0500 Subject: [PATCH] doc updates --- README.md | 8 +-- clog-base.lisp | 2 +- clog-docs.lisp | 101 ++++++++++++++++++++------- clog-window.lisp | 7 +- clog.lisp | 4 +- doc/clog-manual.html | 160 +++++++++++++++++++++++++++++-------------- 6 files changed, 199 insertions(+), 83 deletions(-) diff --git a/README.md b/README.md index 7d11cc0..afcd179 100644 --- a/README.md +++ b/README.md @@ -17,10 +17,10 @@ connectivity to the browser or other websocket client (often a browser embedded in a native template application.) STATUS: CLOG is complete enough for most uses. While there are loose -ends (multimedia, client-side storage, database integrations), -CLOG is actually based on GNOGA, a framework I wrote for Ada in -2013 and used in commercial production code for the last 6 years, -i.e. the techiniques CLOG uses are solid and proven. +ends (multimedia, database integrations), CLOG is actually based on +GNOGA, a framework I wrote for Ada in 2013 and used in commercial +production code for the last 6 years, i.e. the techiniques CLOG uses +are solid and proven. Some potential applications for CLOG: diff --git a/clog-base.lisp b/clog-base.lisp index cfbaf7a..2853b20 100644 --- a/clog-base.lisp +++ b/clog-base.lisp @@ -45,7 +45,7 @@ lisp and the HTML DOM element.")) ;;;;;;;;;;;;;;;;;;;;;;;;;;; (defgeneric connection-data-mutex (clog-obj) - (:documentation "Preader for connection-data thread lock. (Private)")) + (:documentation "Reader for connection-data thread lock. (Private)")) ;;;;;;;;;;;;;;;;;;; ;; make-clog-obj ;; diff --git a/clog-docs.lisp b/clog-docs.lisp index 5da0f2d..4830cd1 100644 --- a/clog-docs.lisp +++ b/clog-docs.lisp @@ -13,51 +13,56 @@ ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;; (defsection @clog-getting-started (:title "CLOG Getting Started") -" -# CLOG - The Common Lisp Omnificent GUI +"# CLOG - The Common Lisp Omnificent GUI ## David Botton -### License BSD 3-Clause License +License BSD 3-Clause License -The Common Lisp Omnificient GUI, CLOG for short, uses web technology to +View the HTML Documentation: + +https://rabbibotton.github.io/clog/clog-manual.html + +### Introduction + +The Common Lisp Omnificent GUI, CLOG for short, uses web technology to produce graphical user interfaces for applications locally or remotely. -CLOG can take the place, or work along side, most cross platform GUI +CLOG can take the place, or work alongside, most cross-platform GUI frameworks and website frameworks. The CLOG package starts up the connectivity to the browser or other websocket client (often a browser embedded in a native template application.) -STATUS: CLOG is complete enough for most uses, there are a few loose -ends (multimedia, client side storage, integrations with databases), -but CLOG is actually based on a framework I wrote for Ada, GNOGA, in -2013 and used in commercial production code for the last 6 years, -i.e. the techiniques it uses are solid and proven. +STATUS: CLOG is complete enough for most uses. While there are loose +ends (multimedia, database integrations), CLOG is actually based on +GNOGA, a framework I wrote for Ada in 2013 and used in commercial +production code for the last 6 years, i.e. the techiniques CLOG uses +are solid and proven. -Some of the things CLOG can be used for: +Some potential applications for CLOG: -* Cross platform GUIs and Reports +* Cross-platform GUIs and Reports * Secure websites and complex interactive web applications -* Write mobile software -* Write massive multiplayer online games +* Mobile software +* Massive multiplayer online games * Monitoring software for embedded systems -* A fun way to teaching programming and advanced multi-tasking +* A fun way to teach programming and advanced multi-tasking parallel programming techniques. (CLOG is a parallel GUI) * And the list goes on The key to CLOG is the relationship it forms with a Browser window or Browser control compiled to native code. CLOG uses websockets -for communications and the browser to render a GUI that maintanes +for communications and the browser to render a GUI that maintains 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. +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: +CLOG will be in Quicklisp in the next update, but because I am still +adding code daily, it is currently preferable to clone the github repo +into your ~/common-lisp directory: ``` cd ~/common-lisp @@ -65,11 +70,11 @@ git clone https://github.com/rabbibotton/clog.git ``` To load this package and work through tutorials (assuming you -have QuickSlip configured): +have Quicklisp configured): -1. cd to the CLOG dir (the dir should be one used by QuickLisp ex. ~/common-lisp/) +1. cd to the CLOG dir (the dir should be one used by Quicklisp ex. ~/common-lisp/) 2. Start emacs/slime or your common lisp \"repl\" in _that_ directory. -3. In the REPL run: +3. In the REPL, run: CL-USER> (ql:quickload :clog) CL-USER> (load \"~/common-lisp/clog/tutorial/01-tutorial.lisp\") @@ -80,6 +85,56 @@ to be a CLOGer. ") +(defsection @clog-event-data (:title "CLOG Event Data") +" +Some events in CLOG return in addition to the target event, event data. +The data is passed in the second argument to the event handler as a +property list. To retrieve the data use (getf data :property) the available +properties (to use for :property) are based on the event type. + +From clog-base + + :event-type :mouse + :x x relative to the target + :y y relative to the target + :screen-x x relative to the users screen + :screen-y y relative to the users screen + :which-button which mouse button clicked + :alt-key t or nil if alt-key held down + :ctrl-key t or nil if ctrl-key held down + :shift-key t or nil if shift-key held down + :meta-key t or nil if meta-key held down + + + :event-type :touch + :x x relative to the target + :y y relative to the target + :screen-x x relative to the users screen + :screen-y y relative to the users screen + :number-fingers number of fingers being used + :alt-key t or nil if alt-key held down + :ctrl-key t or nil if ctrl-key held down + :shift-key t or nil if shift-key held down + :meta-key t or nil if meta-key held down + + :event-type :keyboard + :key-code A key code sometimes called a scan code for the key pressed + :char-code UTF-8 representation for key pressed when possible + :alt-key t or nil if alt-key held down + :ctrl-key t or nil if ctrl-key held down + :shift-key t or nil if shift-key held down + :meta-key t or nil if meta-key held down + +From clog-window + + :event-type :storage + :key local storage key that was updated (even in another window) + :old-value old key value + :value new key value + + +") + (defsection @clog-internals (:title "CLOG Framework internals and extensions") "## Responding to new java script DOM events diff --git a/clog-window.lisp b/clog-window.lisp index 1e4eccb..525707a 100644 --- a/clog-window.lisp +++ b/clog-window.lisp @@ -476,9 +476,10 @@ If ON-ORIENTATION-CHANGE-HANDLER is nil unbind the event.")) (defun parse-storage-event (data) (let ((f (ppcre:split ":" data))) (list - :key (quri:url-decode (nth 0 f)) - :old-value (quri:url-decode (nth 1 f)) - :value (quri:url-decode (nth 2 f))))) + :event-type :storage + :key (quri:url-decode (nth 0 f)) + :old-value (quri:url-decode (nth 1 f)) + :value (quri:url-decode (nth 2 f))))) (defgeneric set-on-storage (clog-window on-storage-handler) (:documentation "Set the ON-STORAGE-HANDLER for CLOG-OBJ. The diff --git a/clog.lisp b/clog.lisp index c16a0ff..4691aa9 100644 --- a/clog.lisp +++ b/clog.lisp @@ -27,6 +27,7 @@ connectivity to the browser or other websocket client (often a browser embedded in a native template application.)" (@clog-getting-started section) + (@clog-event-data section) (@clog-system section) (@clog-utilities section) @@ -302,7 +303,7 @@ embedded in a native template application.)" (defsection @clog-form (:title "CLOG Form Objects") "CLOG-Form - Class for organizing Form Elements in to a From" - (clog-form class) + (clog-form class) (create-form generic-function) (form-element-count generic-function) @@ -393,7 +394,6 @@ embedded in a native template application.)" (stroke-rect generic-function) (fill-text generic-function) (stroke-text generic-function) - ;; (measure-text generic-function) (line-width generic-function) (line-cap generic-function) (line-join generic-function) diff --git a/doc/clog-manual.html b/doc/clog-manual.html index 69590a6..40ef5ec 100644 --- a/doc/clog-manual.html +++ b/doc/clog-manual.html @@ -35,19 +35,20 @@
[in package CLOG]
@@ -61,7 +62,7 @@ embedded in a native template application.)

-

← ↑ → ↺

+

← ↑ → ↺

1 CLOG Getting Started

@@ -69,59 +70,65 @@ embedded in a native template application.)

David Botton mailto:david@botton.com

-

License BSD 3-Clause License

+

License BSD 3-Clause License

-

The Common Lisp Omnificient GUI, CLOG for short, uses web technology to +

View the HTML Documentation:

+ +

https://rabbibotton.github.io/clog/clog-manual.html

+ +

Introduction

+ +

The Common Lisp Omnificent GUI, CLOG for short, uses web technology to produce graphical user interfaces for applications locally or remotely. -CLOG can take the place, or work along side, most cross platform GUI +CLOG can take the place, or work alongside, most cross-platform GUI frameworks and website frameworks. The CLOG package starts up the connectivity to the browser or other websocket client (often a browser embedded in a native template application.)

-

STATUS: CLOG is complete enough for most uses, there are a few loose -ends (multimedia, client side storage, integrations with databases), -but CLOG is actually based on a framework I wrote for Ada, GNOGA, in -2013 and used in commercial production code for the last 6 years, -i.e. the techiniques it uses are solid and proven.

+

STATUS: CLOG is complete enough for most uses. While there are loose +ends (multimedia, database integrations), CLOG is actually based on +GNOGA, a framework I wrote for Ada in 2013 and used in commercial +production code for the last 6 years, i.e. the techiniques CLOG uses +are solid and proven.

-

Some of the things CLOG can be used for:

+

Some potential applications for CLOG:

The key to CLOG is the relationship it forms with a Browser window or Browser control compiled to native code. CLOG uses websockets -for communications and the browser to render a GUI that maintanes +for communications and the browser to render a GUI that maintains 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.

+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:

+

CLOG will be in Quicklisp in the next update, but because I am still +adding code daily, it is currently preferable to clone the github repo +into 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):

+have Quicklisp configured):

    -

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

    2. +

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

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

    4. -

  4. In the REPL run:

    5. +

  5. In the REPL, run:

CL-USER> (ql:quickload :clog) @@ -131,11 +138,64 @@ have QuickSlip configured):

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

+

+ +

← ↑ → ↺

+ +

2 CLOG Event Data

+ +

Some events in CLOG return in addition to the target event, event data. +The data is passed in the second argument to the event handler as a +property list. To retrieve the data use (getf data :property) the available +properties (to use for :property) are based on the event type.

+ +

From clog-base

+ +
 :event-type   :mouse
+ :x            x relative to the target
+ :y            y relative to the target
+ :screen-x     x relative to the users screen
+ :screen-y     y relative to the users screen
+ :which-button which mouse button clicked
+ :alt-key      t or nil if alt-key held down
+ :ctrl-key     t or nil if ctrl-key held down
+ :shift-key    t or nil if shift-key held down
+ :meta-key     t or nil if meta-key held down
+
+
+ :event-type     :touch
+ :x              x relative to the target
+ :y              y relative to the target
+ :screen-x       x relative to the users screen
+ :screen-y       y relative to the users screen
+ :number-fingers number of fingers being used
+ :alt-key        t or nil if alt-key held down
+ :ctrl-key       t or nil if ctrl-key held down
+ :shift-key      t or nil if shift-key held down
+ :meta-key       t or nil if meta-key held down
+
+ :event-type :keyboard
+ :key-code   A key code sometimes called a scan code for the key pressed
+ :char-code  UTF-8 representation for key pressed when possible
+ :alt-key    t or nil if alt-key held down
+ :ctrl-key   t or nil if ctrl-key held down
+ :shift-key  t or nil if shift-key held down
+ :meta-key   t or nil if meta-key held down
+
+ +

From clog-window

+ +
 :event-type :storage
+ :key        local storage key that was updated (even in another window)
+ :old-value  old key value
+ :value      new key value
+
+

-

← ↑ → ↺

+

← ↑ → ↺

-

2 CLOG System

+

3 CLOG System

CLOG Startup and Shutdown

@@ -176,7 +236,7 @@ function. If BOOT-FILE is nil path is removed.

← ↑ → ↺

-

3 CLOG Utilities

+

4 CLOG Utilities

CLOG utilities

@@ -232,7 +292,7 @@ function. If BOOT-FILE is nil path is removed.

← ↑ → ↺

-

4 CLOG Objects

+

5 CLOG Objects

CLOG-Obj - Base class for CLOG Objects

@@ -657,7 +717,7 @@ is nil unbind the event.

← ↑ → ↺

-

5 CLOG Elements

+

6 CLOG Elements

CLOG-Element - Class for CLOG Elements

@@ -1678,7 +1738,7 @@ to no actual HTML elemen.

← ↑ → ↺

-

6 Common CLOG Elements

+

7 Common CLOG Elements

CLOG-A - Class for CLOG Anchors

@@ -1991,7 +2051,7 @@ and if :AUTO-PLACE (default t) place-inside-bottom-of

← ↑ → ↺

-

7 CLOG Form Objects

+

8 CLOG Form Objects

CLOG-Form - Class for organizing Form Elements in to a From

@@ -2536,7 +2596,7 @@ optionally fill in with contents of data-list.

← ↑ → ↺

-

8 CLOG Canvas Objects

+

9 CLOG Canvas Objects

CLOG-Canvas - Class for CLOG canvas objects

@@ -2884,7 +2944,7 @@ https://developer.mozilla.org/en-US/docs/Web/CSS/font

← ↑ → ↺

-

9 CLOG Body Objects

+

10 CLOG Body Objects

CLOG-Body - CLOG Body Objects

@@ -2944,7 +3004,7 @@ or global objects.

← ↑ → ↺

-

10 CLOG Window Objects

+

11 CLOG Window Objects

CLOG-Window - CLOG Window Objects

@@ -3295,7 +3355,7 @@ on-storage event is fired for changes to :local storage keys.

← ↑ → ↺

-

11 CLOG Document Objects

+

12 CLOG Document Objects

CLOG-Document - CLOG Document Objects

@@ -3429,7 +3489,7 @@ on-storage event is fired for changes to :local storage keys.

← ↑ → ↺

-

12 CLOG Location Objects

+

13 CLOG Location Objects

CLOG-Location - CLOG Location Objects

@@ -3545,7 +3605,7 @@ on-storage event is fired for changes to :local storage keys.

← ↑ → ↺

-

13 CLOG Navigator Objects

+

14 CLOG Navigator Objects

CLOG-Navigator - CLOG Navigator Objects

@@ -3595,9 +3655,9 @@ on-storage event is fired for changes to :local storage keys.

← ↑ ↺

-

14 CLOG Framework internals and extensions

+

15 CLOG Framework internals and extensions

-

Responding to new java script DOM events:

+

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: