PATH  Documentation > Mac OS X > Application Kit Reference: Objective-C

Table of Contents

Client Library Functions

Note: This section has not been updated and has not received recent technical review. It is included in this release to test the linkage between application development tools and on-line documentation. The information in this section should be considered at best preliminary and subject to change. An updated version of this file will be included in the next release.


DPSAddFD

Summary: Monitor a file descriptor

Declared in: dpsclient/dpsNeXT.h

Synopsis: void DPSAddFD(int fd, DPSFDProc handler, void *userData, int priority)

Description: DPSAddFD registers the function handler to be called each time there is activity with the file specified by file descriptor fd. The function is called provided the following are true:

DPSFDProc, handler's defined type, takes the form

void *handler(int fd, void *userData)

where fd is the file descriptor that prompted the function call and userData is the same pointer that was passed as the third argument to DPSAddFD. The userData pointer is provided as a convenience, allowing you to pass arbitrary data to handler.

Typically, DPSAddFD is used to listen to a socket or pipe; it's rarely used to monitor a common file.

See also: DPSAddPort, DPSAddTimedEntry, DPSRemoveFD


DPSAddNotifyPortProc

Summary: Set the handler function for the notify port

Declared in: dpsclient/dpsNeXT.h

Synopsis: void DPSAddNotifyPortProc(DPSPortProc handler, void *userData)

Description: DPSAddNotifyPortProc registers handler as the function that's called when a message arrives on the notify port, the unique port, created through the task_notify Mach function, on which notifications (such as port death) are sent. You don't need to create the notify port yourself; DPSAddNotifyPortProc creates it for you if it doesn't already exist.

DPSPortProc, handler's defined type, takes the form

void *handler(msg_header_t *msg, void *userData)

where msg is a pointer to the message that was received at the port and userData is the same pointer that was passed as the second argument to DPSAddNotifyPortProc. The userData pointer is provided as a convenience, allowing you to pass arbitrary data to handler.

The notify port can have only one handler at a time; adding a handler removes the current one. You can remove the port's handler without specifying a new one with the DPSRemoveNotifyPortProc function. The function's argument must match the notify port's current handler.

See also: DPSAddPort, DPSAddTimedEntry, DPSRemoveNotifyPortProc


DPSAddPort

Summary: Monitor a Mach port

Declared in: dpsclient/dpsNeXT.h

Synopsis: void DPSAddPort(port_t port, DPSPortProc handler, int maxMsgSize, void *userData, int priority)

Description: DPSAddPort registers the function handler to be called each time your application asks for an event or peeks at the event queue. The function is called provided the following are true:

DPSPortProc, handler's defined type, takes the form

void *handler(msg_header_t *msg, void *userData)

where msg is a pointer to the message that was received at the port and userData is the same pointer that was passed as the fourth argument to DPSAddPort. The userData pointer is provided as a convenience, allowing you to pass arbitrary data to handler.

If, within handler, you want to call msg_receive to receive further messages at the port, you must first call DPSRemovePort to remove the port from the system's port set. (This is because your application can't receive messages from a port that's in a port set.) After your application is finished receiving messages directly from the port, it can call DPSAddPort to have the system continue to monitor the port.

The contents of the message buffer msg, as received by handler, are invalid after the function returns. If you need to save any of the information that you find.

The maxMsgSize argument is an integer that gives the size, in bytes, of the largest message you expect to receive.

See also: DPSAddFD, DPSAddTimedEntry, DPSRemovePort


DPSAddTimedEntry

Summary: Create a timed entry

Declared in: dpsclient/dpsNeXT.h

Synopsis: DPSTimedEntry DPSAddTimedEntry(double period, DPSTimedEntryProc handler, void *userData, int priority)

Description: DPSAddTimedEntry registers handler as a "timed entry," a function that's called repeatedly at a given time interval. period determines the number of seconds between calls to the timed entry. Whenever an application based on the Application Kit attempts to retrieve events from the event queue, it also checks (depending on priority) to determine whether any timed entries are due to be called. userData is a pointer that you can use to pass some data to the timed entry.

The function registered as handler has the form:

void *handler(DPSTimedEntry tag, double now, void *userData)

where tag is the timed entry identifier returned by DPSAddTimedEntry, now is the number of seconds since some arbitrary point in the past, and userData is the pointer DPSAddTimedEntry received when this timed entry was installed.

An application's priority threshold can be set explicitly as an integer from 0 to 31 through a call to DPSGetEvent or DPSPeekEvent. It's against this threshold that priority is measured (note that priority can be no greater than 30-the additional threshold level, 31, is provided to disallow all inter-event function calls). However, if you're using the Application Kit, you should access the event queue through Application class methods such as getNextEvent:. Although some of these methods let you set the priority threshold explicitly, you typically invoke the methods that set it automatically. Such methods use only three priority levels:

Constant Meaning
NX_BASETHRESHOLD Normal execution
NX_RUNMODALTHRESHOLD An attention panel is being run
NX_MODALRESPTHRESHOLD A modal event loop is being run

When applicable, you should use these constants as the value for priority. For example, if you want handler to be called during normal execution, but not if an attention panel or a modal loop is running, then you would set priority to NX_BASETHRESHOLD.

Return: DPSAddTimedEntry returns a number identifying the timed entry or -1 to indicate an error.

See also: DPSRemoveTimedEntry


DPSAsynchronousWaitContext

Summary: Proceed asynchronously while PostScript code is executed

Declared in: dpsclient/dpsNeXT.h

Synopsis: void DPSAsynchronousWaitContext(DPSContext context, DPSPingProc handler,
void *userData)

Description: This function is similar to the more familiar DPSWaitContext functions, except that rather than wait for all PostScript code to execute, it returns immediately, allowing your application to proceed while the PostScript code is executed in the background. The DPSPingProc function handler is called (with context and userData as its two arguments) when all the PostScript code has been executed. The DPSPingProc function takes the form

void *handler(DPSContext context, void *userData);


Warning: Be careful when you use this function; you must not send more PostScript code while waiting for the handler to be called. In general, it's best to not make any demands on the Application Kit or the Client Library if you're waiting for an asynchronous handler to return.


DPSCreateContext

Summary: Create a PostScript execution context

Declared in: dpsclient/dpsNeXT.h

Synopsis: DPSContext DPSCreateContext(const char *hostName, const char *serverName, DPSTextProc textProc, DPSErrorProc errorProc)

Description: DPSCreateContext establishes a connection with the Window Server and creates a PostScript execution context in it. The new context becomes the current context. The first argument, hostName, identifies the machine that's running the Window Server; the second argument, serverName, identifies the Window Server that's running on that machine. With these two arguments and the help of the Mach network server nmserver, the Mach port for the Window Server can be identified. If hostName is NULL, the network server on the local machine is queried for the Window Server's port. If serverName is NULL, a default name for the Window Server is used.

The last two arguments, textProc and errorProc, refer to call-back functions (defined in the Client Library specification) that handle text returned from the Window Server and errors generated on either side of the connection.

For an application that's based on the Application Kit, you could create an additional context by making this call:

DPSContext c;

c = DPSCreateContext(NXGetDefaultValue([NXApp appName], "NXHost"),
XGetDefaultValue([NXApp appName], "NXPSName"),
NULL,
NULL);

This example queries the application's default values for the identity of the host machine and the Window Server. By doing this, the new context is created in the correct Window Server even if that Server is not on the same machine as the application process.

The context that DPSCreateContext creates allocates memory from the default allocation zone. Also, when there's difficulty creating the context, DPSCreateContext waits up to 60 seconds before raising an exception. If you want to change either of these parameters, use DPSCreateContextWithTimeoutFromZone. Its two additional arguments let you specify the zone for the context to use when allocating context-specific data and a timeout value in milliseconds.

This function returns the newly created DPSContext structure.

Exceptions: DPSCreateContext raises a dps_err_outOfMemory exception if it encounters difficulty allocating ports or other resources for the new context. It raises a dps_err_cantConnect exception if it can't return a context within the timeout period.

See also: DPSCreateContextWithTimeoutFromZone, DPSCreateNonsecureContext, DPSCreateStreamContext


DPSCreateContextWithTimeoutFromZone

Summary: Create a PostScript execution context

Declared in: dpsclient/dpsNeXT.h

Synopsis: DPSContext DPSCreateContextWithTimeoutFromZone(const char *hostName, const char *serverName, DPSTextProc textProc, DPSErrorProc errorProc, int timeout, NSZone *zone)

Description: DPSCreateContextWithTimeoutFromZone is identical to DPSCreateContext except that it accepts two additional arguments that let you specify the zone to use when allocating context-specific data and a timeout value other than the default value of 60 seconds. Specify the new timeout value in milliseconds,

This function returns the newly created DPSContext structure.

Exceptions: DPSCreateContextWithTimeoutFromZone raises a dps_err_outOfMemory exception if it encounters difficulty allocating ports or other resources for the new context. It raises a dps_err_cantConnect exception if it can't return a context within the timeout period.

See also: DPSCreateContext, DPSCreateNonsecureContext, DPSCreateStreamContext


DPSCreateNonsecureContext

Summary: Create a PostScript execution context

Declared in: dpsclient/dpsNeXT.h

Synopsis: DPSContext DPSCreateNonsecureContext(const char *hostName, const char *serverName, DPSTextProc textProc, DPSErrorProc errorProc, int timeout, NSZone *zone)

Description: DPSCreateNonsecureContext creates a "nonsecure" context in which you can use PostScript operators that are normally disallowed. The most significant of these are operators that let you write files.

Few programmers will need to call this function directly: The Application Kit manages contexts for programs based on the Kit. For example, when an application is launched, its Application object calls DPSCreateContext to create a context in the Window Server. Similarly, to print a View the Kit calls DPSCreateStreamContext to temporarily redirect PostScript code from the View to a stream.

This function returns the newly created DPSContext structure.

See also: DPSCreateContext, DPSCreateContextWithTimeoutFromZone, DPSCreateStreamContext


DPSCreateStreamContext

Summary: Create a PostScript execution context

Declared in: dpsclient/dpsNeXT.h

Synopsis: DPSContext DPSCreateStreamContext(NXStream *stream, int debugging, DPSProgramEncoding progEnc, DPSNameEncoding nameEnc, DPSErrorProc errorProc)

Description: DPSCreateStreamContext is similar to DPSCreateContext, except that the new context is actually a connection from the client application to a stream. This connection becomes the current context. PostScript code that the application generates is sent to the stream rather than to the Window Server. The first argument, stream, is a pointer to an NXStream structure, as created by NXOpenFile or NXMapFile. The debugging argument is intended for debugging purposes but is not currently implemented. progEnc and nameEnc specify the type of program and user-name encodings to be used for output to the stream. The last argument, errorProc, identifies the procedure that's called when errors are generated.

Few programmers will need to call this function directly: The Application Kit manages contexts for programs based on the Kit. For example, when an application is launched, its Application object calls DPSCreateContext to create a context in the Window Server. Similarly, to print a View the Kit calls DPSCreateStreamContext to temporarily redirect PostScript code from the View to a stream.

This function returns the newly created DPSContext structure.

See also: DPSCreateContext, DPSCreateContextWithTimeoutFromZone, DPSCreateNonsecureContext


DPSDefineUserObject

Summary: Create a user object

Declared in: dpsclient/dpsNeXT.h

Synopsis: int DPSDefineUserObject(int index)

Description: DPSDefineUserObject associates index with the PostScript object that's on the top of the operand stack, thereby creating a user object (as defined by the PostScript language). If index is 0, the object is assigned the next available index number. The function returns the new index, which can then be passed to a pswrap-generated function that takes a user object.


Warning: To avoid coming into conflict with user objects defined by the Client Library or Application Kit, use DPSDefineUserObject rather than the PostScript operator defineuserobject or the single-operator functions DPSdefineuserobject and PSdefineuserobject.

Return: DPSDefineUserObject, if successful in assigning an index, returns the index that the object was assigned. If unsuccessful, it returns 0.

See also: DPSUndefineUserObject


DPSDiscardEvents

Summary: Discard events from the Window Server

Declared in: dpsclient/dpsNeXT.h

Synopsis: void DPSDiscardEvents(DPSContext context, int mask)

Description: DPSDiscardEvents's two parameters, context and mask, are the same as those for DPSGetEvent and DPSPeekEvent. DPSDiscardEvents removes from the application's event queue those records whose event types match mask and whose context matches context.

Return: DPSGetEvent and DPSPeekEvent return 1 if they are successful in accessing an event record and 0 if they aren't.

See also: DPSGetEvent, DPSPeekEvent, DPSAddFD, DPSAddPort, DPSAddTimedEntry, DPSPostEvent


DPSDoUserPath

Summary: Send an encoded PostScript path to the Window Server

Declared in: dpsclient/dpsNeXT.h

Synopsis: void DPSDoUserPath(void *coords, int numCoords, DPSNumberFormat numType, unsigned char *ops, int numOps, void *bbox, int action)

Description: DPSDoUserPath sends an encoded user path to the Window Server and then executes, upon that path, the operator specified by action. The use of this function, rather than the analogous step-by-step path construction, is encouraged; rendering an encoded path is much more efficient than executing the individual PostScript operators that would otherwise be needed.

An encoded user path consists of an array of coordinate values, a sequence of PostScript operators, and a bounding box specification. The values in the coordinate array are used as operands to the operators; the operands are distributed to the operators in the order that they're given. The resulting path must fit within the bounding box.

The coordinates, operators, and bounding box are given by the function's first five arguments:

The following integer constants represent the data types that you can pass as the numType argument:

Constant Meaning dps_float single-precision floating-point number
dps_long 32-bit integer
dps_short 8-bit integer

You can also specify 16- and 32-bit fixed-point real numbers. For 16-bit fixed-point numbers, use dps_short plus the number of bits in the fractional portion. For 32-bit fixed-point numbers, use dps_long plus the number of bits in the fractional portion.

These constants are provided for ops:

dps_setbbox
dps_moveto
dps_rmoveto
dps_lineto
dps_rlineto
dps_curveto
dps_rcurveto
dps_arc
dps_arcn
dps_arct
dps_closepath
dps_ucache

Once the user path has been constructed, the operator specified by action is executed. The value of action is an index into Display PostScript's encoded system names; the following constants, provided as a convenience, represent the most commonly used actions:

dps_uappend
dps_ufill
dps_ueofill
dps_ustroke
dps_ustrokepath
dps_inufill
dps_inueofill
dps_inustroke
dps_def
dps_put

The following program fragment demonstrates the use of DPSDoUserPath as it creates and strokes a user path (an isosceles triangle) within a bounding rectangle whose lower left corner is located at (0, 0) and whose width and height are 200.

short  coords[6] = {0, 0, 200, 0, 100, 200};
char ops[4] = {dps_moveto, dps_lineto,dps_lineto, dps_closepath};
short bbox[4] = {0, 0, 200, 200};

DPSDoUserPath(coords, 6, dps_short, ops, 4, bbox, dps_ustroke);

Note: If an application calls DPSDoUserPath with large values (~10,000-20,000) of numCoords and/or numOps, it may generate a Display PostScript error.

See also: DPSDoUserPathWithMatrix


DPSDoUserPathWithMatrix

Summary: Send an encoded PostScript path to the Window Server

Declared in: dpsclient/dpsNeXT.h

Synopsis: void DPSDoUserPathWithMatrix(void *coords, int numCoords, DPSNumberFormat numType, unsigned char *ops, int numOps, void *bbox, int action, float matrix[6])

Description: DPSDoUserPathWithMatrix sends an encoded user path to the Window Server and then executes, upon that path, the operator specified by action. The use of this function, rather than the analogous step-by-step path construction, is encouraged; rendering an encoded path is much more efficient than executing the individual PostScript operators that would otherwise be needed.

An encoded user path consists of an array of coordinate values, a sequence of PostScript operators, and a bounding box specification. The values in the coordinate array are used as operands to the operators; the operands are distributed to the operators in the order that they're given. The resulting path must fit within the bounding box.

The coordinates, operators, and bounding box are given by the function's first five arguments:

The following integer constants represent the data types that you can pass as the numType argument:

Constant Meaning dps_float single-precision floating-point number
dps_long 32-bit integer
dps_short 8-bit integer

You can also specify 16- and 32-bit fixed-point real numbers. For 16-bit fixed-point numbers, use dps_short plus the number of bits in the fractional portion. For 32-bit fixed-point numbers, use dps_long plus the number of bits in the fractional portion.

These constants are provided for ops:

dps_setbbox
dps_moveto
dps_rmoveto
dps_lineto
dps_rlineto
dps_curveto
dps_rcurveto
dps_arc
dps_arcn
dps_arct
dps_closepath
dps_ucache

Once the user path has been constructed, the operator specified by action is executed. The value of action is an index into Display PostScript's encoded system names; the following constants, provided as a convenience, represent the most commonly used actions:

