DEFINE-QT-WRAPPERS (qt-library &rest what)
Defines Lisp methods for all Qt methods/signals/slots of given library.
(See example `Qt_EQL/trafficlight/`).

      (define-qt-wrappers *c++*)        ; generate wrappers (see "Qt_EQL/")
      (define-qt-wrappers *c++* :slots) ; Qt slots only (any of :methods :slots :signals)

      (my-qt-function *c++* x y) ; instead of: (! "myQtFunction" (:qt *c++*) x y)

DEFVAR-UI (main-widget &rest variables)
This macro simplifies the definition of UI variables:

      (defvar-ui *main*
        *label*
        *line-edit*
        ...)

      ;; the above will expand to:

      (progn
        (defvar *label*     (qfind-child *main* "label"))
        (defvar *line-edit* (qfind-child *main* "line_edit"))
        ...)

ENSURE-QT-OBJECT (object)
Returns the `qt-object` of the given class/struct (see method `the-qt-object` in example `X-extras/CLOS-encapsulation.lisp`).
This function is used internally whenever a `qt-object` argument is expected.
QADD-EVENT-FILTER (object event function)
Convenience function. Adds a Lisp function to be called on a given event type.
If the object argument is `NIL`, the event will be captured for the whole application.
If the Lisp function returns `NIL`, the event will be processed by Qt afterwards.
Returns a handle which can be used to remove the filter, see `qremove-event-filter`.
See also `qoverride` for `QObject::eventFilter(QObject*,QEvent*)` and
`QObject::installEventFilter(QObject*)`,
`QObject::removeEventFilter(QObject*)`.
The event class corresponds to the respective event type (no cast needed).

      (qadd-event-filter nil |QEvent.MouseButtonPress| (lambda (object mouse-event) (print object) nil))

