172 lines
6.3 KiB
Groff
172 lines
6.3 KiB
Groff
|
.\" $XdotOrg: xc/doc/man/Xp/XpSetAttributes.man,v 1.1 2004/05/22 06:27:25 alanc Exp $
|
||
|
|
.\"
|
||
|
|
.\" Copyright 1996 Hewlett-Packard Company
|
||
|
|
.\" Copyright 1996 International Business Machines Corp.
|
||
|
|
.\" Copyright 1996, 1999, 2004 Sun Microsystems, Inc.
|
||
|
|
.\" Copyright 1996 Novell, Inc.
|
||
|
|
.\" Copyright 1996 Digital Equipment Corp.
|
||
|
|
.\" Copyright 1996 Fujitsu Limited
|
||
|
|
.\" Copyright 1996 Hitachi, Ltd.
|
||
|
|
.\" Copyright 1996 X Consortium, Inc.
|
||
|
|
.\"
|
||
|
|
.\" Permission is hereby granted, free of charge, to any person obtaining a
|
||
|
|
.\" copy of this software and associated documentation files (the "Software"),
|
||
|
|
.\" to deal in the Software without restriction, including without limitation
|
||
|
|
.\" the rights to use, copy, modify, merge, publish, distribute,
|
||
|
|
.\" sublicense, and/or sell copies of the Software, and to permit persons
|
||
|
|
.\" to whom the Software is furnished to do so, subject to the following
|
||
|
|
.\" conditions:
|
||
|
|
.\"
|
||
|
|
.\" The above copyright notice and this permission notice shall be
|
||
|
|
.\" included in all copies or substantial portions of the Software.
|
||
|
|
.\"
|
||
|
|
.\" THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
|
||
|
|
.\" EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
|
||
|
|
.\" MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
|
||
|
|
.\" IN NO EVENT SHALL THE COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM,
|
||
|
|
.\" DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR
|
||
|
|
.\" OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR
|
||
|
|
.\" THE USE OR OTHER DEALINGS IN THE SOFTWARE.
|
||
|
|
.\"
|
||
|
|
.\" Except as contained in this notice, the names of the copyright holders
|
||
|
|
.\" shall not be used in advertising or otherwise to promote the sale, use
|
||
|
|
.\" or other dealings in this Software without prior written authorization
|
||
|
|
.\" from said copyright holders.
|
||
|
|
.\"
|
||
|
|
.TH XpSetAttributes 3Xp __xorgversion__ "XPRINT FUNCTIONS"
|
||
|
|
.SH NAME
|
||
|
|
XpSetAttributes \- Sets or updates an attribute pool in the specified print
|
||
|
|
context.
|
||
|
|
.SH SYNOPSIS
|
||
|
|
.br
|
||
|
|
cc [ flag... ] file... -lXp [ library... ]
|
||
|
|
.br
|
||
|
|
#include <X11/extensions/Print.h>
|
||
|
|
.LP
|
||
|
|
.B void XpSetAttributes
|
||
|
|
(
|
||
|
|
.I display,
|
||
|
|
.I context,
|
||
|
|
.I type,
|
||
|
|
.I pool,
|
||
|
|
.I replacement_rule
|
||
|
|
)
|
||
|
|
.br
|
||
|
|
Display *\fIdisplay\fP\^;
|
||
|
|
.br
|
||
|
|
XPContext \fIcontext\fP\^;
|
||
|
|
.br
|
||
|
|
XPAttributes \fItype\fP\^;
|
||
|
|
.br
|
||
|
|
char *\fIpool\fP\^;
|
||
|
|
.br
|
||
|
|
XPAttrReplacement \fIreplacement_rule\fP\^;
|
||
|
|
.if n .ti +5n
|
||
|
|
.if t .ti +.5i
|
||
|
|
.SH ARGUMENTS
|
||
|
|
.TP
|
||
|
|
.I display
|
||
|
|
Specifies a pointer to the Display structure; returned from XOpenDisplay.
|
||
|
|
.TP
|
||
|
|
.I context
|
||
|
|
The print context whose attribute pool is to be modified.
|
||
|
|
.TP
|
||
|
|
.I type
|
||
|
|
Specifies the attribute pool.
|
||
|
|
.TP
|
||
|
|
.I pool
|
||
|
|
An attribute pool represented as a resource string. Encoded in COMPOUND_TEXT.
|
||
|
|
.TP
|
||
|
|
.I replacement_rule
|
||
|
|
Either XPAttrReplace orXPAttrMerge.
|
||
|
|
.SH DESCRIPTION
|
||
|
|
.LP
|
||
|
|
XpSetAttributes accepts pool, a COMPOUND_TEXT resource string representing new
|
||
|
|
name-value pairs for the attribute pool specified by type. The attribute pool
|
||
|
|
is modified by the new name-value pairs according to replacement_rule. For
|
||
|
|
XPAttrReplace, the existing attribute pool is discarded and replaced with
|
||
|
|
pool. For XPAttrMerge, pool is merged into the existing attribute pool;
|
||
|
|
pre-existing name-value pairs are replaced, and non-existing name-value pairs
|
||
|
|
are added. The contents of pool is not affected by this call, and can be freed
|
||
|
|
by the caller afterwards.
|
||
|
|
|
||
|
|
When setting supported attribute names, the X Print Server and associated
|
||
|
|
driver will validate the new values and ignore those that are invalid;
|
||
|
|
previous values remain unchanged. When setting unsupported (that is, unknown)
|
||
|
|
attribute names, no validation is done, and the name-value pairs will be set,
|
||
|
|
even though they will not be used. When deleting (that is, failing to reset
|
||
|
|
with XPAttrReplace) a supported attribute name, the X Print Server explicitly
|
||
|
|
or implicitly resets the attribute to a default value.
|
||
|
|
|
||
|
|
When setting certain supported attributes, the X Print Server may modify other
|
||
|
|
associated attributes. For example, considering the XPPrinterAttr attribute
|
||
|
|
document-formats-supported, setting the XPDocAttr attribute document-format
|
||
|
|
may cause a number of other attributes to change.
|
||
|
|
|
||
|
|
For attribute pools that are read-only (see "get only" in XPAttributes
|
||
|
|
definition), attempting to use XpSetAttributes generates a BadMatch. For
|
||
|
|
attribute pools that are writable, lists of the supported attributes can be
|
||
|
|
found in the XPPrinterAttr pool.
|
||
|
|
|
||
|
|
The lifetime of all attribute pools are bounded by the lifetime of the print
|
||
|
|
context they are contained in. When set, all attribute values will be retained
|
||
|
|
across all Xp operations, until changed by the user directly, the X Print
|
||
|
|
Server directly, or changed because of a side effect when either the user or X
|
||
|
|
Print Server changed another attribute value.
|
||
|
|
|
||
|
|
Refer to a complete description of all print attributes, the precedence
|
||
|
|
between print attributes, and the side effects of setting certain print
|
||
|
|
attributes on other print attributes, etc.
|
||
|
|
|
||
|
|
To monitor changes to the attribute pools, see XpSelectInput and the event
|
||
|
|
XPAttributeNotify. Since a print context can be shared among clients, changes
|
||
|
|
made by one client will be seen by all others, and if selected for, the event
|
||
|
|
XPAttributeNotify will be sent to all clients referencing the print context
|
||
|
|
when changes do occur. It is the responsibility of the clients sharing a print
|
||
|
|
context to coordinate their operations.
|
||
|
|
.SH STRUCTURES
|
||
|
|
The values for the typedef XPAttributes in <X11/extensions/Print.h> are:
|
||
|
|
.nf
|
||
|
|
|
||
|
|
#define XPJobAttr 1 /\(** get/set */
|
||
|
|
#define XPDocAttr 2 /\(** get/set */
|
||
|
|
#define XPPageAttr 3 /\(** get/set - subset of XPDocAttr */
|
||
|
|
#define XPPrinterAttr 4 /\(** get only (library) */
|
||
|
|
#define XPServerAttr 5 /\(** get only (library), no context needed */
|
||
|
|
|
||
|
|
.fi
|
||
|
|
The values for the typedef XPAttrReplacement in <X11/extensions/Print.h> are:
|
||
|
|
.nf
|
||
|
|
|
||
|
|
#define XPAttrReplace 1
|
||
|
|
#define XPAttrMerge 2
|
||
|
|
|
||
|
|
.fi
|
||
|
|
.SH DIAGNOSTICS
|
||
|
|
.TP 15
|
||
|
|
.SM BadAlloc
|
||
|
|
Insufficient memory.
|
||
|
|
.TP 15
|
||
|
|
.SM BadMatch
|
||
|
|
The attribute pool specified by pool cannot be set.
|
||
|
|
.TP 15
|
||
|
|
.SM BadValue
|
||
|
|
The value specified for type is not valid.
|
||
|
|
.TP 15
|
||
|
|
.SM XPBadContext
|
||
|
|
The specified print context-id is not valid.
|
||
|
|
.TP 15
|
||
|
|
.SM XPBadSequence
|
||
|
|
A request to set an attribute pool occurred at a time when the attribute pool
|
||
|
|
could not be modified (for example, modifying XPJobAttr immediately after
|
||
|
|
calling XpStartJob).
|
||
|
|
.SH FILES
|
||
|
|
.PD 0
|
||
|
|
.TP 20
|
||
|
|
<X11/extensions/Print.h>
|
||
|
|
.SH "SEE ALSO"
|
||
|
|
.BR XpSelectInput (3Xp),
|
||
|
|
.BR XpStartJob (3Xp)
|
||
|
|
|
||
|
|
|