dps_uappend
dps_ufill
dps_ueofill
dps_ustroke
dps_ustrokepath
dps_inufill
dps_inueofill
dps_inustroke
dps_def
dps_put

DPSDoUserPathWithMatrix's matrix argument represents the transformation matrix operand used by the ustroke, inustroke, and ustrokepath operators. If matrix is NULL, the argument is ignored.


DPSFlush

Summary: Send PostScript data to the Window Server

Declared in: dpsclient/dpsNeXT.h

Synopsis: void DPSFlush

Description: DPSFlush flushes the application's output buffer, forcing any buffered PostScript code or data to the Window Server.

See also: DPSSendEOF


DPSGetEvent

Summary: Access events from the Window Server

Declared in: dpsclient/dpsNeXT.h

Synopsis: int DPSGetEvent(DPSContext context, NXEvent *anEvent, int mask, double timeout, int threshold)

Description: DPSGetEvent and DPSPeekEvent are macros that access event records in an application's event queue. These routines are provided primarily for programs that don't use the Application Kit. An application based on the Kit should use the corresponding Application class methods (such as getNextEvent: and peekNextEvent:into:) so that it can be journaled. DPSDiscardEvents removes all event records of a specified type from the queue.

DPSGetEvent and DPSPeekEvent differ only in how they treat the accessed event record. DPSGetEvent removes the record from the queue after making its data available to the application; DPSPeekEvent leaves the record in the queue.

DPSGetEvent and DPSPeekEvent take the same parameters. The first, context, represents a PostScript execution context within the Window Server. Virtually all applications have only one execution context, which can be returned using DPSGetCurrentContext. Applications having more than one execution context can use the constant DPS_ALLCONTEXTS to access events from all contexts belonging to them.

The second argument, anEvent, is a pointer to an event record. If DPSGetEvent or DPSPeekEvent is successful in accessing an event record, the record's data is copied into the storage referred to by anEvent.

mask determines the types of events sought. See the section "Types and Constants" for a list of the constants that represent the event type masks. To check for more than one type of event, you combine individual constants using the bitwise OR operator.

If an event matching the event mask isn't available in the queue, DPSGetEvent or DPSPeekEvent waits until one arrives or until timeout seconds have elapsed, whichever occurs first. The value of timeout can be in the range of 0.0 to NX_FOREVER. If timeout is 0.0, the routine returns an event only if one is waiting in the queue when the routine asks for it. If timeout is NX_ FOREVER, the routine waits until an appropriate event arrives before returning.

The last argument, threshold, is an integer in the range 0 through 31 that determines which other services may be provided during a call to DPSGetEvent or DPSPeekEvent.

Requests for services are registered by the functions DPSAddTimedEntry, DPSAddPort, and DPSAddFD. Each of these functions takes an argument specifying a priority level. If this level is equal to or greater than threshold, the service is provided before DPSGetEvent or DPSPeekEvent returns.

Return: DPSGetEvent returns 1 if it is successful in accessing an event record and 0 if it isn't.

See also: DPSPeekEvent, DPSDiscardEvents, DPSAddFD, DPSAddPort, DPSAddTimedEntry, DPSPostEvent


DPSInterruptContext


Warning: This function is unimplemented in the NEXTSTEP version of the Client Library.


DPSNameFromTypeAndIndex

Summary: Access the system and user name tables

Declared in: dpsclient/dpsNeXT.h

Synopsis: const char *DPSNameFromTypeAndIndex(short type, int index)

Description: DPSNameFromTypeAndIndex returns the text associated with index from the system or user name table. If type is -1, the text is returned from the system name table; if type is 0, it's returned from the user name table.

The name tables are used primarily by the Client Library and pswrap; few programmers will access them directly.

Return: This function returns a read-only character string.


DPSPeekEvent

Summary: Access events from the Window Server

Declared in: dpsclient/dpsNeXT.h

Synopsis: int DPSPeekEvent(DPSContext context, NXEvent *anEvent, int mask, double timeout, int threshold)

Description: DPSGetEvent and DPSPeekEvent are macros that access event records in an application's event queue. These routines are provided primarily for programs that don't use the Application Kit. An application based on the Kit should use the corresponding Application class methods (such as getNextEvent: and peekNextEvent:into:) so that it can be journaled. DPSDiscardEvents removes all event records of a specified type from the queue.

