write-string-with-properties

write-string-with-properties 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`
	The face that the compiler uses when it outputs an error to an editor buffer.
`:compiler-warning-highlight`
	The face that the compiler uses when it outputs a warning to an editor buffer.
`:compiler-note-highlight`
	The face that the compiler uses when it outputs a note 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.

Examples

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*)

Notes

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.