QAPP ()
Convenience function returning `qApp`.
QAPROPOS (&optional search-string class-name)
Finds all occurrencies of the given search string in the given object's meta information.
Constructors are listed under "Methods".
To list the user defined functions of external C++ classes (see Qt_EQL), pass the object instead of the class name.

      (qapropos "html" "QTextEdit")
      (qapropos nil "QWidget")
      (qapropos)
      (qapropos '|toString|)   ; wrapper function symbol
      (qapropos nil *qt-main*) ; see Qt_EQL (QObject derived C++ classes)

QAPROPOS* (&optional search-string class-name)
Similar to `qapropos`, returning the results as nested list.
QAUTO-RELOAD-C++ (variable library-name)
Linux only.
Extends `qload-c++` (see `Qt_EQL/`).
Defines a global variable (see return value of `qload-c++`), which will be updated on every change of the C++ plugin (e.g. after recompiling, the plugin will automatically be reloaded, and the `variable` will be set to its new value).
If you want to be notified on every change of the plugin, set `*<variable>-reloaded*`. It will then be called after reloading, passing both the variable name and the plugin name.
See `qload-c++` for an example how to call plugin functions.

      (qauto-reload-c++ *c++* "eql_cpp")

      (setf *c++-reloaded* (lambda (var lib) (qapropos nil (symbol-value var)))) ; optional: set a notifier

QCALL-DEFAULT ()
To use anywhere inside an overridden function (see `qoverride`).
Calls the base implementation of the virtual Qt method after leaving the function body.
Optionally call the base implementation directly (if you want to do post-processing of the return value).
QCLEAR-EVENT-FILTERS ()
Clears all added event filters.
QCONNECT (caller signal receiver/function &optional slot)
Connects either a Qt signal to a Qt slot, or a Qt signal to a Lisp function.

      (qconnect edit "textChanged(QString)" label "setText(QString)")
      (qconnect edit "textChanged(QString)" (lambda (txt) (print txt)))

QCOPY (object)
Copies `object` using copy-on-write, if such a constructor is available (non QObject derived classes only).
This function is short for e.g: `(qnew "QPixmap(QPixmap)" pixmap)`
Note that the returned value will not be garbage collected (analogous to `qnew`).

      (qcopy pixmap) ; QPen, QBrush, QFont, QPalette, QPixmap, QImage...

QDELETE (object &optional later)
QDEL
Deletes any Qt object, and sets the `pointer` value to `0`. Deleting a widget deletes all its child widgets, too.
If `later` is not `NIL`, the function `QObject::deleteLater()` will be called instead (but note: the `object` pointer will be set to `0` immediately.)
Returns `T` if the object has effectively been deleted.
See also `qlet` for local Qt objects.

      (qdel widget)
      (qdel socket :later)

QDISCONNECT (caller &optional signal receiver/function slot)
Disconnects signals to either Qt slots or Lisp functions. Anything but the caller can be either `NIL` or omitted.
Returns `T` if something has effectively been disconnected.

      (qdisconnect edit "textChanged(QString)" label "setText(QString)")
      (qdisconnect edit "textChanged(QString)")
      (qdisconnect edit nil label)
      (qdisconnect edit)

QENUMS (class-name &optional enum-name)
Returns the meta enum list of the given `class-name` and `enum-name` (see `Q_ENUMS` in Qt sources).
Omitting `enum-name` will return all meta enum lists of the class/scope.

      (qenums "QLineEdit" "EchoMode") ; gives '("QLineEdit" ("EchoMode" ("Normal" . 0) ...))
      (qenums "Qt")

QEQL (object1 object2)
Returns `T` for same instances of a Qt class. Comparing `QVariant` values will work, too.
To test for same Qt classes only, do:

      (= (qt-object-id object1) (qt-object-id object2))

QESCAPE (string)
Calls `QString::toHtmlEscaped()`.
QEVAL (&rest forms)
Slime mode `:repl-hook` only (not needed in default Slime mode): evaluate forms in GUI thread. Defaults to a simple `progn` outside of Slime.
QEXEC (&optional milliseconds)
Convenience function to call `QApplication::exec()`.
Optionally pass the time in milliseconds after which `QEventLoop::exit()` will be called.
See also `qsleep`.
QEXIT ()
Calls `QEventLoop::exit()`, in order to exit event processing after a call to `qexec` with a timeout.
Returns `T` if the event loop has effectively been exited.
QFIND-BOUND (&optional class-name)
Finds all symbols bound to Qt objects, returning both the Qt class names and the respective Lisp variables.
Optionally finds the occurrencies of the passed Qt class name only.

      (qfind-bound "QLineEdit")

QFIND-BOUND* (&optional class-name)
Like `qfind-bound`, but returning the results as list of conses.
QFIND-CHILD (object object-name)
Calls `QObject::findChild<QObject*>()`.
Can be used to get the child objects of any Qt object (typically from a UI, see `qload-ui`), identified by `QObject::objectName()`.

      (qfind-child *main* "editor")

QFIND-CHILDREN (object &optional object-name class-name)
Calls `QObject::findChildren<QObject*>()`, returning a list of all child objects matching `object-name` and `class-name`.
Omitting the `&optional` arguments will find all children, recursively.

      (qfind-children *qt-main* nil "LightWidget") ; see Qt_EQL example

QFROM-UTF8 (byte-array)
Returns the byte array (vector of octets) converted using `QString::fromUtf8()`.
QGUI (&optional process-events)
Launches the EQL convenience GUI.
If you don't have an interactive environment, you can pass `T` to run a pseudo Qt event loop. A better option is to start the tool like so:
`eql5 -qgui`, in order to run the Qt event loop natively.
QID (name)
Returns the internally used ID of the object name. Non QObject classes have negative ids.

      (qid "QWidget")

QINVOKE-METHOD (object function-name &rest arguments)
QFUN
Calls any of Qt methods, slots, signals. Static methods can be called by passing the string name of an object.
The most convenient way of calling Qt methods is to use the wrapper functions (see alternative 2 below), which allows for tab completion, showing all possible candidates in case of ambiguous type lists (overloaded methods). Additionally, static functions are shown as one symbol (easily catching the eye).
(Optionally you can pass the argument types (as for `qconnect` and `qoverride`), which may result in better performance, but only in some edge cases.)

      (qfun item "setText" 0 "Some objects are EQL.")
      (qfun "QDateTime" "currentDateTime")            ; static method
      (qfun slider "valueChanged" 10)                 ; emit signal

      ;; alternative 1: (macro '!')

      (! "setText" item 0 "Some objects are EQL.")
      (! "currentDateTime" "QDateTime")
      (! "valueChanged" slider 10)

      ;; alternative 2: (wrapper functions)

      (|setText| item 0 "Some objects are EQL.")
      (|currentDateTime.QDateTime|)
      (|valueChanged| slider 10)

QINVOKE-METHOD* (object cast-class-name function-name &rest arguments)
QFUN*
Similar to `qinvoke-method`, additionally passing a class name, enforcing a cast to that class.
Note that this cast is not type safe (the same as a C cast, so dirty hacks are possible).
Note: using the (recommended) wrapper functions (see `qfun`), casts are applied automatically where needed.

      (qfun* graphics-text-item "QGraphicsItem" "setPos" (list x y)) ; multiple inheritance problem
      (qfun* event "QKeyEvent" "key")                                ; not needed with QADD-EVENT-FILTER

      ;; alternatively:

      (! "setPos" ("QGraphicsItem" graphics-text-item) (list x y))
      (! "key" ("QKeyEvent" event))

      ;; better/recommended:

      (|setPos| graphics-text-item (list x y))

QINVOKE-METHOD+ (object function-name &rest arguments)
QFUN+
Use this variant to call user defined functions (declared `Q_INVOKABLE`), slots, signals from external C++ classes.
In order to call ordinary functions, slots, signals from external C++ classes, just use the ordinary `qfun`.

      (qfun+ *qt-main* "foo") ; see Qt_EQL

      ;; alternatively:

      (! "foo" (:qt *qt-main*))

QINVOKE-METHODS (object &rest functions)
QFUNS
A simple syntax for nested `qfun` calls.

      (qfuns object "funA" "funB" "funC")      ; expands to: (qfun (qfun (qfun object "funA") "funB") "funC")
      (qfuns object ("funA" 1) ("funB" a b c)) ; expands to: (qfun (qfun object "funA" 1) "funB" a b c)
      (qfuns "QApplication" "font" "family")
      (qfuns *table-view* "model" ("index" 0 2) "data" "toString")

      ;; alternatively:

      (! ("funC" "funB" "funA" object))
      (! (("funB" a b c) ("funA" 1) object))
      (! ("family" "font" "QApplication"))
      (! ("toString" "data" ("index" 0 2) "model" *table-view*))

      ;; using wrapper functions, the above reads:

      (|funC| (|funB| (|funA| object)))
      (|funB| (|funA| object 1) a b c)
      (|family| (|font.QApplication|))
      (|toString| (|data| (|index| (|model| *table-view*) 0 2)))

QLATER (function)
Convenience macro: a `qsingle-shot` with a `0` timeout.
This will call `function` as soon as the Qt event loop is idle.

      (qlater 'delayed-ini)

QLET (((variable-1 expression-1) (variable-2 expression-2) ...) &body body)
Similar to `let*` (and to local C++ variables).
Creates temporary Qt objects, deleting them at the end of the `qlet` body.
If `expression` is a string, it will be substituted with `(qnew expression)`, optionally including constructor arguments.
This macro is convenient for e.g. local `QPainter` objects, in order to guarantee C++ destructors being called after leaving a local scope.

      (qlet ((painter "QPainter"))
        ...)

      (qlet ((reg-exp "QRegExp(QString)" "^\\S+$"))
        ...)

QLOAD (file-name)
Convenience function for Slime (or when loading EQL files from an ECL thread).
Loading files that create many Qt objects can be slow on the Slime REPL (many thread switches).
This function reduces all thread switches (GUI related) to a single one.
QLOAD-C++ (library-name &optional unload)
Loads a custom Qt/C++ plugin (see `Qt_EQL/`).
The `library-name` has to be passed as path to the plugin, without file ending.
This offers a simple way to extend your application with your own Qt/C++ functions.
The plugin will be reloaded (if supported by the OS) every time you call this function (Linux: see also `qauto-reload-c++`).
If the `unload` argument is not `NIL`, the plugin will be unloaded (if supported by the OS).

      (defparameter *c++* (qload-c++ "eql_cpp")) ; load (Linux: see also QAUTO-RELOAD-C++)

      (qapropos nil *c++*)                       ; documentation

      (! "mySpeedyQtFunction" (:qt *c++*))       ; call library function (see also DEFINE-QT-WRAPPERS)

QLOAD-UI (file-name)
Calls a custom `QUiLoader::load()` function, loading a UI file created by Qt Designer. Returns the top level widget of the UI.
Use `qfind-child` to retrieve the child widgets.

      (qload-ui "my-fancy-gui.ui")

QLOCAL8BIT (string)
Converts a Unicode pathname to a simple ECL base string, using `QString::toLocal8Bit()` (see `QLocale` settings).
Depending on the OS (namely Windows), this is necessary if you get a filename from Qt and want to use it in ECL.
See also QUTF8.
QMESSAGE-BOX (x)
QMSG
Convenience function: a simple message box, converting `x` to a string if necessary.
Returns its argument (just like `print`).
QML ()
Generates global variables for all QML items with `objectName` set, see `lisp/ui-vars.lisp`. Requires the QML app to be running. Will show an error message if `objectName` is not unique.
QNEW-INSTANCE (class-name &rest arguments/properties)
QNEW
Creates a new Qt object, optionally passing the given arguments to the constructor.
Additionally you can pass any number of property/value pairs.
Please note how you can abbreviate long type lists.

      (qnew "QWidget")
      (qnew "QPixmap(int,int)" 50 50)                                           ; providing constructor types
      (qnew "QLabel" "text" "Readme")                                           ; set properties (any number); can be combined with above
      (qnew "QMatrix4x4(qreal...)" 1 2 3 4 1 2 3 4 1 2 3 4 1 2 3 4)             ; abbreviate long type lists
      (qnew "QSizePolicy(...)" |QSizePolicy.Expanding| |QSizePolicy.Expanding|) ; will work if type unambiguous, and no properties are passed

QNEW-INSTANCE* (class-name &rest arguments/properties)
QNEW*
Convenience function for the REPL.
Same as `qnew`, but showing the object immediately (if of type `QWidget`).
QNULL-OBJECT (object)
QNULL
Checks for a `0` Qt object pointer.
QOBJECT-NAMES (&optional type)
Returns all supported object names. Passing either `:q` or `:n` returns only the QObject inherited, or not QObject inherited names, respectively.
QOK ()
Needed to get the boolean ok value in cases like this:

      (! "getFont(bool*)" "QFontDialog" nil)

      (|getFont.QFontDialog| nil) ; NIL needed for <bool*>

QOVERRIDE (object name function)
Sets a Lisp function to be called on a virtual Qt method.
To remove a function, pass `NIL` instead of the function argument.
If you call `qcall-default` anywhere inside your overridden function, the base implementation will be called afterwards.
Instead of `qcall-default` you can directly call the base implementation, which is useful if you want to do post-processing of the returned value.

      (qoverride edit "keyPressEvent(QKeyEvent*)" (lambda (ev) (print (|key| ev)) (qcall-default)))

QPROCESS-EVENTS ()
Convenience function to call `QApplication::processEvents()`.
QPROPERTIES (object &optional (depth 1))
Prints all current properties of `object`, searching both all Qt properties and all Qt methods which don't require arguments (marked with '*').
Optionally pass a `depth` indicating how many super-classes to include. Pass `T` to include all super-classes.

      (qproperties (|font.QApplication|))
      (qproperties (qnew "QVariant(QString)" "42"))
      (qproperties *tool-button* 2)                 ; depth 2: both QToolButton and QAbstractButton

QPROPERTIES* (object)
Similar to `qproperties`, but listing all properties (including user defined ones) of the passed `object` instance.
This is only useful for e.g. `QQuickItem` derived classes, which don't have a corresponding C++ class, in order to list all QML properties.

      (qproperties* (qml:find-quick-item "myItem"))

QPROPERTY (object name)
QGET
Gets a Qt property. Enumerator values are returned as `int` values.
Returns `T` as second return value for successful calls.

      (qget label "text")

QQUIT (&optional (exit-status 0) (kill-all-threads t))
QQ
Terminates EQL. Use this function to quit gracefully, not `ext:quit`.
Negative values for `exit-status` will call `abort()` instead of normal program exit (e.g. to prevent infinite error message loops in some nasty cases).
QREMOVE-EVENT-FILTER (handle)
Removes the event filter corresponding to `handle`, which is the return value of `qadd-event-filter`.
Returns `handle` if the event filter has effectively been removed.
See also `qclear-event-filters`.
QREQUIRE (module &optional quiet)
Loads an EQL module, corresponding to a Qt module.
Returns the module name if both loading and initializing have been successful.
If the `quiet` argument is not `NIL`, no error message will be shown on failure.
Currently available modules: `:help :multimedia :network :quick :sql :svg :webengine :webkit`

      (qrequire :network)

QRGB (red green blue &optional (alpha 255))
Constructs a `(unsigned-byte 32)` value that represents a 32 bit pixel color specified by the red, green, blue and alpha values.
QRUN-ON-UI-THREAD (function &optional (blocking t))
QRUN
Runs `function` on the UI thread while (by default) blocking the calling thread (if called from main thread, `function` will simply be called directly).
This is needed to run GUI code from ECL threads other than the main thread.
Returns `T` on success.
There are 2 reasons to always wrap any EQL function like this, if called from another ECL thread:

- Qt UI methods always need to run on the UI thread
- EQL functions are not designed to be reentrant (not needed for UI code)

See also macro `qrun*`.

      (qrun 'update-view-data)

QRUN-ON-UI-THREAD* (&body body)
QRUN*
Convenience macro for `qrun`, wrapping `body` in a closure (passing arguments, return values).

      (qrun* (|setValue| ui:*progress-bar* value))

      (let ((item (qrun* (qnew "QTableWidgetItem")))) ; return value(s)
        ...)

QSELECT (&optional on-selected)
QSEL
Allows to select (by clicking) any (child) widget.
The variable `qsel:*q*` is set to the latest selected widget.
Optionally pass a function to be called upon selecting, with the selected widget as argument.

      (qsel (lambda (widget) (qmsg widget)))

QSENDER ()
Corresponding to `QObject::sender()`. To use inside a Lisp function connected to a Qt signal.
QSET-COLOR (widget color-role color)
Convenience function for simple color settings (avoiding `QPalette` boilerplate).
Use `QPalette` directly for anything more involved.

      (qset-color widget |QPalette.Window| "white")

QSET-NULL (object)
Sets the Qt object pointer to `0`. This function is called automatically after `qdel`.
QSET-PROPERTY (object name value)
QSET
Sets a Qt property. Enumerators have to be passed as `int` values.
Returns `T` as second return value for successful calls.

      (qset label "alignment" |Qt.AlignCenter|)

QSIGNAL (name)
Needed in functions which expect a `const char*` Qt signal (not needed in `qconnect`).
QSINGLE-SHOT (milliseconds function)
A single shot timer similar to `QTimer::singleShot()`.

      (qsingle-shot 1000 'one-second-later)

      (let ((ms 500))
        (qsingle-shot ms (lambda () (qmsg ms))))

QSLEEP (seconds)
Similar to `sleep`, but continuing to process Qt events.
QSLOT (name)
Needed in functions which expect a `const char*` Qt slot (not needed in `qconnect`).
QSTATIC-META-OBJECT (class-name)
Returns the `::staticMetaObject` of the given class name.

      (qstatic-meta-object "QEasingCurve")

QSUPER-CLASS-NAME (name)
Returns the super class of an object name, or `NIL` if the class doesn't inherit another Qt class.
Returns `T` as second return value for successful calls.

      (qsuper-class-name "QGraphicsLineItem")

QT-OBJECT-? (object)
Returns the specific `qt-object` of a generic `qt-object`.
Works for QObject and QEvent inherited classes only.

      (qt-object-? (|parentWidget| widget))
      (qt-object-? (|widget| (|itemAt| box-layout 0)))
      (qt-object-? event)

QT-OBJECT-NAME (object)
Returns the Qt class name.
QUI-CLASS (file-name &optional object-name)
Finds the class name for the given user-defined object name in the given UI file.
Omitting the object name will return the top level class name of the UI.

      (qui-class "examples/data/main-window.ui" "editor") ; returns "QTextEdit"

QUI-NAMES (file-name)
Finds all user-defined object names in the given UI file.

      (qui-names "examples/data/main-window.ui")

QUIC (&optional (file.h "ui.h") (file.lisp "ui.lisp") (ui-package :ui))
Takes C++ code from a file generated by the `uic` user interface compiler, and generates the corresponding EQL code.
See also command line option `-quic`.
QUTF8 (string)
Converts a Unicode pathname to a simple ECL base string, using `QString::toUtf8()`.
Depending on the OS (namely OSX, Linux), this is necessary if you get a filename from Qt and want to use it in ECL.
See also QLOCAL8BIT.
QVARIANT-FROM-VALUE (value type-name)
Constructs a new `QVariant`. This is needed for types that don't have a direct constructor, like `QPixmap`, or primitive types, like `QSize`.

      (qvariant-from-value "red" "QColor")

QVARIANT-VALUE (object)
Returns the Lisp value of the `QVariant` object.
QVERSION ()
Returns the EQL version number as "<year>.<month>.<counter>".
The second return value is the Qt version as returned by `qVersion()`.
TR (source &optional context plural-number)
Macro expanding to `qtranslate`, which calls `QCoreApplication::translate()`.
Both `source` and `context` can be Lisp forms evaluating to constant strings (at compile time).
The `context` argument defaults to the Lisp file name. For the `plural-number`, see Qt Assistant.