From e95700908da12f11ed754846f7404a384e9507cb Mon Sep 17 00:00:00 2001 From: David Botton Date: Thu, 20 Nov 2025 00:09:16 -0500 Subject: [PATCH] doc updates --- doc/clog-manual.html | 2510 ++++++++++++++++++++++++++++++++++++++++- doc/live.js | 47 + doc/style.css | 87 +- doc/toc.min.js | 2 +- source/clog-docs.lisp | 7 + 5 files changed, 2605 insertions(+), 48 deletions(-) create mode 100644 doc/live.js diff --git a/doc/clog-manual.html b/doc/clog-manual.html index 9119889..b76e2ad 100644 --- a/doc/clog-manual.html +++ b/doc/clog-manual.html @@ -1,23 +1,13 @@ -The CLOG manual - +The CLOG manual - + - - + @@ -30,9 +20,13 @@

+

→ ↺

+

The CLOG manual

+

Table of Contents

+ +
[in package CLOG]
+

The Common Lisp Omnificient 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 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.)

+

+

← ↑ → ↺

+

1 CLOG Getting Started

+

CLOG - The Common Lisp Omnificent GUI

+

David Botton mailto:david@botton.com

+

License BSD 3-Clause License

+

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 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's API is mature and stable. Tools and new plugins always in the works. Check the github discussion boards for the latest.

+

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 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 and SBCL, it is tested fairly regulary with SBCL on Linux, Windows and Intel MacBook. It should in theory work on any system with Quicklisp and CLACK.

+

CLOG is in Quicklisp (ql:quickload :clog), but you may want to live on the bleeding edge and use Ultralisp or clone the github repo into your ~/common-lisp directory (or other quicklisp/asdf findable directory):

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

To load this package and work through tutorials (assuming you have Quicklisp configured.)

+

Note: If using portacle for Windows you will need to update Quicklisp use (ql:update-dist "quicklisp") You will also likely need to copy the sqlite3 dll from https://www.sqlite.org/download.html to portaclewinlib

+

  1. Start emacs then M-x slime

  2. In the REPL, run:

+ 
CL-USER> (ql:quickload :clog)
 CL-USER> (clog:run-tutorial 1)
+

Tip for Windows WSL linux user. Install "sudo apt install xdg-utils" to install xdg-open so that run-tutorial uses the windows browser.

+

To see where the source, tutorial and demo files are:

+ 
CL-USER> (clog:clog-install-dir)
+

You can the run the demos with:

+ 
CL-USER> (ql:quickload :clog)
 CL-USER> (clog:run-demo 1)
+

The clog-db-admin tool can be run with:

+ 
CL-USER> (ql:quickload :clog/tools)
 CL-USER> (clog-tools:clog-db-admin)
+

The clog-builder GUI Builder tool can be run with:

+ 
CL-USER> (ql:quickload :clog/tools)
 CL-USER> (clog-tools:clog-builder)
+

You can also open a "clog-repl" window in your browser to play from the common-lisp repl:

+ 
CL-USER> (in-package clog-user)
 CLOG-USER> (clog-repl)
 CLOG-USER> (setf (background-color *body*) "beige")
 CLOG-USER> (create-div *body* :content "Hello World!")
+

The clog-repl URL is http://127.0.0.1:8080/repl body will always refer to the last access of that URL.

+

To open a browser with the CLOG manual:

+ 
CL-USER> (clog:open-manual)
+

Work your way through the tutorials. You will see how quick and easy it is to be a CLOGer. The next section also covers the basic programming concepts needed for mastering CLOG.

+

+

← ↑ → ↺

+

2 CLOG Programming Basics

+

  • Simple REPL techniques Tutorial

    • +

    We first need to load CLOG

    + 
    CL-USER> (ql:quickload :clog)
 To load "clog":
   Load 1 ASDF system:
@@ -176,7 +211,9 @@ To load "clog":
 ; Loading "clog"
 ................................................
 (:CLOG)
    +

    Next, we tell clog to start a clog-repl:

    + 
    CL-USER> (clog:clog-repl)
 Hunchentoot server is started.
 Listening on 0.0.0.0:8080.
