Add -template option to nsimage.

1 files changed, 106 insertions, 0 deletions

diff --git a/doc/nsimage.n b/doc/nsimage.n
new file mode 100644
index 0000000..1807927
--- /dev/null
+++ b/doc/nsimage.n
@@ -0,0 +1,106 @@
+'\"
+'\" Copyright (c) 2022 Marc Culler
+'\"
+'\" See the file "license.terms" for information on usage and redistribution
+'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
+'\"
+.TH nsimage n 8.7 Tk "Tk Built-In Commands"
+.so man.macros
+.BS
+'\" Note:  do not modify the .SH NAME line immediately below!
+.SH NAME
+nsimage \- A Tk image type for macOS based on the NSImage class.
+.BE
+.SH DESCRIPTION
+The nsimage is implemented as a Tk image type.  The \fBimage\fR
+command is used to create, delete, and query all images, including
+images of type \fBnsimage\fR.  The options that are available are
+specific to the nsimage type and are described below.
+.PP
+The command to create an \fBnsimage\fR:
+.TP
+\fBimage create nsimage \fR?\fIname\fR? ?\fIoption value ...\fR?
+.PP
+creates a new nsimage and a command with the same name and returns its
+name.
+.SH OPTIONS
+.PP
+Valid \fIoptions\fR are:
+.TP
+\fB\-source\fR
+.PP
+The value of the \fB\-source\fR option is a string describing an
+NSimage.  There are several ways to interpret this string, and the
+interpretation is determined by the value of the \fB\-as\fR option.
+This option is required.
+.PP
+.TP
+\fB\-as\fR
+.PP
+There are four possible values for the \fB-as\fR option which specify
+how the source string should be interpreted.  The allowed values and
+their meanings are:
+.IP
+\fBname\fR
+.IP
+The source should be interpreted as the name of a named NSImage
+provided by the system.  This is the default if the -as option is not specified.
+.IP
+\fBfile\fR
+.IP
+The source should be interpreted as a path to an image
+file in one of the formats understood by the NSImage class.
+.IP
+\fBpath\fR
+.IP
+The source should be interpreted as a path to an arbitrary
+file. The type of the file will be examined and the resulting image
+will be the system icon for files of that type.
+.IP
+\fBfiletype\fR
+.IP
+The source is interpreted as a string identifying a
+particular file type.  It may be a filename extension, an Apple Uniform Type
+Identifier or a 4-character OSType value as used in the HFS filesystem.
+.TP
+\fB\-width\fR
+.PP
+The value of the \fIwidth\fR option is an integer specifying the width
+ in pixels of the nsimage.  The default value is 32pp. 
+.TP
+\fB-height\fR
+.PP
+The value of the \fIheight\fR option is an integer specifying the
+ height in pixels of the nsimage. The default value is 32pp. 
+.TP
+\fB-alpha\fR
+.PP
+The value of the \fIalpha\fR option should be a floating point number
+between 0.0 and 1.0.  This alpha value will be applied to each pixel
+of the nsimage, producing a partially transparent image.  The default value
+is 1,0, which makes the image opaque.
+.TP
+\fB-pressed\fR
+.PP
+The \fIpressed\fR option takes a boolean value.  If the value is true
+or 1 then the image will be algorithmically modified to become darker
+in light mode or lighter in dark mode.  The default is false.  For an
+image button, the primary image should use the value false while the
+pressed image should be the same image but with the \fIpressed\fR
+option set to true.
+.TP
+\fB-template\fR
+.PP
+The \fItemplate\fR option takes a boolean value.  If the value is true
+or 1 then the image will be marked as being a template image.  This
+means that the system will algorithmically convert the image to a
+light colored image when in dark mode.  For the algorithm to work
+correctly the image must consist only of black pixels with alpha
+values.
+.SH "SEE ALSO"
+image(n), options(n), photo(n)
+.SH KEYWORDS
+height, image, types of images, width
+'\" Local Variables:
+'\" mode: nroff
+'\" End: