nodgui FAQ

Nodgui shows a weak heritage from LTK, at this point the documentation for the original library can be confusing for the newcomer; i suggest, instead, these resources:

• a fellow lisper wrote an impressive set of examples for Nodgui.
• the demo code can be used both as teaching material or as boiler plate for your code.
• also check out the vindarel experiments

The rest of the documentation is this page and the rare docstrings at the moment.

If you want to help please open a pull request.

It is actually very simple: let's suppose you want to use a spinbox widget in your program and you have no idea how to do, the idea to solve this problem is like:

1. open the file src/spinbox.lisp an look at the top of this file:

   (defargs spinbox ()
   cursor
   state
   style
   takefocus
   validate
   validatecommand
   xscrollcommand
   command
   format
   from
   increment
   to
   values
   wrap)
   

   the symbols listed are all the options for the spinbox TK command (in TCL language everything is a command) or the configuration variable that you can pass as initarg for (make instance 'spinbox ...) and, sometimes, changed after object instancing via configure (see the general documentation)

2. for the meaning of this symbols refers to the original TK documentation

   As a general rule choose the link to the command with its name prefixed with "ttk::" (if exists).

   In our example point to:

   https://www.tcl.tk/man/tcl8.6/TkCmd/ttk_spinbox.htm

   and not

   https://www.tcl.tk/man/tcl8.6/TkCmd/spinbox.htm

   You can easily understand what all the options above are for.

See: Widget pack

The root window is returned by the function: nodgui:root-toplevel.

with-nodgui accepts keywords :title and :class to change the name and the class of the window respectively.

Sure! Use grid-(column|row)-configure.

(grid-columnconfigure (root-toplevel) :all :weight 1)
(grid-rowconfigure    (root-toplevel) :all :weight 1)

You can replace :all with a row or column indices to apply this behaviour only to a subset of the columns or rows.

Use nodgui:listbox-export-selection

(nodgui:with-nodgui ()
  (let* ((listbox-1 (make-instance 'nodgui:listbox))
         (listbox-2 (make-instance 'nodgui:listbox))
         (entry     (make-instance 'nodgui:entry)))
    (nodgui:grid listbox-1 0 0)
    (nodgui:grid listbox-2 0 1)
    (nodgui:grid entry     1 0 :columnspan 2 :pady 2 :sticky :ew)
    (setf (nodgui:text entry) "baz")
    ;; note the call to listbox-export-selection for each listbox
    (nodgui:listbox-export-selection listbox-1 nil)
    (nodgui:listbox-export-selection listbox-2 nil)
    (nodgui:listbox-insert listbox-1 0 "foo")
    (nodgui:listbox-insert listbox-2 0 "bar")))

If you try to run the same code without the two nodgui:listbox-export-selection calls the selected text (even on the entry) will remove all the other selections.

The method initialize-instance specialized on widget, a common ancestor of many GUI elements available (button, frame, etc) accepts the keyword argument: grid, pack and place. Pass a list of arguments, compatible with the corresponding layout function to this keyword argument to configure the layout for the widget you are creating, for example:

(make-instance 'nodgui:frame :grid '(0 ; first row
                                     1 ; second column
                                     :sticky :news
                                     :padx   10))

see for reference: https://codeberg.org/cage/nodgui/issues/9#issuecomment-1549116

Use exit-nodgui

(with-nodgui ()
  (let ((button (make-instance 'button :text "quit")))
    (setf (command button)
          (lambda ()
            (format t "quitting~%")
            (exit-nodgui)))
    (pack button)))

The two libraries diverged now, the API is no more compatible with LTK.

The major differences are:

1. A reader macro for events i.e. #$<Alt-q>$ instead of "<Alt-q>" (a string), the macro will parse and check for trivial errors in the event definition syntax at compile time.

   (named-readtables:in-readtable nodgui.syntax:nodgui-syntax) ; do not forget that!
   
   [...]
   
   (bind (root-toplevel) #$<Alt-q>$ (lambda (event) ...
   

   Please note that a string is still accepted as event specifier.

2. A DSL for TCL code that allow to mix TCL code and lisp expression, check for example the following code to create a bitmap:

   (named-readtables:in-readtable nodgui.syntax:nodgui-syntax) ; do not forget that!
   
   [...]
   
   (tclize `([list
               ,(loop for r from 0 below h collect
                   (tclize `([list ,(loop
   ...
   

   The tclize macro will transforms the backquoted forms in TCL code, the unquoted forms will be evaluated before the translation occurs;

3. The function postscript returns a postscript file as string instead of writing a file on disk;
4. Support for images in GIF, PNG, TGA, JPEG and raw RGB format, limited manipulation for the latest four formats is provided (scaling and rotation);
5. Compatible only with TK 8.6;
6. A general refactoring;
7. Integrated with cl-colors library (can use X11 color names or RGB struct, see Colors Name);
8. Many more widgets, some not even available with TK, included canvas with hardware accelerated rendering;
9. Some bugs fixed (and more added of course :-) ).

Check the file src/demo-tests.lisp

Yes, of course! Please open an issue or a pull request on the web repository, if you do not feel comfortable with coding, documentation improvements are very welcome too! :)

Also i would appreciate testing if the library works on different environment than mine (Debian GNU/Linux with SBCL).