@@ -186,31 +223,46 @@ Boot file for path / : /debug.html
 
 Use clog-user:*body* to access the clog-repl window.
 NIL
    +

    At this point CLOG should open a browser window to http://127.0.0.1:8008/repl

    +

    We can now enter the clog-user package and hack a way.

    + 
    CL-USER> (in-package clog-user)
 #<"CLOG-USER" package>
 CLOG-USER> (setf (background-color *body*) :red)
    +

    Something more than an empty lambda function is needed to do more. The tutorials are a good place to start with make CLOG apps in code, so here we are going to demonstrate the concepts using some REPL tricks to help developing CLOG apps in general.

    +

    (From here on, we will leave out the prompts and responses in our quotes of code.)

    + 
    (create-div *body* :content "Hello World")
    +

    If you have the browser on the screen you will see the results immediately. Try this line and you can watch it happen:

    + 
    (dotimes (n 10) (create-div *body* :content (format nil "Line ~A - Hello World" n)) (sleep .3))
    +

    We can also set and respond to events and set properties etc:

    + 
    (let ((tmp (create-button *body* :content "Click Me")))
   (set-on-click tmp (lambda (obj)(setf (hiddenp tmp) t))))
    +

    Since we already initialized CLOG let's use SET-ON-NEW-WINDOW to change our on-new-window handler (handler is just a made up name for a function that will handle an event).

    + 
    CLOG-USER> (set-on-new-window (lambda (body) (create-div body :content "Hello World!")))
    +

    Now any new window opened will not be using CLOG REPL but instead will execute our handler.

    +

    Important take aways to using CLOG from the REPL:

    +

    1. You will need to pass to a global from the running system whatever you want to tinker with in the live system from the REPL.

      2. @@ -219,15 +271,21 @@ you will need to use SET-ON-NEW-WINDOW.

    2. Similarily with all events, any time an event handler is recompiled or want to change the even hander, set-on-* function will need to be called.

    +

    +

    ← ↑ → ↺

    +

    3 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.

    +

    Events in clog-base

    + 
     :event-type   :mouse
  :x            x relative to the target
  :y            y relative to the target
@@ -239,6 +297,13 @@ properties (to use for :property) are based on the event type.
    
  :shift-key    t or nil if shift-key held down
  :meta-key     t or nil if meta-key held down
 
+ :event-type  :wheel
+ :delta-x     change in x float
+ :delta-y     change in y float
+ :delta-z     change in z float
+ :delta-mode  unit of measure used for delta values
+              0 - pixel  1 - line  2 - page
+
  :event-type   :pointer
  :x            x relative to the target
  :y            y relative to the target
@@ -270,19 +335,27 @@ properties (to use for :property) are based on the event type.
    
  :shift-key  t or nil if shift-key held down
  :meta-key   t or nil if meta-key held down
    +

    Events in 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
    +

    +

    ← ↑ → ↺

    +

    4 CLOG System

    +

    CLOG Startup and Shutdown

    +

    + +

    + +

    + +

    + +

    + +

    + +

    + +

    + +

    + +

    + +

    +

    ← ↑ → ↺

    +

    5 CLOG Utilities

    +

    Concurrent Hash Tables

    +

    + +

    Declerative Syntax Support

    +

    + +

    CLOG ID utilities

    +

    + +

    + +

    CLOG JS utilities

    +

    + +

    + +

    + +

    + +

    + +

    + +

    + +

    + +

    + +

    CLOG Color utilities

    +

    + +

    + +

    + +

    + +

    + +

    CLOG Unit utilities

    +

    + +

    + +

    +

    ← ↑ → ↺

    +

    6 CLOG Objects

    +

    CLOG-Obj - Base class for CLOG Objects

    +

    + +

    + +

    CLOG-Obj - General Properties

    +

    + +

    CLOG-Obj - General Methods

    +

    + +

    + +

    + +

    + +

    CLOG-Obj - Low Level

    +

    + +

    + +

    + +

    + +

    + +

    + +

    + +

    + +

    + +

    + +

    + +

    CLOG-Obj - Internals for Extensions and Plugins

    +

    + +

    + +

    + +

    + +

    +