---
title: LispPad System macOS
group: Libraries
anchor: lp-lisppad-system
order: 4
---

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)** &nbsp;&nbsp;&nbsp; <span style="float:right;text-align:rigth;">[procedure]</span>  

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)** &nbsp;&nbsp;&nbsp; <span style="float:right;text-align:rigth;">[procedure]</span>  

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_)** &nbsp;&nbsp;&nbsp; <span style="float:right;text-align:rigth;">[procedure]</span>  

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

**(edit-windows)** &nbsp;&nbsp;&nbsp; <span style="float:right;text-align:rigth;">[procedure]</span>  

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)** &nbsp;&nbsp;&nbsp; <span style="float:right;text-align:rigth;">[procedure]</span>  

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_)** &nbsp;&nbsp;&nbsp; <span style="float:right;text-align:rigth;">[procedure]</span>  

Returns the name of the window with window id _win_.

**(set-window-name! _win name_)** &nbsp;&nbsp;&nbsp; <span style="float:right;text-align:rigth;">[procedure]</span>  

Sets the name of the window with window id _win_ to string _name_.

**(window-position _win_)** &nbsp;&nbsp;&nbsp; <span style="float:right;text-align:rigth;">[procedure]</span>  

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_)** &nbsp;&nbsp;&nbsp; <span style="float:right;text-align:rigth;">[procedure]</span>  

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_)** &nbsp;&nbsp;&nbsp; <span style="float:right;text-align:rigth;">[procedure]</span>  

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_)** &nbsp;&nbsp;&nbsp; <span style="float:right;text-align:rigth;">[procedure]</span>  

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_)** &nbsp;&nbsp;&nbsp; <span style="float:right;text-align:rigth;">[procedure]</span>  

Closes the window with window id _win_.


## Edit Windows

**(make-edit-window _str pos size_)** &nbsp;&nbsp;&nbsp; <span style="float:right;text-align:rigth;">[procedure]</span>  

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_)** &nbsp;&nbsp;&nbsp; <span style="float:right;text-align:rigth;">[procedure]</span>  

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

**(insert-edit-window-text! _win str_)** &nbsp;&nbsp;&nbsp; <span style="float:right;text-align:rigth;">[procedure]</span>  
**(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_)** &nbsp;&nbsp;&nbsp; <span style="float:right;text-align:rigth;">[procedure]</span>  

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_)** &nbsp;&nbsp;&nbsp; <span style="float:right;text-align:rigth;">[procedure]</span>  
**(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_)** &nbsp;&nbsp;&nbsp; <span style="float:right;text-align:rigth;">[procedure]</span>  
**(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_)** &nbsp;&nbsp;&nbsp; <span style="float:right;text-align:rigth;">[procedure]</span>  

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_)** &nbsp;&nbsp;&nbsp; <span style="float:right;text-align:rigth;">[procedure]</span>  

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

**(set-graphics-window-drawing! _win drawing_)** &nbsp;&nbsp;&nbsp; <span style="float:right;text-align:rigth;">[procedure]</span>  

Sets the drawing associated with the graphics window with window id _win_ to _drawing_.

**(graphics-window-label _win_)** &nbsp;&nbsp;&nbsp; <span style="float:right;text-align:rigth;">[procedure]</span>  

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_)** &nbsp;&nbsp;&nbsp; <span style="float:right;text-align:rigth;">[procedure]</span>  

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_)** &nbsp;&nbsp;&nbsp; <span style="float:right;text-align:rigth;">[procedure]</span>  

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

**(set-graphics-window-background! _win color_)** &nbsp;&nbsp;&nbsp; <span style="float:right;text-align:rigth;">[procedure]</span>  

Sets the background color for the graphics window with id _win_ to _color_.

**(drawing-size _win_)** &nbsp;&nbsp;&nbsp; <span style="float:right;text-align:rigth;">[procedure]</span>  

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_)** &nbsp;&nbsp;&nbsp; <span style="float:right;text-align:rigth;">[procedure]</span>  

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_)** &nbsp;&nbsp;&nbsp; <span style="float:right;text-align:rigth;">[procedure]</span>  

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_)** &nbsp;&nbsp;&nbsp; <span style="float:right;text-align:rigth;">[procedure]</span>  

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


## Navigation

**(show-message-panel _title_)** &nbsp;&nbsp;&nbsp; <span style="float:right;text-align:rigth;">[procedure]</span>  
**(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_)** &nbsp;&nbsp;&nbsp; <span style="float:right;text-align:rigth;">[procedure]</span>  
**(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_)** &nbsp;&nbsp;&nbsp; <span style="float:right;text-align:rigth;">[procedure]</span>  
**(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_)** &nbsp;&nbsp;&nbsp; <span style="float:right;text-align:rigth;">[procedure]</span>  
**(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_)** &nbsp;&nbsp;&nbsp; <span style="float:right;text-align:rigth;">[procedure]</span>  

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

**(search-help _str_)** &nbsp;&nbsp;&nbsp; <span style="float:right;text-align:rigth;">[procedure]</span>  

Searches all documentation for string _str_ and shows all matches.


## Sessions

**(session-id)** &nbsp;&nbsp;&nbsp; <span style="float:right;text-align:rigth;">[procedure]</span>  

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

**(session-name)** &nbsp;&nbsp;&nbsp; <span style="float:right;text-align:rigth;">[procedure]</span>  

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

**(session-display _obj_)** &nbsp;&nbsp;&nbsp; <span style="float:right;text-align:rigth;">[procedure]</span>  
**(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_)** &nbsp;&nbsp;&nbsp; <span style="float:right;text-align:rigth;">[procedure]</span>  
**(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_)** &nbsp;&nbsp;&nbsp; <span style="float:right;text-align:rigth;">[procedure]</span>  
**(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)** &nbsp;&nbsp;&nbsp; <span style="float:right;text-align:rigth;">[procedure]</span>  
**(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?)** &nbsp;&nbsp;&nbsp; <span style="float:right;text-align:rigth;">[procedure]</span>  

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