Return to ch01a.t CVS log

Up to [CSRG BSD Unix] / 43BSD / contrib / X / doc / Xlib

Annotation of 43BSD/contrib/X/doc/Xlib/ch01a.t, revision 1.1

1.1     ! root        1: .NH
        !             2: Introduction
        !             3: .XS ii
        !             4: Table of Contents
        !             5: .XE
        !             6: .XS
        !             7: Introduction
        !             8: .XE
        !             9: .PP
        !            10: The X window system supports overlapping (sub)windows.
        !            11: All the windows in an X server are arranged in a strict hierarchy.  At
        !            12: the top of the hierarchy is the `root' window,
        !            13: which covers the entire display screen.
        !            14: The root window is partially or completely covered by child windows.
        !            15: All windows have parents except for the root window.
        !            16: There is usually at least one window per application program.
        !            17: .IN "Definitions" "Child Window"
        !            18: .IN "Definitions" "Parent Window"
        !            19: Child windows  may in turn have
        !            20: their own children.
        !            21: In this way, an application program can create a tree of arbitrary depth.
        !            22: .PP
        !            23: A child window may be larger than its parent--that is, part or all of
        !            24: the child window may extend beyond the boundaries of the parent.
        !            25: However, all output to a window is clipped by the boundaries of its
        !            26: parent window.
        !            27: .PP
        !            28: .IN "Definitions" "Stacking order"
        !            29: If several children of a window have overlapping locations, then one of
        !            30: the children is considered to be `on top of' or `raised over' the
        !            31: others, obscuring them.
        !            32: Output to areas covered by other windows will be suppressed by the window
        !            33: system.
        !            34: If a window  is obscured
        !            35: by a second window, 
        !            36: then the window will obscure only those ancestors of the second window which
        !            37: are also ancestors of the window.
        !            38: Normally, child windows obscure their parents
        !            39: as well (but there are exceptions--see the discussions of
        !            40: .IN "XOpenTransparency"
        !            41: .IN "XClipMode"
        !            42: \fIXOpenTransparency\fP and \fIXClipMode\fP for details).
        !            43: .PP
        !            44: .IN "Definitions" "Events"
        !            45: .IN "Events"
        !            46: Input from X takes the form of `events'.
        !            47: Events may either be side effects of a command (restacking windows,
        !            48: for example, generates exposure events),
        !            49: or completely asynchronous (for example, the keyboard).
        !            50: A client program asks to be informed of such events;
        !            51: X never sends events a program did not ask for.
        !            52: .PP
        !            53: X does not take responsibility for the contents of windows; when (part or
        !            54: all of) a window is hidden and then brought back onto the screen, its
        !            55: contents may be lost lost and the client program is notified (by an exposure
        !            56: event) that (part or all
        !            57: of) the window needs to be repainted.
        !            58: Programs should be prepared to regenerate their windows on demand.
        !            59: .PP
        !            60: .IN "Definitions" "Resource ID"
        !            61: Most of the subroutines in Xlib just add requests to an output buffer;
        !            62: these requests later execute asynchronously on the X server
        !            63: (often referred to as ``display server'' below).
        !            64: Subroutines that return values do not return (``block'')
        !            65: until an explicit reply is
        !            66: received or an error occurs.
        !            67: This may be queried information or a ``resource id'' discussed below.
        !            68: If such a call results in an error, the error will
        !            69: generally not be reported (by a call to an optional error handler)
        !            70: until some later, blocking call is made.
        !            71: .PP
        !            72: .IN "XSync"
        !            73: If a
        !            74: client does not want a request to execute asynchronously, he can follow
        !            75: it with a call to \fIXSync\fP, which will block until all previously buffered
        !            76: asynchronous events have been sent and acted on.
        !            77: .PP
        !            78: As an important side effect, 
        !            79: .IN "XPending"
        !            80: .IN "XNextEvent"
        !            81: .IN "XWindowEvent"
        !            82: .IN "XFlush"
        !            83: .IN "XSync"
        !            84: the output buffer is always flushed by a call to any subroutine
        !            85: which returns a value or by calls to \fIXPending\fP,
        !            86: \fIXNextEvent\fP, \fIXWindowEvent\fP,
        !            87: \fIXFlush\fP or \fIXSync\fP.
        !            88: .PP
        !            89: .IN "Resource ID" "Window"
        !            90: .IN "Resource ID" "Font"
        !            91: .IN "Resource ID" "Pixmap"
        !            92: .IN "Resource ID" "Bitmap"
        !            93: .IN "Resource ID" "Cursor"
        !            94: Many subroutines will return an integer resource id.
        !            95: These can be of type ``Window'', ``Font'', ``Pixmap'', ``Bitmap'',
        !            96: and ``Cursor'',
        !            97: .IN "File" "<X/X.h>"
        !            98: as defined in \fI<X/X.h>\fP.
        !            99: Some subroutines return ``Status'', an integer error indication.
        !           100: If the subroutine fails, it will return 0.
        !           101: .PP
        !           102: .IN "Definitions" "Status"
        !           103: Since C does not provide multiple return values, many subroutines return
        !           104: their results by writing into client-passed storage.  Any pointer that is
        !           105: used to return a value is designated as ``/* RETURN */'' in the procedure
        !           106: declarations below.
        !           107: All other pointers passed to these subroutines are
        !           108: used for reading only.
        !           109: If such a procedure returns a status of 0,
        !           110: then it has NOT updated the return parameters.
        !           111: .IN "Error Handling"
        !           112: By default, errors are handled by a standard library subroutine,
        !           113: or you can provide your own.
        !           114: Subroutines that return pointers to strings will return NULL pointers if
        !           115: the string does not exist.
        !           116: .PP
        !           117: .PP
        !           118: Input events (e.g. key pressed, mouse moved) arrive asynchronously from
        !           119: the server and are queued until they are requested by a call to
        !           120: \fIXNextEvent\fP or \fIXWindowEvent\fP.  In addition, some of the library
        !           121: .IN "XChangeWindow"
        !           122: .IN "XRaiseWindow"
        !           123: subroutines (e.g. \fIXChangeWindow\fP and \fIXRaiseWindow\fP)
        !           124: generate ``exposure''
        !           125: events--requests to repaint sections of a window that do not have valid
        !           126: contents.  These events also arrive asynchronously, but the client may
        !           127: .IN "XSync"
        !           128: wish to explicitly wait for them by calling \fIXSync\fP after calling a
        !           129: subroutine which may generate exposure events.

This archive runs on limited infrastructure. Preserving old code on modern bandwidth. Automated agents are requested to crawl responsibly.