(lisppad system)

Library (lisppad system) defines an API for scripting the LispPad user interface. This library is specific to LispPad and is not bundled with LispKit.

Library (lisppad system) provides functionality primarily for managing LispPad windows: new windows can be created, properties of existing windows can be changed, and the content of existing windows can be accessed and modified. There is also support for making use of simple dialogs, e.g. for displaying messages, asking the user to make a choice, or for letting the user choose a file or directory in a load or save panel.

Windows

(lisppad system) does not provide a data structure for modeling references to LispPad windows. Instead, it uses integer ids as references. Two different types of windows can be managed:

• Edit windows are used for editing text, and

• Graphics windows are used for displaying drawings created via library (lispkit draw).

Other types of windows are currently not accessible via library (lisppad system).

(open-document path)

Opens a document stored in a file at path path. Only documents that LispPad is able to open are supported.

(edit-windows)

Returns an association list containing all open edit windows. Each open window has an entry of the form (window id . window title). For example, the result of invoking (edit-windows) could look like this: ((106102873393392 . "LispKit Libraries.md") (106377751319520 . "Untitled")).

(graphics-windows)

Returns an association list containing all open graphics windows. Each open window has an entry of the form (window id . window title). For example, the result of invoking (graphics-windows) could look like this: ((106102873393789 . "My Drawing") (106377751899571 . "Untitled Drawing")).

(window-name win)

Returns the name of the window with window id win.

(window-position win)

Returns the position of the window with window id win. The position of a window is the upper left corner of its title bar represented as a point.

(set-window-position! win pos)

Sets the position of the window with window id win to point pos. The position of a window is the upper left corner of its title bar.

(window-size win)

Returns the size of the window with window id win. The size of a window consists of its width and height represented as a size.

(set-window-size! win size)

Sets the size of the window with window id win to size size. The size of a window consists of its width and height.

(close-window win)

Closes the window with window id win.

Edit Windows

(make-edit-window str pos size)

Creates a new edit window containing str as its textual content. The window's initial position is pos and its size is size.

(edit-window-text win)

Returns the textual content of the edit window with the given window id win.

(insert-edit-window-text! win str) (insert-edit-window-text! win str start) (insert-edit-window-text! win str start end)

Inserts a string str replacing text between start and end for the edit window with window id win. It start is not provided, start is considered to be 0 (i.e. the text is inserted at the beginning). If end is not provided, it is considered to be the length of the text contained in the edit window win.

(edit-window-text-length win)

Returns the length of the text contained in the edit window with window id win.

Graphics Windows

(make-graphics-window drawing dsize) (make-graphics-window drawing dsize title) (make-graphics-window drawing dsize title pos) (make-graphics-window drawing dsize title pos size)

Creates a new graphics window for drawing drawing. dsize refers to the size of the drawing. title is the window title of the new window, pos is its initial position, and size corresponds to the initial size of the graphics window.

(use-graphics-window drawing dsize title) (use-graphics-window drawing dsize title pos) (use-graphics-window drawing dsize title pos size) (use-graphics-window drawing dsize title pos size ignore)

This is almost equivalent to function make-graphics-window. The main difference consists in use-graphics-window reusing an existing graphics window if there is one open with the given title. If there is no window whose title matches title, a new graphics window will be created. If a window exists already and boolean argument ignore is set to #t, the existing window's position and size will not be updated.

(update-graphics-window win)

This function forces the graphics window with window id win to redraw its content. Currently, graphics windows are only guaranteed to redraw automatically after executing a command in the session window which was used to create the drawing object.

(graphics-window-drawing win)

Returns the drawing associated with the graphics window with window id win.

(set-graphics-window-drawing! win drawing)

Sets the drawing associated with the graphics window with window id win to drawing.

(graphics-window-label win)

Each graphics window has a label at the bottom of the window. This label can be arbitrarily modified, and e.g. used as a caption. graphics-window-label returns the label of the graphics window with window id win.

(set-graphics-window-label! win str)

Each graphics window has a label at the bottom of the window. The label of graphics window win can be set via function set-graphics-window-label! to string str.

(drawing-size win)

Returns the size of the drawing associated with graphics window win. Please note that this is not the window size of win.

(set-drawing-size! win size)

Sets the size of the drawing associated with graphics window win to size. Please note that this is not setting the window size of win.

Utilities

(screen-size) (screen-size win)

Returns the screen size of the screen on which window win is displayed. If argument win is omitted, function screen-size will return the size of the main screen.

(show-message-panel title) (show-message-panel title str) (show-message-panel title str button)

Shows a message panel within the current session window. title refers to the panel title, str is the message to be displayed_, and button is the label of the confirmation button.

(show-choice-panel title str) (show-choice-panel title str yes) (show-choice-panel title str yes no)

Shows a choice panel within the current session window. title refers to the panel title, str is the question to be asked, and yes and no refer to the two labels of the buttons for users to choose. The function returns #t if the user clicked on the "yes button".

(show-load-panel prompt) (show-load-panel prompt folders) (show-load-panel prompt folders filetypes)

Displays a load panel within the current session window together with the given prompt message. folders is a boolean argument; it should be set to #t if the user is required to select a folder. filetypes is a list of suffixes of selectable file types.

(show-save-panel prompt) (show-save-panel prompt filetypes)

Displays a save panel within the current session window together with the given prompt message. filetypes is a list of suffixes of selectable file types.

(session-id)

Returns a unique fixnum (within LispPad) identifying the session.

(session-name)

Returns the name of the LispPad session which executes this function.

(session-display obj) (session-display obj bold?) (session-display obj bold? col)

Displays value obj in the current session in color col and in bold if bold? is true.

(session-write obj) (session-write obj bold?) (session-write obj bold? col)

Writes the value obj into the current session in color col and in bold if bold? is true.

(session-log time sev str) (session-log time sev str tag)

Logs the message str with severity sev at the given timestamp time (a double value) in the session log. sev is one of the following symbols: debug, info, warn, error, or fatal.

(project-directory)

Returns the path to the project directory as defined in the preferences of LispPad. project-directory returns #f if no project directory was explicitly set.

(dark-mode?)

Return #t if the session window of the LispPad session which executes this function is rendered in dark mode; returns #f otherwise.

(sleep sec)

Sleeps for sec seconds.