# LispPad System macOS

Library `(lisppad system macos)` defines an API for scripting the LispPad user interface on macOS. Procedures that match the same functionality on iOS are also available via library `(lisppad system)`.

Library `(lisppad system macos)` 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.

## Files

(project-directory) [procedure]

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.

(icloud-directory) [procedure]

Returns the path to the iCloud directory. `icloud-directory` returns `#f` if iCloud synchronization is disabled.

## Windows

`(lisppad system macos)` 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 macos)`.

(open-document path) [procedure]

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

(edit-windows) [procedure]

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) [procedure]

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) [procedure]

Returns the name of the window with window id win.

(set-window-name! win name) [procedure]

Sets the name of the window with window id win to string name.

(window-position win) [procedure]

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) [procedure]

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) [procedure]

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) [procedure]

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) [procedure]

Closes the window with window id win.

## Edit Windows

(make-edit-window str pos size) [procedure]

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) [procedure]

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

(insert-edit-window-text! win str) [procedure]
(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) [procedure]

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

## Graphics Windows

A graphics window displays a drawing in a canvas of a given minimum drawing size (different from the window size). A scaling factor can be utilized to adjust the size of the drawing to the window. Furthermore, the background color of the drawing can be freely adjusted. There is a graphics window label at the bottom of graphic windows which can be used to display a line of text.

(make-graphics-window drawing dsize) [procedure]
(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) [procedure]
(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) [procedure]

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) [procedure]

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

(set-graphics-window-drawing! win drawing) [procedure]

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

(graphics-window-label win) [procedure]

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) [procedure]

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.

(graphics-window-background win) [procedure]

Returns the background color for the graphics window with id win. By default, the background color is white.

(set-graphics-window-background! win color) [procedure]

Sets the background color for the graphics window with id win to color.

(drawing-size win) [procedure]

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) [procedure]

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.

(drawing-scale win) [procedure]

Returns the scaling factor used for showing the drawing in graphics window with id win. By default, the scaling factor is 1.0.

(set-drawing-scale! win factor) [procedure]

Sets the scaling factor used for showing the drawing in graphics window with id win to factor.

## Navigation

(show-message-panel title) [procedure]
(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) [procedure]
(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) [procedure]
(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) [procedure]
(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.

(show-help name) [procedure]

Shows documentation for identifier name (string), if available.

(search-help str) [procedure]

Searches all documentation for string str and shows all matches.

## Sessions

(session-id) [procedure]

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

(session-name) [procedure]

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

(session-display obj) [procedure]
(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) [procedure]
(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) [procedure]
(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`.

## Environment

(screen-size) [procedure]
(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.

(dark-mode?) [procedure]

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