DPSGetEvent and DPSPeekEvent differ only in how they treat the accessed event record. DPSGetEvent removes the record from the queue after making its data available to the application; DPSPeekEvent leaves the record in the queue.

DPSGetEvent and DPSPeekEvent take the same parameters. The first, context, represents a PostScript execution context within the Window Server. Virtually all applications have only one execution context, which can be returned using DPSGetCurrentContext. Applications having more than one execution context can use the constant DPS_ALLCONTEXTS to access events from all contexts belonging to them.

The second argument, anEvent, is a pointer to an event record. If DPSGetEvent or DPSPeekEvent is successful in accessing an event record, the record's data is copied into the storage referred to by anEvent.

mask determines the types of events sought. See the section "Types and Constants" for a list of the constants that represent the event type masks. To check for more than one type of event, you combine individual constants using the bitwise OR operator.

If an event matching the event mask isn't available in the queue, DPSGetEvent or DPSPeekEvent waits until one arrives or until timeout seconds have elapsed, whichever occurs first. The value of timeout can be in the range of 0.0 to NX_FOREVER. If timeout is 0.0, the routine returns an event only if one is waiting in the queue when the routine asks for it. If timeout is NX_ FOREVER, the routine waits until an appropriate event arrives before returning.

The last argument, threshold, is an integer in the range 0 through 31 that determines which other services may be provided during a call to DPSGetEvent or DPSPeekEvent.

Requests for services are registered by the functions DPSAddTimedEntry, DPSAddPort, and DPSAddFD. Each of these functions takes an argument specifying a priority level. If this level is equal to or greater than threshold, the service is provided before DPSGetEvent or DPSPeekEvent returns.

Return: DPSPeekEvent returns 1 if it is successful in accessing an event record and 0 if it isn't.

See also: DPSGetEvent, DPSDiscardEvents, DPSAddFD, DPSAddPort, DPSAddTimedEntry, DPSPostEvent


DPSPostEvent

Summary: Create an event

Declared in: dpsclient/dpsNeXT.h

Synopsis: int DPSPostEvent(NXEvent *anEvent, int atStart)

Description: DPSPostEvent lets you add an event record to your application's event queue without involving the Window Server. anEvent is a pointer to the event record to be added. atStart specifies where the new record will be placed in relation to any other records in the queue. If atStart is TRUE, the event is posted in front of all others and so will be the next one your application receives. If atStart is FALSE, the event is posted behind all others and so won't be returned until events that precede it are processed.

You can free, reuse, or otherwise mangle anEvent after you've posted it without fear of corrupting the posted record. DPSEvent copies the record it receives and posts the copy.

Note that event records you post using DPSPostEvent aren't filtered by an event filter function set with DPSSetEventFunc.

Return: DPSPostEvent returns 0 if successful in posting the event record; it returns -1 if unsuccessful in posting the record because the event queue is full.

See also: DPSSetEventFunc


DPSPrintError

Summary: Print error messages

Declared in: dpsclient/dpsNeXT.h

Synopsis: void DPSPrintError(FILE *fp, const DPSBinObjSeq error)

Description: DPSPrintError and DPSPrintErrorToStream format and print error messages received from a PostScript execution context in the Window Server. The error message is extracted from the binary object sequence error. DPSPrintError prints the error message to the file identified by fp; DPSPrintErrorToStream prints the error message to stream.

You rarely need to call this function directly. However, if you reset the error handler for a PostScript execution context, the new handler you install could use this function to process errors that it receives.

See also: DPSPrintErrorToStream


DPSPrintErrorToStream

Summary: Print error messages

Declared in: dpsclient/dpsNeXT.h

Synopsis: void DPSPrintErrorToStream(NXStream *stream, const DPSBinObjSeq error)

Description: DPSPrintError and DPSPrintErrorToStream format and print error messages received from a PostScript execution context in the Window Server. The error message is extracted from the binary object sequence error. DPSPrintError prints the error message to the file identified by fp; DPSPrintErrorToStream prints the error message to stream.

You rarely need to call this function directly. However, if you reset the error handler for a PostScript execution context, the new handler you install could use this function to process errors that it receives.

See also: DPSPrintError


DPSRemoveFD

Summary: Stop monitoring a file descriptor

Declared in: dpsclient/dpsNeXT.h

Synopsis: void DPSRemoveFD(int fd)

