6    X-Specific Operators for WS

The Display PostScript system extends the PostScript language to include operators for generic window-related tasks; but for tasks that relate specifically to X, the window system of UWS, additional operators are needed. To fill this need, UWS extends the PostScript language to include X-specific operators.

This chapter describes the X-specific operators for UWS.

The Client Library defines single-operator procedures that execute the X-specific operators. For information on these procedures, see Chapter 5.

6.1    About the Operators

The operators described in the rest of this chapter are arranged alphabetically by operator name. Each description follows this format:

operand1 .. operandN operator result1 ... resultM

.SP Text describing what the operator does

EXAMPLE: (Optional)

Sample PostScript language code showing how to use the operator

ERRORS:

comma-separated list of errors this operator might execute

Each operator description begins with a syntax summary. In it, operand1 through operandN are the operands that the operator requires; operand1 is the top element on the operand stack. A dash (--) in the operand position means the operator accepts no operands.

The operator pops the operands from the stack, and processes them. After executing, the operator pushes result1 through resultM on the stack; resultM is the top element. A dash (--) in the result position means the operator returns no results.

Table 6-1 describes the values used as operands and results by the X-specific operators for WS. All operands are required.

Table 6-1: Operands and Results for X-Specific Operators

Note that drawable, gc, x, and y are part of the PostScript graphics state, which can be saved and restored using the PostScript language operators gsave and grestore.

6.2    Operator Errors

Table 6-2 describes the errors for the X-specific operators.

Table 6-2: Errors for X-Specific Operators

6.3    Operator Descriptions

Following is an alphabetical list and description of the X-specific operators for WS. The format for these descriptions is explained in Section 6.1.

-- clientsync --

The clientsync operator pauses the current context, sets the status of the context to FROZEN, and causes the X server to return a PSFROZEN status event. The context stays frozen until the application calls the Client Library routine XDPSUnfreezeContext(). Thus, clientsync synchronizes the application with the current context.

One possible use of clientsync is to display PostScript language output one page at a time by pausing the current context after each page, as in the following example. This example redefines the operator showpage, so that the operator first pauses the current context.

EXAMPLE:

     /showpage {
     clientsync
     showpage
     } bind def

ERRORS:

None

-- currentXgcdrawable gc drawable x y

The currentXgcdrawable operator returns the X Graphic Context, drawable, and default user space origin of the current context.

Note that the results returned by currentXgcdrawable can be used as the operands of setXgcdrawable.

ERRORS:

undefined

-- currentXgcdrawablecolor gc drawable x y colorinfo

The currentXgcdrawablecolor operator returns the GC, drawable, default user space origin, and color attributes of the current context.

Note that the results returned by currentXgcdrawablecolor can be used as the operands of setXgcdrawablecolor.

ERRORS:

undefined

-- currentXoffset x y

The currentXoffset operator returns the default user space origin of the current context.

Note that the results returned by currentXoffset can be used as the operands of setXoffset.

ERRORS:

undefined

red green blue setrgbXactual success

The setrgbXactual operator allocates a new colormap entry to display the color specified by red, green, blue. If the allocation succeeds (if success is nonzero), future painting of this color uses the new colormap entry instead of dithering from the colorcube.

Note that setrgbXactual does not affect the graphics state. Thus, to paint with the specified color, you must first execute the operator setrgbcolor.

ERRORS:

stackunderflow, undefined, typecheck

gc drawable x y setXgcdrawable --

The setXgcdrawable operator sets the X Graphic Context, drawable, and default user space origin of the current context. The values supplied as operands supersede any existing values for these attributes. The setXgcdrawable operator causes all subsequent operations of the current context to occur in the specified X drawable, with the specified Graphic Context and default user space origin.

To make the effects of setXgcdrawable temporary, use it between the operators gsave and grestore.

ERRORS:

rangecheck, stackunderflow, typecheck, undefined

gc drawable x y colorinfo setXgcdrawablecolor --

The setXgcdrawablecolor operator sets the GC, drawable, default user space origin, and color attributes of the current context.

ERRORS:

rangecheck, stackunderflow, typecheck, undefined

x y setXoffset --

The setXoffset operator sets the default user space origin for the current context.

ERRORS:

stackunderflow, undefined