Return to ch04a.t CVS log

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

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

1.1     ! root        1: .NH
        !             2: Opening and Closing the Display
        !             3: .XS
        !             4: Initializing the Window System
        !             5: .XE
        !             6: .PP
        !             7: The window system is a network service.
        !             8: You must connect to the X server before you can perform any operations.
        !             9: There is one X server for each hardware display.
        !            10: This library interface presumes you are working with a single display at
        !            11: one time, and
        !            12: therefore has an idea of the current display you are using.
        !            13: .FD
        !            14: .IN "Definitions" "XOpenDisplay"
        !            15: .IN "XOpenDisplay"
        !            16: Display *XOpenDisplay (name)
        !            17:        char *name;
        !            18: .FN    
        !            19: This function takes the \fIname\fP of the server, and opens a connection to the
        !            20: server for the display hardware.
        !            21: .IN "DISPLAY Environment Variable"
        !            22: .IN "Environment" "DISPLAY"
        !            23: If the display name string is NULL, it uses the environment variable DISPLAY
        !            24: to determine which display and which communications domain to use.
        !            25: The
        !            26: display string or DISPLAY environment variable should be in the format
        !            27: ``hostname:number'', where ``hostname'' is the name of a machine, and
        !            28: ``number'' is the number of the display on that machine.
        !            29:  For example, ``mit-athena:3'' would be display 3 on the machine
        !            30: ``mit-athena''.
        !            31: .IN "Protocol" "TCP"
        !            32: .IN "Protocol" "DECnet"
        !            33: XOpenDisplay connects through TCP, Unix or DECnet streams to the server.
        !            34: If the ``hostname'' is ``unix'', Unix domain IPC is used.
        !            35: If there is only a single ``:'' between hostname and display number,
        !            36: TCP streams are used.
        !            37: If hostname and display number are seperated by a ``::'', DECnet streams
        !            38: will be used.
        !            39: Note that you must build all software for DECnet if you want to use DECnet.
        !            40: A single X server will accept both TCP and DECnet connections if it has been
        !            41: built for DECnet.
        !            42: .PP
        !            43: .IN "Definitions" "Display"
        !            44: .IN "Data Structures" "Display"
        !            45: If the call is successful, it returns a pointer to a  Display structure,
        !            46: .IN "File" "<X/Xlib.h>"
        !            47: which is defined in \fI<X/Xlib.h>\fP.
        !            48: .PP
        !            49: The procedure returns NULL on failure.
        !            50: .PP
        !            51: There are a number of useful macros and functions
        !            52: which return information out of the
        !            53: Display structure.
        !            54: .IN "Unix System Call" "select"
        !            55: Some programs may find it useful to perform select(2) on the file descriptor
        !            56: .IN "Macro" "dpyno()"
        !            57: returned using the \fIdpyno()\fP macro,
        !            58: which returns the file descriptor of the connection.
        !            59: This comes up most often in applications which drive more than one
        !            60: display at a time.
        !            61: The length of the input queue on the display connection is
        !            62: .IN "Macro" "QLength()"
        !            63: returned using the \fIQLength()\fP macro.
        !            64: This may be useful to make sure you have processed all events
        !            65: already read in before performing a select again.
        !            66: .IN "Macro" "DisplayType()"
        !            67: .IN "Macro" "DisplayPlanes()"
        !            68: .IN "Macro" "DisplayCells()"
        !            69: The \fIDisplayType()\fP, \fIDisplayPlanes()\fP, \fIDisplayCells()\fP and
        !            70: .IN "Macro" "ProtocolVersion()"
        !            71: \fIProtocolVersion()\fP macros
        !            72: return the appropriate information out of the current display structure.
        !            73: .IN "Window" "RootWindow"
        !            74: .IN "RootWindow"
        !            75: .IN "Macro" "RootWindow"
        !            76: .PP
        !            77: The \fIRootWindow\fP variable (actually a reference to the current display
        !            78: structure) is often useful in other calls, as many subroutines take a
        !            79: parent window as an argument.
        !            80: .PP
        !            81: .IN "Macro" "DisplayType()"
        !            82: There may be different performance tradeoffs a client program
        !            83: may wish to make depending on the display type.
        !            84: The \fIDisplayType()\fP macro returns the type of the device, as
        !            85: .IN "File" "<X/X.h>"
        !            86: defined in <X/X.h>.
        !            87: Its use is discouraged; programs should be prepared to work on different
        !            88: displays of various sizes and characteristics.
        !            89: .PP
        !            90: .IN "Macro" "DisplayName()"
        !            91: The \fIDisplayName()\fP macro returns the string that was passed to 
        !            92: \fIXOpenDisplay\fP
        !            93: when the current display was opened (or, if that was NULL, the value of
        !            94: the DISPLAY environment variable when the current display was opened).
        !            95: .IN "Unix System Call" "fork"
        !            96: This is especially useful to applications which \fIfork()\fP, and want to open
        !            97: a new connection to the same display from the child process.
        !            98: .PP
        !            99: .IN "BlackPixmap"
        !           100: .IN "WhitePixmap"
        !           101: .IN "Pixmap"
        !           102: .IN "Macro" "BlackPixmap"
        !           103: .IN "Macro" "WhitePixmap"
        !           104: \fIXOpenDisplay\fP
        !           105: automatically creates a solid black and a solid white pixmap,
        !           106: suitable for use as a background or border tile.
        !           107: You can refer to these
        !           108: by using the \fIBlackPixmap\fP and \fIWhitePixmap\fP macros,
        !           109: which refer to the
        !           110: current display structure.
        !           111: .PP
        !           112: .IN "DisplayWidth"
        !           113: .IN "DisplayHeight"
        !           114: .IN "Definitions" "DisplayWidth"
        !           115: .IN "Definitions" "DisplayHeight"
        !           116: The size of the current display's root window can be determined with the
        !           117: \fIDisplayWidth()\fP and \fIDisplayHeight()\fP functions,
        !           118: which return integers describing the size of the screen in pixels.
        !           119: .PP
        !           120: .IN "Data Structures" "Display"
        !           121: Other elements of the \fIDisplay\fP structure are private to
        !           122: the X library and must not be used.
        !           123: .FD
        !           124: .IN "XSetDisplay"
        !           125: .IN "Definitions" "XSetDisplay"
        !           126: XSetDisplay(display)
        !           127:        Display *display;
        !           128: .FN
        !           129: .PP
        !           130: This procedure sets the current \fIdisplay\fP
        !           131: connection which you are talking to.
        !           132: It is used to switch between displays.
        !           133: .FD
        !           134: .IN "XCloseDisplay"
        !           135: .IN "Definitions" "XCloseDisplay"
        !           136: XCloseDisplay (display)
        !           137:        Display *display;
        !           138: .FN
        !           139: .LP
        !           140: \fIXCloseDisplay\fP closes the connection associated with the specified
        !           141: \fIdisplay\fP.
        !           142: All windows or other resources that the caller has created on this display
        !           143: server are destroyed; they should never be referenced again.
        !           144: Any output events
        !           145: that have been buffered but not yet sent are discarded.
        !           146: .PP
        !           147: The effect of \fIXCloseDisplay\fP is automatically achieved if a process exits.
        !           148: For this reason, most clients
        !           149: will not need to call \fIXCloseDisplay\fP.
        !           150: .PP
        !           151: .IN "Resource ID"
        !           152: If a client has created Window, Font, Bitmap, Pixmap, or Cursor
        !           153: resource ID's with this display server, they must not be used after calling
        !           154: .IN "XCloseDisplay"
        !           155: XCloseDisplay.
        !           156: .PP
        !           157: .IN "Unix System Call" "fork"
        !           158: A special note on \fIfork()\fP:  if a program has a connection to a display
        !           159: server open and then
        !           160: calls \fIfork()\fP you must take typical 
        !           161: UNIX care when dealing with the
        !           162: connection to the window system.
        !           163: Do not forget to flush the output buffer before waiting on the child
        !           164: process, and do not forget to make sure that you have processed all input
        !           165: events before forking or exiting in the child, or your programs
        !           166: may perform the operations twice.

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