-<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN" "http://www.w3.org/TR/REC-html40/loose.dtd">
+<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
<html>
<!-- SECTION: Specifications -->
<head>
CUPS PPD extensions specification for the Common UNIX Printing System (CUPS).
- Copyright 2007-2008 by Apple Inc.
+ Copyright 2007-2009 by Apple Inc.
Copyright 1997-2007 by Easy Software Products.
These coded instructions, statements, and computer programs are the
file is missing or damaged, see the license at "http://www.cups.org/".
-->
+<H1 CLASS="title">CUPS PPD Extensions</H1>
+
<h2 class='title'><a name='INTRODUCTION'>Introduction</a></h2>
<p>This specification describes the attributes and extensions
<p class='summary'>*APCustomColorMatchingProfile: name</p>
<p>This attribute defines a supported RGB color profile that can be used
-when doing custom color matching. Currently only <tt>sRGB</tt> and
-<tt>AdobeRGB</tt> are supported. If not specified, RGB data will use the
-Generic RGB colorspace.</p>
+when doing custom color matching. Currently only <tt>sRGB</tt>,
+<tt>AdobeRGB</tt>, and <tt>GenericRGB</tt> are supported. If not specified, RGB
+data will use the GenericRGB colorspace.</p>
<blockquote><b>Note:</b>
<p class='summary'>*APDefaultCustomColorMatchingProfile: name</p>
<p>This attribute defines the default RGB color profile that will be used
-when doing custom color matching. Currently only <tt>sRGB</tt> and
-<tt>AdobeRGB</tt> are supported.</p>
+when doing custom color matching. Currently only <tt>sRGB</tt>,
+<tt>AdobeRGB</tt>, and <tt>GenericRGB</tt> are supported.</p>
<p>Examples:</p>
<p>This attribute specifies that the driver provides its own custom color
matching. When <tt>true</tt>, the default hand-off colorspace will be
-Generic Gray, Generic RGB, or Generic CMYK depending on the number of
+GenericGray, GenericRGB, or GenericCMYK depending on the number of
components the driver requests. The <a
href='#APDefaultCustomColorMatchingProfile'><tt>APDefaultCustomColorMatchingProfile</tt></a>
attribute can be used to override the default 3-component (RGB) colorspace.</p>
<p>CUPS 1.4 and higher define two new attributes for constraints,
<tt>cupsUIConstraints</tt> and <tt>cupsUIResolver</tt>. Each
<tt>cupsUIConstraints</tt> attribute points to a <tt>cupsUIResolver</tt>
-attribute which corrects the conflict condition. The same
-<tt>cupsUIResolver</tt> can be used by multiple <tt>cupsUIConstraints</tt>.</p>
+attribute which specifies alternate options that resolve the conflict condition.
+The same <tt>cupsUIResolver</tt> can be used by multiple
+<tt>cupsUIConstraints</tt>.</p>
+
+<blockquote><b>Note:</b>
+
+ <p>When developing PPD files that contain constraints, it is very important
+ to use the <a href="man-cupstestppd.html">cupstestppd(1)</a> program to
+ verify that your constraints are accurate and cannot result in unresolvable
+ option selections.</p>
+
+</blockquote>
<h3><span class='info'>CUPS 1.4</span><a name='cupsUIConstraints'>cupsUIConstraints</a></h3>
<p>Lists two or more options which conflict. The "resolver" string is a
(possibly unique) keyword which specifies which options to change when the
-constraint exists. When no resolver is provided, a "revert to defaults"
-change is assumed - this type of constraint is typically only used for
-installable options.</p>
+constraint exists. When no resolver is provided, CUPS first tries the default
+choice followed by testing each option choice to resolve the conflict.</p>
<p>Examples:</p>
<em>*% Specify that 2-sided printing cannot happen on transparencies</em>
*cupsUIConstraints transparency: "*Duplex *MediaType Transparency"
+<em>*% Specify that envelope printing cannot happen from the paper trays</em>
+*cupsUIConstraints envelope: "*PageSize Env10 *InputSlot Tray1"
+*cupsUIConstraints envelope: "*PageSize Env10 *InputSlot Tray1"
+*cupsUIConstraints envelope: "*PageSize EnvDL *InputSlot Tray2"
+*cupsUIConstraints envelope: "*PageSize EnvDL *InputSlot Tray2"
+
+<em>*% Specify an installable option constraint for the envelope feeder</em>
+*cupsUIConstraints: "*InputSlot EnvFeeder *InstalledEnvFeeder"
+
<em>*% Specify that photo printing cannot happen on plain paper or transparencies at 1200dpi</em>
*cupsUIConstraints photo: "*OutputMode Photo *MediaType Plain *Resolution 1200dpi"
*cupsUIConstraints photo: "*OutputMode Photo *MediaType Transparency *Resolution 1200dpi"
<h3><span class='info'>CUPS 1.4</span><a name='cupsUIResolver'>cupsUIResolver</a></h3>
-<p class='summary'>*cupsUIResolution resolver: "*Keyword OptionKeyword ..."</p>
+<p class='summary'>*cupsUIResolution resolver: "*Keyword1 OptionKeyword1 *Keyword2 OptionKeyword2 ..."</p>
-<p>Specifies one or more options to mark/select to resolve a constraint. The
+<p>Specifies two or more options to mark/select to resolve a constraint. The
"resolver" string identifies a particular action to take for one or more
<a href='#cupsUIConstraints'><tt>cupsUIConstraints</tt></a>. The same action
-can be used for multiple constraints.</p>
+can be used for multiple constraints. The option keyword pairs are treated as
+an ordered list of option selections to try - only the first N selections will
+be used, where N is the minimum number of selections required. Because
+<a href="api-ppd.html#cupsResolveConflicts"><code>cupsResolveConflicts()</code></a>
+will not change the most recent option selection passed to it, at least two
+options from the constraints must be listed to avoid situations where conflicts
+cannot be resolved.</p>
<p>Examples:</p>
<pre class='command'>
-<em>*% Specify the option to change for the 2-sided transparency constraint</em>
-*cupsUIResolver transparency: "*Duplex None"
+<em>*% Specify the options to change for the 2-sided transparency constraint</em>
+*cupsUIResolver transparency: "*Duplex None *MediaType Plain"
+
+<em>*% Specify the options to change for the envelope printing constraints. Notice
+*% that we try to change the InputSlot to either the envelope feeder or the
+*% manual feed first, then we change the page size...</em>
+*cupsUIResolver envelope: "*InputSlot EnvFeeder *InputSlot ManualFeed *PageSize Letter"
<em>*% Specify the options to change for the photo printing constraints</em>
*cupsUIResolver photo: "*OutputMode Best *Resolution 600dpi"
*cupsPreFilter: "image/png 0 mypngprefilter"
</pre>
+<h3><span class='info'>CUPS 1.4</span><a name='cupsSNMPSupplies'>cupsSNMPSupplies</a></h3>
+
+<p class='summary'>*cupsSNMPSupplies: boolean</p>
+
+<p>This attribute tells the standard network backends whether they should query
+the standard SNMP Printer MIB OIDs for supply levels. The default value is
+<code>True</code>.
+
+<p>Example:</p>
+
+<pre class='command'>
+<em>*% Do not use SNMP queries to report supply levels</em>
+*cupsSNMPSupplies: False
+</pre>
+
<h3><a name='cupsVersion'>cupsVersion</a></h3>
<p class='summary'>*cupsVersion: major.minor</p>
<h3><span class='info'>Mac OS X 10.3</span><a name='APPrinterIconPath'>APPrinterIconPath</a></h3>
-<p class='summary'>*APPrinterIconPath: "/Library/Printers/vendor/filename"</p>
+<p class='summary'>*APPrinterIconPath: "/Library/Printers/vendor/filename.icns"</p>
<p>This attribute defines the location of a printer icon file to use when
-displaying the printer.</p>
+displaying the printer. The file must be in the Apple icon format.</p>
<p>Examples:</p>
<pre class='command'>
*% Apple icon file
*APPrinterIconPath: "/Library/Printers/vendor/Icons/filename.icns"
-
-*% TIFF icon file
-*APPrinterIconPath: "/Library/Printers/vendor/Icons/filename.tiff"
-
-*% PNG icon file
-*APPrinterIconPath: "/Library/Printers/vendor/Icons/filename.png"
-
-*% JPEG icon file
-*APPrinterIconPath: "/Library/Printers/vendor/Icons/filename.jpg"
</pre>
<h3><span class='info'>Mac OS X 10.4</span><a name='APPrinterLowInkTool'>APPrinterLowInkTool</a></h3>
*APPrinterPrinterUtilityPath: "/Library/Printers/vendor/Tools/utility.app"
</pre>
+<h3><span class='info'>Mac OS X 10.6</span><a name='APScannerOnly'>APScannerOnly</a></h3>
+
+<p class='summary'>*APScannerOnly: boolean</p>
+
+<p>This attribute specifies whether the device has scanning but no printing
+capabilities. The default is <tt>False</tt>.</p>
+
+<p>Examples:</p>
+
+<pre class='command'>
+*APICADriver: True
+*APScannerOnly: True
+</pre>
+
<h3><span class='info'>Mac OS X 10.3</span><a name='APScanAppBundleID'>APScanAppBundleID</a></h3>
<p class='summary'>*APScanAppBundleID: "bundle ID"</p>
<li>Added <a href='#cupsPJLDisplay'><tt>cupsPJLDisplay</tt></a>
attribute.</li>
+ <li>Added <a href='#cupsSNMPSupplies'><tt>cupsSNMPSupplies</tt></a>
+ attribute.</li>
+
<li>Added <a href='#cupsUIResolver'><tt>cupsUIResolver</tt></a> and
<a href='#cupsUIConstraints'><tt>cupsUIConstraints</tt></a>
attributes.</li>
projects / thirdparty / cups.git / blobdiff