Description: DPSRemoveFD removes the specified file descriptor from the list of those that the application will check.

See also: DPSAddFD


DPSRemoveNotifyPortProc

Summary: Removes the handler function for the notify port

Declared in: dpsclient/dpsNeXT.h

Synopsis: void DPSRemoveNotifyPortProc(DPSPortProc handler)

Description: Removes the notify port's handler without specifying a new one. The handler argument must match the notify port's current handler.

See also: DPSAddNotifyPortProc


DPSRemovePort

Summary: Remove the Mach port being monitored.

Declared in: dpsclient/dpsNeXT.h

Synopsis: void DPSRemovePort(port_t port)

Description: DPSRemovePort removes the specified Mach port from the list of those that the application will check.

See also: DPSAddPort


DPSRemoveTimedEntry

Summary: Create a timed entry

Declared in: dpsclient/dpsNeXT.h

Synopsis: void DPSRemoveTimedEntry(DPSTimedEntry tag)

Description: DPSRemoveTimedEntry removes a previously registered timed entry.

See also: DPSAddTimedEntry


DPSResetContext


Warning: This function is unimplemented in the NEXTSTEP version of the Client Library.


DPSSendEOF

Summary: Send PostScript data to the Window Server

Declared in: dpsclient/dpsNeXT.h

Synopsis: void DPSSendEOF(DPSContext context)

Description: DPSSendEOF sends a PostScript end-of-file marker to the given context. The connection to the context isn't closed or disturbed in any way by this function.

See also: DPSFlush


DPSSetDeadKeysEnabled

Summary: Allow dead key processing for a context's events

Declared in: dpsclient/dpsNeXT.h

Synopsis: void DPSSetDeadKeysEnabled(DPSContext context, int flag)

Description: DPSSetDeadKeysEnabled turns dead key processing on or off for context. If flag is 0, dead key processing is turned off; otherwise, it's turned on (the default).

Dead key processing is a technique for extending the range of characters that can be entered from the keyboard. In NEXTSTEP, it provides one way for users to enter accented characters. For example, a user can type Alternate-e followed by the letter "e" to produce the letter "é". The first keyboard input, Alternate-e, seems to have no effect-it's the "dead key". However, it signals Client Library routines that it and the following character should be analyzed as a pair. If, within NEXTSTEP, the pair of characters has been associated with a third character, a keyboard event record representing the third character is placed in the application's event queue, and the first two event records are discarded. If there is no such association between the two characters, the two event records are added to the event queue.


DPSSetEventFunc

Summary: Set the function that filters events

Declared in: dpsclient/dpsNeXT.h

Synopsis: DPSEventFilterFunc DPSSetEventFunc(DPSContext context, DPSEventFilterFunc func)

Description: DPSSetEventFunc establishes the function func as the function to be called when an event record is returned from the PostScript context context in the Window Server. The registered function is called before the event record is put in the event queue. If the registered function returns 0, the record is discarded. If the registered function returns 1, the record is passed on for further processing.

Only event records coming from the Window Server are filtered by the registered function. Records that you post to the event queue using DPSPostEvent aren't affected.

A DPSEventFilterFunc function takes the following form:

int *func(NXEvent *anEvent)

Return: DPSSetEventFunc returns a pointer to the previously registered event function. This lets you chain together the current and previous event functions.

See also: DPSPostEvent


DPSSetTracking

Summary: Coalesce mouse events

Declared in: dpsclient/dpsNeXT.h

Synopsis: int DPSSetTracking(int flag)

Description: DPSSetTracking turns mouse event-coalescing on or off for the current context. If flag is 0, coalescing is turned off; otherwise, it's turned on (the default).

Event coalescing is an optimization that's useful when tracking the mouse. When the mouse is moved, numerous events flow into the event queue. To reduce the number of events awaiting removal by the application, adjacent mouse-moved events are replaced by the most recent event of the contiguous group. The same is done for left and right mouse-dragged events, with the addition that a mouse-up event replaces mouse-dragged events that come before it in the queue.

Return: DPSSetTracking returns the previous state of the event-coalescing switch.


DPSStartWaitCursorTimer

Summary: Initiate a count down for the wait cursor

Declared in: dpsclient/dpsNeXT.h

Synopsis: void DPSStartWaitCursorTimer

