Error Codes

Calls to the graphics libraries may produce errors. Most errors that occur are due to specifying a window or graphics context which does not exist, or attempting an operation which is illegal. Many things are allowed even if pointless, such as drawing outside of the window boundaries, or while a window is not mapped. The things which return errors are those which definitely indicate a program bug, attempts to exceed the system limits, or a fatal device error.

In order to be as efficient as possible, error codes are not returned by individual function calls. Instead, if a function fails, an error event is generated which will eventually be noticed by the program at a possibly much later time. This allows many drawing requests to be sent at one time without having to worry about the status of each one.

Error events are detected when the program checks for events, such as by calling GrGetNextEvent. At this point, if an error had occurred, a special error handler routine is called to notice the error. If the program had not set up its own error handler, a default one is called which will disconnect from the server, print out an indication of the error, and exit the program.

The following is a list of the possible errors:

GR_ERROR_BAD_WINDOW_ID		the specified window id is unknown
GR_ERROR_BAD_GC_ID		the specified graphics context id is unknown
GR_ERROR_BAD_CURSOR_SIZE	the specified cursor is too large
GR_ERROR_MALLOC_FAILED		no more memory is available in the server
GR_ERROR_BAD_WINDOW_SIZE	the specified window size is illegal
GR_ERROR_KEYBOARD_ERROR		an error occurred reading from the keyboard
GR_ERROR_MOUSE_ERROR		an error occurred reading from the mouse
GR_ERROR_INPUT_ONLY_WINDOW	drawing was attempted in an input-only window
GR_ERROR_ILLEGAL_ON_ROOT_WINDOW	an illegal operation was attempted on the root
GR_ERROR_TOO_MUCH_CLIPPING	complexity of windows exceeded clipping limits
GR_ERROR_SCREEN_ERROR		an error occurred talking to the screen driver
GR_ERROR_UNMAPPED_FOCUS_WINDOW	attempted to set focus to an unmapped window
GR_ERROR_BAD_DRAWING_MODE	illegal drawing mode specified for a GC