Function

Summary

Writes the string to the stream, and adds properties if the stream supports it.

Package

hcl

Signature

write-string-with-properties string properties &optional stream &key start end => string

Arguments

string

A string.

properties

A property list.

stream

An output stream designator.

start, end

Bounding index designators of string.

Values

string

A string.

Description

The function write-string-with-properties writes a part of string, bounded by start and end, to stream exactly like cl:write-string does, and then adds properties if stream supports this operation. Currently the only types of stream that support properties are Editor streams, which means streams that write to Editor buffers.

properties must be a property list, with alternating key and value. When adding the properties, each pair of key and value is processed separately, in the order they occur in the list.

If key is :highlight, then value must specify a editor:face. It can be an editor:face object, a face name (which means a symbol that was used as the name in editor:make-face), or one of the following keywords:

:underline

Underline the text.

:bold

Make the text bold.

:italic

Make the text italic.

:bold-italic

Make the text bold and italic.

:inverse

Invert the background and foreground.

:compiler-error-highlight

or :compiler-warning-highlight

or :compiler-note-highlight

The faces that the compiler use when it outputs to an editor buffer.

:editor-error-highlight

The face that the editor uses in the echo area when it reports an editor error.

If key is :menu-items, value specifies menu items that are added to the context menu that is displayed when the current point is inside string in the Editor buffer. The value must a list where each element specifies a menu-item by a list of three elements: title , function and arg. title must be a string, and is what the end user sees. If the user selects this item, function is called with arg as a single argument.

 

If key is not :menu-items or :highlight, the key / value is added as a text property using editor:put-text-property, with key as the property argument and value as value.

Example

Output "A string in bold" in bold face to mp:*background-standard-output*:

(write-string-with-properties

       "A string in bold"

        '(:highlight :bold)

        mp:*background-standard-output*)

Note

write-string-with-properties can be used where ever write-string is used, because it does exactly the same for streams that do not implement properties.

The LispWorks compiler uses write-string-with-properties to write compiler errors, warnings and notes with :complier-...-highlight keywords above. This is how it produces the colored errors/warnings/notes when it writes to the Listener or is invoked in the Editor.

Support for :menu-items is implemented by the method:

(method capi:pane-popup-menu-items

         (capi:editor-pane capi:interface))

Therefore, if this method is not called, for example if you make a capi:editor-pane and pass it :pane-menu, then items will not be added to the menu.

See also

cl:write-string