Next: Introduction, Previous: (dir), Up: (dir) [Contents][Index]
This is the cl-charms Reference Manual, version 0.2.0, generated automatically by Declt version 4.0 beta 2 "William Riker" on Wed Jun 15 03:34:38 2022 GMT+0.
Next: Systems, Previous: The cl-charms Reference Manual, Up: The cl-charms Reference Manual [Contents][Index]
cl-charms
is an interface to libcurses
in Common Lisp. It provides
both a raw, low-level interface to libcurses
via CFFI, and a more
higher-level lispier interface.
It is intended to succeed cl-ncurses
, which used the less portable
UFFI instead of CFFI for foreign bindings. Indeed, cl-charms
includes portions of code from cl-ncurses
, and is largely a direct
translation of the latter's UFFI definitions to CFFI.
Currently, the low-level interface (the package charms/ll
) is
probably feature-equivalent to cl-ncurses
and compatible with client
code. In the future, however, cl-charms
may break compatibility with
cl-ncurses
.
cl-charms
has been developed by its original author, Abhishek Reddy
(abhishek@abhishek.geek.nz), since beginning of October 2010 for quite
some time, then abandoned for unknown reason. After that, in 2014,
Mark Fedurin (hitecnologys@gmail.com) took responsibility for keeping
the library in working state. Robert Smith (quad@symbo1ics.com) began
to fix up the CFFI bindings and provide a friendlier interface.
The software is released under an MIT-style license. See the file
COPYING
for details.
The imitator dooms himself to hopeless mediocrity. The inventor did it because it was natural to him, and so in him it has a charm. In the imitator something else is natural, and he bereaves himself of his own beauty, to come short of another man's. -- R.W. Emerson on originality.
Versioning roughly follows the scheme described in Semantic Versioning. Only "releases" will be versioned.
Since we are still pre-1.0.0
, the minor version will indicate API
breakage. Despite being pre-1.0.0
, what exists in the low-level
interface as of now is quite usable for ASCII usage. We consider this
"beta" quality. The high-level functionality is considered "alpha"
quality.
cl-charms
has been tested to work to a reasonable extent (e.g.,
example code runs) on the following platforms:
It may work on other implementations and system but there's no guarantee. More testing is really appreciated.
cl-charms
ought to function on other implementations of Common Lisp
and libcurses
on various distributions of UNIX and UNIX-like
systems. See the section on Bugs and Contributing below for how to
help test and realize this.
cl-charms
is supposed to be only bindings along with a separate,
no-frills interface atop: nothing more, nothing less. For
full-featured TUI see: https://bitbucket.org/naryl/cl-tui
cl-charms
works on Windows with some limitations. Currently colours are not
supported and some other features like bold might not work correctly. In order
to use cl-charms
on Windows, you'll need PDCurses library that is available
at http://pdcurses.sourceforge.net/. If you want to use GDI instead of console
http://www.projectpluto.com/win32a.htm would be a good option.
While the original PDCurses project offers prebuilt binaries, using project pluto requires you to compile your own binaries.
Usage is as simple as placing the pdcurses.dll
(optionally renaming
it libcurses.dll
) either in PATH
or in the directory where you're
running your cl-charms
program. Project pluto will require
additional dependencies, namely libgcc_s_dw2-1.dll
and SDL.dll
.
If you're Quicklisp user, then simple
(ql:quickload :cl-charms)
would suffice, as cl-charms
is in Quicklisp.
If you're not, then install Quicklisp and follow to the previous paragraph.
The low-level library is contained within the package
cl-charms/low-level
, nicknamed charms/ll
. This is mostly a
one-to-one equivalent to standard curses functions.
The high-level library is contained within the package cl-charms
,
nicknamed charms
.
There are currently two examples included with the source code, all of which you can find in the examples directory.
You might also want to check out the following applications written
using cl-charms
:
Daniel Kochmanski has written a nice tutorial about CL-CHARMS here.
A minimal, simple timer/stopwatch program.
* (ql:quickload :cl-charms-timer)
* (charms-timer:main)
A simple ASCII art drawing program.
* (ql:quickload :cl-charms-paint)
* (charms-paint:main)
As a minimum, it would be appreciated if the library was compiled and loaded on various Lisp systems on a variety of operating systems.
[TODO]
The libcurses
library handles terminal, and emacs is not a terminal
it can handle. So if you run lisp from SLIME (inside emacs),
libcurses
functions won't work properly.
If you want to use SLIME, a possible way (to e.g. run the timer example) is:
(ql:quickload '(:swank) :silent t)
;; from terminal(swank:create-server :port 5555 :dont-close t)
;; from terminal, too(loop (sleep 1))
;; from terminal, prevents read-line in console REPL(ql:quickload :cl-charms-timer)
;; from emacs repl(charms-timer:main)
;; from emacs replNow you should see timer running on terminal.
Step 1. ~ 3. can be done as a one-liner:
sbcl --eval "(ql:quickload '(:swank) :silent t)" --eval "(swank:create-server :port 5555 :dont-close t)"
ccl -e "(ql:quickload '(:swank) :silent t)" -e "(swank:create-server :port 5555 :dont-close t)"
;; maybe ccl64 instead of cclros run -e "(ql:quickload '(:swank) :silent t)" -e "(swank:create-server :port 5555 :dont-close t)"
You can use GitHub project's (which is located here: https://github.com/HiTECNOLOGYs/cl-charms) issues tracker or wiki to contribute bug reports/patches/etc. or just send an email to one of the maintainers.
Major areas of work to be done:
Next: Modules, Previous: Introduction, Up: The cl-charms Reference Manual [Contents][Index]
The main system appears first, followed by any subsystem dependency.
CFFI bindings for curses.
Mark Fedurin <hitecnologys@gmail.com>
Abhishek Reddy <abhishek@abhishek.geek.nz>
MIT License (See COPYING)
0.2.0
cffi-grovel (system).
Next: Files, Previous: Systems, Up: The cl-charms Reference Manual [Contents][Index]
Modules are listed depth-first from the system components tree.
Next: cl-charms/high-level, Previous: Modules, Up: Modules [Contents][Index]
features.lisp (file).
cl-charms (system).
Previous: cl-charms/low-level, Up: Modules [Contents][Index]
low-level (module).
cl-charms (system).
Next: Packages, Previous: Modules, Up: The cl-charms Reference Manual [Contents][Index]
Files are sorted by type and then listed depth-first from the systems components trees.
Next: cl-charms/features.lisp, Previous: Lisp, Up: Lisp [Contents][Index]
cl-charms (system).
Next: cl-charms/low-level/package.lisp, Previous: cl-charms/cl-charms.asd, Up: Lisp [Contents][Index]
cl-charms (system).
Next: cl-charms/low-level/curses-grovel.lisp, Previous: cl-charms/features.lisp, Up: Lisp [Contents][Index]
low-level (module).
Next: cl-charms/low-level/curses-bindings.lisp, Previous: cl-charms/low-level/package.lisp, Up: Lisp [Contents][Index]
package.lisp (file).
low-level (module).
Next: cl-charms/low-level/mouse.lisp, Previous: cl-charms/low-level/curses-grovel.lisp, Up: Lisp [Contents][Index]
curses-grovel.lisp (file).
low-level (module).
Next: cl-charms/high-level/package.lisp, Previous: cl-charms/low-level/curses-bindings.lisp, Up: Lisp [Contents][Index]
curses-bindings.lisp (file).
low-level (module).
Next: cl-charms/high-level/utilities.lisp, Previous: cl-charms/low-level/mouse.lisp, Up: Lisp [Contents][Index]
high-level (module).
Next: cl-charms/high-level/windows.lisp, Previous: cl-charms/high-level/package.lisp, Up: Lisp [Contents][Index]
package.lisp (file).
high-level (module).
Next: cl-charms/high-level/cursor.lisp, Previous: cl-charms/high-level/utilities.lisp, Up: Lisp [Contents][Index]
utilities.lisp (file).
high-level (module).
Next: cl-charms/high-level/output.lisp, Previous: cl-charms/high-level/windows.lisp, Up: Lisp [Contents][Index]
windows.lisp (file).
high-level (module).
Next: cl-charms/high-level/input.lisp, Previous: cl-charms/high-level/cursor.lisp, Up: Lisp [Contents][Index]
cursor.lisp (file).
high-level (module).
Next: cl-charms/high-level/initialization.lisp, Previous: cl-charms/high-level/output.lisp, Up: Lisp [Contents][Index]
output.lisp (file).
high-level (module).
get-char (function).
Next: cl-charms/high-level/miscellaneous.lisp, Previous: cl-charms/high-level/input.lisp, Up: Lisp [Contents][Index]
input.lisp (file).
high-level (module).
*input-mode* (special variable).
Previous: cl-charms/high-level/initialization.lisp, Up: Lisp [Contents][Index]
initialization.lisp (file).
high-level (module).
Next: Definitions, Previous: Files, Up: The cl-charms Reference Manual [Contents][Index]
Packages are listed by definition order.
Next: cl-charms/low-level, Previous: Packages, Up: Packages [Contents][Index]
Package containing a high-level interface to ncurses.
charms
common-lisp.
Package containing the one-to-one bindings to the ncurses library.
charms/ll
common-lisp.
Next: Indexes, Previous: Packages, Up: The cl-charms Reference Manual [Contents][Index]
Definitions are sorted by export status, category, package, and then by lexicographic order.
Next: Internals, Previous: Definitions, Up: Definitions [Contents][Index]
Next: Special variables, Previous: Public Interface, Up: Public Interface [Contents][Index]
Next: Symbol macros, Previous: Constants, Up: Public Interface [Contents][Index]
Bind-only special variable containing the standard window.
Next: Macros, Previous: Special variables, Up: Public Interface [Contents][Index]
Next: Ordinary functions, Previous: Symbol macros, Up: Public Interface [Contents][Index]
Prints formatted output in curses windows at (‘x‘, ‘y‘).
Output is formatted as ‘fmt‘, according to C language’s printf function.
Arguments for ‘fmt‘ can be passed as a form of { arg-type arg }*.
caution: This function may crash when format string ‘fmt‘ won’t match rest arguments.
see printw for examples.
Prints formatted output in window ‘win‘ at (‘x‘, ‘y‘).
Output is formatted as ‘fmt‘, according to C language’s printf function.
Arguments for ‘fmt‘ can be passed as a form of { arg-type arg }*.
caution: This function may crash when format string ‘fmt‘ won’t match rest arguments.
see printw for examples.
Prints formatted output in curses windows.
Output is formatted as ‘fmt‘, according to C language’s printf function.
Arguments for ‘fmt‘ can be passed as a form of { arg-type arg }*.
caution: This function may crash when format string ‘fmt‘ won’t match rest arguments.
examples:
(printw "Hello world") ; prints ’Hello world’
(printw "%d %.2f %s" :int 42 :double pi :string "charms"); prints ’42 3.14 charms’
Execute the body BODY, ensuring that curses is properly initialized and finalized.
Within BODY, the special variable *STANDARD-WINDOW* will be bound, which refers to the global window.
Currently, there are no OPTIONS.
Execute the body BODY, restoring the cursor position in the window WINDOW to its beginning state.
Prints formatted output in window ‘win‘.
Output is formatted as ‘fmt‘, according to C language’s printf function.
Arguments for ‘fmt‘ can be passed as a form of { arg-type arg }*.
caution: This function may crash when format string ‘fmt‘ won’t match rest arguments.
see printw for examples.
Next: Classes, Previous: Macros, Up: Public Interface [Contents][Index]
Audibly beep to alert the user.
What is the character at the cursor in the window WINDOW?
What is the character at the point (X, Y) in the window WINDOW?
Clear the rest of the line after the cursor in the window WINDOW.
Blank out the contents of the window WINDOW. If FORCE-REPAINT is T, then the window will be repainted entirely in the next refresh. (Using this option can be more optimally performant than calling ‘CHARMS:FORCE-REPAINT’ manually.)
Clear the rest of the window after the cursor in the window WINDOW.
Copy the window WINDOW.
Return a string representing the version of the underlying curses implementation.
Given a window WINDOW, return its X and Y coordinates as two values respectively.
Destroy the window WINDOW.
Disable the echoing of characters to the screen.
Disable extra keys, such as arrow and function keys, in the window WINDOW.
Disable non-blocking mode for the window WINDOW. This will cause character input to block.
Disables raw input mode. This undoes the action of ‘CHARMS:ENABLE-RAW-INPUT’.
Enable the echoing of characters to the screen.
Enable extra keys, such as arrow and function keys, in the window WINDOW.
Enable non-blocking mode for the window WINDOW. This will cause character input functions to not block and error (or return NIL).
Enables raw input mode. This disables line buffering and will make characters available as soon as they’re typed.
If INTERPRET-CONTROL-CHARACTERS is T, then control characters like Ctrl-C will be interpreted as usual.
Finalize ncurses.
This function must be called before exiting. Consider using the macro ‘CHARMS:WITH-CURSES’ to ensure this.
Visually flash the console.
Force the entire window to be cleared and repainted on the next call to ‘CHARMS:REFRESH-WINDOW’.
Get a character from the window WINDOW. In the event a character is not ready or could not be returned, thensignal an error. If IGNORE-ERROR is T, then instead return NIL.
Returns the character in the main value and C-function’s return code in second
value. Replaces primary value (which would be garbage) with :ERROR if C-function returned ERR
The has_mouse function returns TRUE if the mouse driver has been successfully initialized.
Initialize ncurses and the terminal for drawing. Return the standard window.
This function must be called before using curses functions. Consider using the macro ‘CHARMS:WITH-CURSES’ to ensure this.
Insert the character CHAR at the cursor within the window WINDOW, advancing the rest of the line, without moving the cursor. (This is akin to pressing the ’insert’ key and typing a character.)
Insert the character CHAR at the coordinates (X,Y) within the window WINDOW, advancing the rest of the line, without moving the cursor. (This is akin to pressing the ’insert’ key and typing a character.)
Make a new window of width WIDTH and height HEIGHT, starting at the coordinate (START-X, START-Y).
Note that windows may not overlap.
The mouse_trafo function performs the same translation as wmouse_trafo, using stdscr for win.
The wmouse_trafo function transforms a given pair of coordinates from
stdscr-relative coordinates to coordinates relative to the given window or vice
versa. The resulting stdscr-relative coordinates are not always identical to
window-relative coordinates due to the mechanism to reserve lines on top or
bottom of the screen for other purposes (see the ripoffline and slk_init calls,
for example).
- If the parameter to_screen is TRUE, the pointers pY, pX must reference the
coordinates of a location inside the window win. They are converted to
window-relative coordinates and returned through the pointers. If the
conversion was successful, the function returns TRUE.
- If one of the parameters was NULL or the location is not inside the window,
FALSE is returned.
- If to_screen is FALSE, the pointers pY, pX must reference window-relative
coordinates. They are converted to stdscr-relative coordinates if the window
win encloses this point. In this case the function returns TRUE.
- If one of the parameters is NULL or the point is not inside the window, FALSE is returned. The referenced coordinates are only replaced by the converted coordinates if the transformation was successful.
The mouseinterval function sets the maximum time (in thousands of a second) that can elapse between press and release events for them to be recognized as a click. Use mouseinterval(0) to disable click resolution. This function returns the previous interval value. Use mouseinterval(-1) to obtain the interval without altering it. The default is one sixth of a second.
set newmask as mousemask, returning old one
Move the cursor in window WINDOW to the coordinates (X, Y).
Move the cursor in the window WINDOW down by 1 character. If the positive integer AMOUNT is specified, it will be moved down AMOUNT characters. If negative, it will move up AMOUNT characters.
Move the cursor in the window WINDOW left by 1 character. If the positive integer AMOUNT is specified, it will be moved left AMOUNT characters. If negative, it will move right AMOUNT characters.
Move the cursor in the window WINDOW right by 1 character. If the positive integer AMOUNT is specified, it will be moved right AMOUNT characters. If negative, it will move left AMOUNT characters.
Move the cursor in the window WINDOW up by 1 character. If the positive integer AMOUNT is specified, it will be moved up AMOUNT characters. If negative, it will move down AMOUNT characters.
Returns the character in the main value and C-function’s return code in second
value. Replaces primary value (which would be garbage) with :ERROR if C-function returned ERR
Returns the character in the main value and C-function’s return code in second
value. Replaces primary value (which would be garbage) with :ERROR if C-function returned ERR
Refresh the display of the window WINDOW.
The wenclose function tests whether a given pair of screen-relative character-cell coordinates is enclosed by a given window, returning TRUE if it is and FALSE otherwise. It is useful for determining what subset of the screen windows enclose the location of a mouse event.
Returns the character in the main value and C-function’s return code in second
value. Replaces primary value (which would be garbage) with :ERROR if C-function returned ERR
Given a window WINDOW, return its width and height as two values respectively.
Write the character CHAR to the window WINDOW at the cursor.
Write the character CHAR to the window WINDOW at the coordinates (X, Y).
Write the string STRING to the window WINDOW at the cursor.
Write the string STRING to the window WINDOW at the coordinates (X, Y).
Previous: Ordinary functions, Up: Public Interface [Contents][Index]
A curses window.
Pointer to the underlying representation of a window pointer. (This is of CFFI type ‘CHARMS/LL:WINDOW-PTR’.)
:pointer
Previous: Public Interface, Up: Definitions [Contents][Index]
Next: Symbol macros, Previous: Internals, Up: Internals [Contents][Index]
Next: Macros, Previous: Special variables, Up: Internals [Contents][Index]
Next: Ordinary functions, Previous: Symbol macros, Up: Internals [Contents][Index]
Check the status of the resulting value VALUE to see if it is an error. If so, signal an error. If not, return the value.
Define libcurses functions using cffi:defcfun. If given multiple names, define each as a distinct C function but otherwise with the same signature. The resulting function names are exported from the current package.
Next: Generic functions, Previous: Macros, Up: Internals [Contents][Index]
Once a class of mouse events has been made visible in a window, calling the wgetch function on that window may return KEY_MOUSE as an indicator that a mouse event has been queued. To read the event data and pop the event off the queue, call getmouse. This function will return OK if a mouse event is actually visible in the given window, ERR otherwise. When getmouse returns OK, the data deposited as y and x in the event structure coordinates will be screen-relative character-cell coordinates. The returned state mask will have exactly one bit set to indicate the event type. The corresponding data in the queue is marked invalid. A subsequent call to getmouse will retrieve the next older item from the queue.
To make mouse events visible, use the mousemask function. This will set the
mouse events to be reported. By default, no mouse events are reported. The
function will return a mask to indicate which of the specified mouse events can
be reported; on complete failure it returns 0. If oldmask is non-NULL, this
function fills the indicated location with the previous value of the given
window’s mouse event mask.
As a side effect, setting a zero mousemask may turn off the mouse pointer; setting a nonzero mask may turn it on. Whether this happens is device-dependent.
The ungetmouse function behaves analogously to ungetch. It pushes a KEY_MOUSE event onto the input queue, and associates with that event the given state data and screen-relative character-cell coordinates.
Convert a C character to a Lisp character.
Convert a Lisp character to a C character.
Convert the value VALUE to a Lisp boolean. If RELAX is true, then all non-false values are true.
Convert the value VALUE to a foreign bool.
Next: Classes, Previous: Ordinary functions, Up: Internals [Contents][Index]
Previous: Generic functions, Up: Internals [Contents][Index]
Previous: Definitions, Up: The cl-charms Reference Manual [Contents][Index]
Jump to: | %
(
A B C D E F G H I K L M N O P Q R S T U V W |
---|
Jump to: | %
(
A B C D E F G H I K L M N O P Q R S T U V W |
---|
Next: Data types, Previous: Functions, Up: Indexes [Contents][Index]
Jump to: | *
A B C E F K O P R S T W |
---|
Jump to: | *
A B C E F K O P R S T W |
---|
Jump to: | C F H I L M O P S U W |
---|
Jump to: | C F H I L M O P S U W |
---|