Description: DPSStartWaitCursorTimer triggers the mechanism that displays a wait cursor when an application is busy and can't respond to user input. In most cases, wait cursor support is automatic: You'll only need to call this function if your application starts a time-consuming operation that's not initiated by a user-generated event.

Client Library routines and the Window Server cooperate to display the wait cursor whenever more than a preset amount of time elapses between the time an application takes an event record from the event queue and the time the application is again ready to consume events. However, when an application starts an operation that isn't initiated by an event-such as one caused by receiving a Mach message or by processing data from a file (see DPSAddPort and DPSAddFD)-the wait cursor mechanism is bypassed. To ensure proper wait cursor behavior in these cases, call DPSStartWaitCursorTimer before beginning the time-consuming operation.

See also: DPSAddFD, DPSAddPort


DPSSynchronizeContext

Summary: Synchronize a context with your application

Declared in: dpsclient/dpsNeXT.h

Synopsis: int DPSSynchronizeContext(DPSContext context, int flag)

Description: DPSSynchronizeContext causes DPSWaitContext to be called after each pswrap function is called, thus synchronizing the PostScript context with your application.


DPSTraceContext

Summary: Trace data and events

Declared in: dpsclient/dpsNeXT.h

Synopsis: int DPSTraceContext(DPSContext context, int flag)

Description: DPSTraceContext controls the tracing of data between a PostScript execution context (or contexts) in the Window Server and an application process.

The first argument, context, specifies the context to be traced. An application's single context can be returned with DPSGetCurrentContext. Applications having more than one execution context can use the constant DPS_ALLCONTEXTS to trace all contexts belonging to them.

The second argument, flag, determines whether tracing is enabled. When data tracing is enabled, a copy of the PostScript code generated by an application and the values returned to it by the Window Server is sent to standard error. Values returned to the application are marked by the prepended string:

% value returned ==>

For applications based on the Application Kit, there are two preferable methods for turning on data tracing: You can use the NXShowPS command-line switch when you launch an application from Terminal. Alternatively, when you run the application under GDB, you can use the showps and shownops commands to control tracing output.

Only one tracing context can be created for the supplied context. If you attempt to create additional tracing contexts for a context that's already being traced, no new context is created and DPSTraceContext returns -1.

Return: DPSTraceContext returns 0 if successful in creating a tracing context, or -1 if not.

See also: DPSTraceEvents


DPSTraceEvents

Summary: Trace data and events

Declared in: dpsclient/dpsNeXT.h

Synopsis: void DPSTraceEvents(DPSContext context, int flag)

Description: DPSTraceEvents controls the tracing of events between a PostScript execution context (or contexts) in the Window Server and an application process.

The first argument, context, specifies the context to be traced. An application's single context can be returned with DPSGetCurrentContext. Applications having more than one execution context can use the constant DPS_ALLCONTEXTS to trace all contexts belonging to them.

The second argument, flag, determines whether tracing is enabled. When event tracing is enabled, information about each event that the application receives is sent to standard error. For example, for a left mouse-down event the listing might look like this:

Receiving: LMouseDown at: 343.0,69.0 time: 1271899 
flags: 0x0 win: 6 ctxt: 76128 data: 1111,1

The listing displays the fields of the event record: type, location, time, flags, local window number, PostScript execution context, and data. The contents of the data field listing depends on the event type; for instance, in the preceding example the event number and the click count were displayed.

To enable event tracing, you can use the NXTraceEvents command-line switch when you launch an application from Terminal. Alternatively, when you run the application under GDB, you can use the traceevents and tracenoevents commands to control event-tracing output.

See also: DPSTraceContext


DPSUndefineUserObject

Summary: Remove a user object

Declared in: dpsclient/dpsNeXT.h

Synopsis: void DPSUndefineUserObject(int index)

Description: DPSUndefineUserObject removes the association between index and the PostScript object it refers to, thus destroying the user object. By destroying a user object that's no longer needed, you can let the garbage collector reclaim the previously associated PostScript object.

See also: DPSDefineUserObject


NX_EVENTCODEMASK

Summary: Generate an event mask for an event type

Declared in: dpsclient/event.h

Synopsis: int NX_EVENTCODEMASK(int type)

Description: This handy utility macro returns an event mask that corresponds to the given (single) event type.



Table of Contents

Copyright © 1998, Apple Computer, Inc. All rights reserved.