Return to ch05a.t CVS log

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

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

1.1     ! root        1: .NH
        !             2: Creating and Destroying Windows
        !             3: .XS
        !             4: Window Related Operations
        !             5: .XE
        !             6: .PP
        !             7: .IN "Definitions" "Opaque Window"
        !             8: .IN "Definitions" "Transparent Window"
        !             9: There are two kinds of windows, opaque and transparent.  
        !            10: If an opaque
        !            11: window is stacked `on top of' another window, it obscures that other
        !            12: window for the purpose of both input and output.
        !            13: Attempts to output to
        !            14: the obscured area will do nothing, and no input events (e.g. mouse
        !            15: motion) will be generated for the obscured area.
        !            16: Most windows are opaque.
        !            17: Opaque windows have borders of a programmable width and pattern
        !            18: and a background pattern (or `tile').
        !            19: .IN "Tile Pixmaps"
        !            20: Tile and border patterns are described using Pixmaps.
        !            21: In a program, you refer to the window using its resource id,
        !            22: of type `Window'.
        !            23: .PP
        !            24: .IN "Resource ID's" "Freeing"
        !            25: .IN "Freeing" "Resources"
        !            26: The background and border pixmaps may be destroyed immediately after
        !            27: creating the window if no further explicit references to them
        !            28: are to be made.
        !            29: .PP
        !            30: .IN "Definitions" "Tile Mode"
        !            31: An opaque window's background is tiled with a pattern (most commonly a constant
        !            32: color).
        !            33: This pattern can either be relative to the parent (the pattern will be
        !            34: shifted appropriately to match the parent window) or absolute
        !            35: (the pattern will be positioned in the window independently of the
        !            36: parent window).
        !            37: This is called the `tile mode' of a window,
        !            38: and can be set by subroutine calls.
        !            39: .PP
        !            40: .IN "Definitions" "Clip Mode"
        !            41: It is also possible to specify if graphics operations will be clipped by
        !            42: child windows or will write through the children.
        !            43: This is called the `clip mode' of a window.
        !            44: .PP
        !            45: .IN "Input" "Transparent Window"
        !            46: A transparent window obscures other windows for the purpose of input
        !            47: only.
        !            48: .IN "Parent Window"
        !            49: .IN "Output" "On Transparent Windows"
        !            50: Doing output to a transparent window is equivalent to output to
        !            51: the parent window, except that the transparent window's own clip mode is
        !            52: .IN "XClipMode"
        !            53: used instead of the parent's (see \fIXClipMode\fP below), and the output is
        !            54: clipped to the boundaries of the transparent window.
        !            55: If a transparent window is moved, it has no effect on the display.
        !            56: Transparent windows do not have borders.
        !            57: .PP
        !            58: .IN "Window" "RootWindow"
        !            59: .IN "RootWindow"
        !            60: .IN "Macro" "RootWindow"
        !            61: The macro \fIRootWindow\fP is a convenient shorthand for referring to the
        !            62: root of the window hierarchy, and is usually used as the \fIparent\fPn
        !            63: argument to most calls.
        !            64: .PP
        !            65: When windows are first created, they are not visible on the screen.
        !            66: Any output to a window not visible (not `mapped') on the screen
        !            67: will be discarded.
        !            68: An application may wish to create a window long before it is
        !            69: mapped to the screen.
        !            70: When an opaque window is eventually mapped to the screen 
        !            71: (using \fIXMapWindow\fP)
        !            72: .IN "Window" "Mapping to screen"
        !            73: .IN "XMapWindow"
        !            74: it will generate an exposure event for the window.
        !            75: .IN "Exposure Event"
        !            76: .FD
        !            77: .IN "Definitions" "XCreateWindow"
        !            78: .IN "XCreateWindow"
        !            79: Window XCreateWindow (parent, x, y, width, height, borderwidth, border, bgnd)
        !            80:        Window parent;
        !            81:        int x, y, width, height;
        !            82:        int borderwidth;        /* border width */
        !            83:        Pixmap border;
        !            84:        Pixmap background;
        !            85: .FN
        !            86: \fIXCreateWindow\fP creates an unmapped,
        !            87: opaque subwindow of the specified parent window,
        !            88: which must also be opaque.
        !            89: The created window will always be wholly
        !            90: contained within its \fIparent\fP,
        !            91: any part of the window extending outside its parent window will be clipped.
        !            92: .PP
        !            93: The \fIx\fP and \fIy\fP
        !            94: coordinates represent the top left outside corner of the new window's
        !            95: borders.
        !            96: They are relative to the inside of the \fIparent\fP window's
        !            97: borders.
        !            98: The \fIwidth\fP and \fIheight\fP parameters are the new window's inside
        !            99: dimensions--they do not include the new window's borders,
        !           100: which are entirely outside of the window.
        !           101: The new window will have a border \fIborderwidth\fP pixels wide.
        !           102: .PP
        !           103: .IN "Window" "Border"
        !           104: .IN "Window" "Background"
        !           105: .IN "Macro" "BlackPixmap"
        !           106: .IN "Macro" "WhitePixmap"
        !           107: .IN "BlackPixmap"
        !           108: .IN "WhitePixmap"
        !           109: A \fIborder\fP Pixmap need not be given if the border width is zero,
        !           110: in which case the window will not have a border.
        !           111: If no \fIbackground\fP Pixmap is given, the parent's background Pixmap is
        !           112: used.  A monochrome application may find the macros \fIBlackPixmap\fP and
        !           113: \fIWhitePixmap\fP useful; these refer to solid black and white pixmaps that
        !           114: are automatically created by \fIXOpenDisplay\fP.
        !           115: .PP
        !           116: .IN "Window" "Tile Mode"
        !           117: The \fItilemode\fP of the new window is absolute.
        !           118: .IN "Window" "Clip Mode"
        !           119: The \fIclipmode\fP of the new window is `clipped'.
        !           120: .IN "Icon" "Creating Windows"
        !           121: The new window does not have an associated icon window.
        !           122: .IN "Window" "Name"
        !           123: The \fIname\fP of the window is the null string.
        !           124: .PP
        !           125: The created window is not yet displayed (`mapped') on the user's display;
        !           126: to display the
        !           127: .IN "XMapWindow"
        !           128: window, call \fIXMapWindow\fP.
        !           129: .IN "Cursor" "Initial State"
        !           130: The new window will not have a cursor defined; the cursor will
        !           131: be that of the window's parent until/unless a cursor is registered.
        !           132: The window will not be visible on the screen unless it and all of its
        !           133: ancestors are `mapped', and it is not obscured by any of its ancestors.
        !           134: .IN "XDefineCursor"
        !           135: .PP
        !           136: The subroutine returns the window id of the created window, or 0 if
        !           137: the subroutine fails.
        !           138: .FD
        !           139: .IN "Definitions" "XCreateTransparency"
        !           140: .IN "XCreateTransparency"
        !           141: Window XCreateTransparency (parent, x, y, width, height)
        !           142:        Window parent;
        !           143:        int x, y, width, height;
        !           144: .FN
        !           145: \fIXCreateTransparency\fP creates an unmapped  transparent
        !           146: window.
        !           147: Transparent windows do not have borders.
        !           148: The coordinates are relative to the parents coordinate system.
        !           149: .IN "Transparent Window" "Clip Mode"
        !           150: .IN "Transparent Window" "Initial Cursor"
        !           151: The
        !           152: window will not initially have a cursor registered, and will have a
        !           153: clipmode of \fIClipModeClipped\fP
        !           154: (i.e. output to the window is obscured by subwindows of
        !           155: the parent).
        !           156: .IN "Transparent Window" "Background"
        !           157: .IN "Transparent Window" "Border"
        !           158: .IN "Transparent Window" "Tile Mode"
        !           159: A transparent window does not have a border or background pattern.
        !           160: It initially has a tile mode of \fITileModeRelative\fP.
        !           161: .PP
        !           162: The subroutine returns the window id of the created window, or 0 if
        !           163: the subroutine fails.
        !           164: .FD
        !           165: .IN "Definitions" "XDestroyWindow"
        !           166: .IN "XDestroyWindow"
        !           167: XDestroyWindow (w)
        !           168:        Window w;
        !           169: .FN
        !           170: \fIXDestroyWindow\fP unmaps and destroys the window and all of its subwindows.
        !           171: The windows should never again be referenced.
        !           172: \fIXDestroyWindow\fP may be
        !           173: called on either opaque or transparent windows.
        !           174: .PP
        !           175: .IN "Icon" "Mapping Behavior"
        !           176: If the window has an icon window, that icon window is automatically unmapped
        !           177: and sent an unmap window event.
        !           178: If the window is a mapped icon window,
        !           179: its corresponding `regular' window is automatically mapped.
        !           180: This prevents windows being lost when a window manager exits unexpectedly.
        !           181: .PP
        !           182: Destroying a mapped opaque window will generate exposure events on other
        !           183: opaque windows that were obscured by the window being destroyed.
        !           184: .PP
        !           185: .IN "XCloseDisplay"
        !           186: \fIXCloseDisplay\fP automatically destroys all windows that have been created
        !           187: .IN "Unix System Call" "fork"
        !           188: on that server  (unless called after a \fIfork()\fP--see note under 
        !           189: \fIXCloseDisplay\fP).
        !           190: .FD
        !           191: .IN "Definitions" "XDestroySubwindows"
        !           192: .IN "XDestroySubwindows"
        !           193: XDestroySubwindows (w)
        !           194:        Window w;
        !           195: .FN
        !           196: .IN "XDestroySubwindows"
        !           197: \fIXDestroySubwindows\fP destroys all subwindows of this window.  The
        !           198: subwindows should never again be referenced.  
        !           199: .PP
        !           200: \fIXDestroySubwindows\fP generates exposure events on \fIw\fP, if any mapped
        !           201: opaque subwindows were actually destroyed.
        !           202: .PP
        !           203: Note that this is MUCH more efficient than deleting many windows
        !           204: one at a time, as much of the work need only be performed once for all
        !           205: of the windows rather than for each window.
        !           206: .PP
        !           207: To allow efficient creation of many similar windows or subwindows
        !           208: simultaneously
        !           209: (a function often wanted when creating menus or complex forms),
        !           210: .IN "XCreateWindow"
        !           211: .IN "XCreateTransparency"
        !           212: .IN "XCreateWindowBatch"
        !           213: both \fIXCreateWindow\fP and \fIXCreateTransparency\fP have analogous forms
        !           214: which take structures of the form:
        !           215: .DS
        !           216: .TA .5i 3i
        !           217: .ta .5i 3i
        !           218: typedef struct _OpaqueFrame {
        !           219:        Window self;    /* window id of the window, filled in later */
        !           220:        short x, y;     /* where to create the window */
        !           221:        short width, height;    /* window size */
        !           222:        short bdrwidth; /* border width */
        !           223:        Pixmap border;  /* border pixmap */
        !           224:        Pixmap background;      
        !           225: } OpaqueFrame;
        !           226: .DE
        !           227: .IN "Definitions" "OpaqueFrame"
        !           228: .IN "Data Structures" "OpaqueFrame"
        !           229: .IN "OpaqueFrame"
        !           230: .DS
        !           231: .TA .5i 3i
        !           232: .ta .5i 3i
        !           233: typedef struct _TransparentFrame {
        !           234:        Window self;    /* window id of the window, filled in later */
        !           235:        short x, y;     /* where to create the window */
        !           236:        short width, height;    
        !           237: } TransparentFrame;
        !           238: .DE
        !           239: .IN "Definitions" "BatchFrame"
        !           240: .IN "Data Structures" "BatchFrame"
        !           241: .IN "BatchFrame"
        !           242: .DS
        !           243: .TA .5i 3i
        !           244: .ta .5i 3i
        !           245: typedef struct _BatchFrame {
        !           246:        short type;     /* One of (IsOpaque, IsTransparent). */
        !           247:        Window parent;  /* Window if of the window's parent. */
        !           248:        Window self;    /* Window id of the window, filled in later. */
        !           249:        short x, y;     /* Where to create the window. */
        !           250:        short width, height;    /* Window width and height. */
        !           251:        short bdrwidth; /* Window border width. */
        !           252:        Pixmap border;  /* Window border pixmap */
        !           253:        Pixmap background;      /* Window background pixmap. */
        !           254: } BatchFrame;
        !           255: .DE
        !           256: .fi
        !           257: .IN "Definitions" "TransparentFrame"
        !           258: .IN "Data Structures" "TransparentFrame"
        !           259: .IN "TransparentFrame"
        !           260: .FD
        !           261: .IN "Definitions" "XCreateWindows"
        !           262: .IN "XCreateWindows"
        !           263: int XCreateWindows (parent, defs, ndefs)
        !           264:        Window parent;
        !           265:        OpaqueFrame defs[];
        !           266:        int ndefs;
        !           267: .FN
        !           268: This subroutine takes an array of window information definitions
        !           269: and creates them in a single handshake with the window system.
        !           270: The caller should have filled in the structure except for the window id.
        !           271: The window id's of the created windows are returned in the structure
        !           272: passed to the subroutine.
        !           273: You must specify the number of windows to be created using the
        !           274: \fIndefs\fP argument.
        !           275: .IN "XCreateWindow"
        !           276: The other side-effects are the same as for \fIXCreateWindow\fP.
        !           277: The subroutine returns the number of windows actually created.
        !           278: .FD
        !           279: .IN "Definitions" "XCreateTransparencies"
        !           280: .IN "XCreateTransparencies"
        !           281: int XCreateTransparencies(parent, defs, ndefs)
        !           282:        Window parent;
        !           283:        TransparentFrame defs[];
        !           284:        int ndefs;
        !           285: .FN
        !           286: This subroutine takes an array of window information definitions
        !           287: and creates the transparencies in a single handshake with the window system.
        !           288: The caller should have filled in the structure except for the window id.
        !           289: The window id's of the created windows are returned in the structure
        !           290: passed to the subroutine.
        !           291: You must specify the number of windows to be created using the
        !           292: ndefs argument.
        !           293: .IN "XCreateWindow"
        !           294: The side effects are the same as for \fIXCreateWindow\fP.
        !           295: The subroutine returns the number of windows actually created.
        !           296: .FD
        !           297: .IN "Definitions" "XCreateWindowBatch"
        !           298: .IN "XCreateWindowBatch"
        !           299: int XCreateWindowBatch(defs, ndefs)
        !           300:        Window parent;
        !           301:        BatchFrame defs[];
        !           302:        int ndefs;
        !           303: .FN
        !           304: This subroutine takes an array of window information definitions
        !           305: and creates the windows of the specified types
        !           306: in a single handshake with the window system.
        !           307: The caller should have filled in the structure except for the window id.
        !           308: The window id's of the created windows are returned in the structure
        !           309: passed to the subroutine.
        !           310: You must specify the number of windows to be created using the
        !           311: ndefs argument.
        !           312: .IN "XCreateWindow"
        !           313: .IN "XCreateTransparency"
        !           314: The side effects are the same as for \fIXCreateWindow\fP and \fIXCreateTransparency\fP.
        !           315: The subroutine returns the number of windows actually created.
        !           316: The parent windows must already exist.
        !           317: .FD
        !           318: .IN "Definitions" "XCreate"
        !           319: .IN "XCreate"
        !           320: Window XCreate(prompt, program, geometry, default, frame, minwidth, minheight)
        !           321:        char *prompt;   /* prompt string */
        !           322:        char *program;  /* program name for Xdefaults */
        !           323:        char *geometry, *default;       /* geometry specs */
        !           324:        OpaqueFrame *frame;     /* background and border pixmaps in */
        !           325:        int minwidth, minheight;        /* minimum size for the window */
        !           326: .FN
        !           327: XCreate does all the work for automatic and manual placement of a window,
        !           328: and is commonly used by most applications for creating graphics related 
        !           329: windows.
        !           330: .PP
        !           331: The \fIprompt\fP argument is used in a prompt window (if needed) to inform the
        !           332: user what application wants to be placed.
        !           333: The \fIprogram\fP name must be passed in with the program argument (usually
        !           334: it should be \fIargv[0]\fP) so that \fIXGetDefault\fP can find out how the
        !           335: user likes to be prompted to create the window.
        !           336: .PP
        !           337: The \fIgeometry\fP and \fIdefault\fP arguments are used to place the position
        !           338: and/or size of the window.
        !           339: .PP
        !           340: The \fIframe\fP passed in must include the background and border pixmaps
        !           341: already specified, and the border width of the window.
        !           342: .PP
        !           343: \fIMinwidth\fP and \fIminheight\fP specify the minimum size of the created window
        !           344: in pixels.
        !           345: .PP
        !           346: The window is not mapped after creation.
        !           347: The function returns the window id of the window just created,
        !           348: and all values in the passed in window \fIframe\fP (as defined above)
        !           349: will be set.
        !           350: .PP
        !           351: The following paragraphs describes the current user interface;
        !           352: it may change in the
        !           353: future somewhat.
        !           354: .IN "XGeometry"
        !           355: .IN "XParseGeometry"
        !           356: If a sufficiently complete geometry specification (see \fIXParseGeometry\fP 
        !           357: and \fIXGeometry\fP)
        !           358: is passed in, the window will be created automatically.
        !           359: If no X or Y locations are set by the geometry spec, the user will be
        !           360: prompted to interactively position the window.
        !           361: A prompt window will be popped up in the upper left hand corner,
        !           362: and the mouse grabbed.
        !           363: .PP
        !           364: .IN "XGrabMouse"
        !           365: .IN "Grabbing" "Mouse"
        !           366: .IN "XGetDefault"
        !           367: The ``MakeWindow'' X defaults ``BodyFont'', ``ReverseVideo'',
        !           368: ``BorderWidth'', ``InternalBorder'', ``Freeze'',
        !           369: ``Foreground'', ``Background'', ``Border''
        !           370: ``Mouse'', ``MouseMask'' control the appearance
        !           371: of a prompt window and the cursor to be used when rubber banding.
        !           372: If ``freeze'' is ``on'', the server will be frozen while the window is being
        !           373: created.
        !           374: So for example, one of these might be specified as ``.MakeWindow.Freeze''
        !           375: in your \fI~/.Xdefaults\fP file.
        !           376: .IN "XGrabServer"
        !           377: .IN "Grabbing" "Server"
        !           378: A box the size of the minimum window will be rubber banded on the
        !           379: screen.
        !           380: .PP
        !           381: If the left button is pressed, the outline of the default window at its
        !           382: default size and location will be shown; when the button is released, the
        !           383: window will be created.
        !           384: If the right button is pressed, the outline of the default window at its
        !           385: default size and the current location of the mouse will be shown;
        !           386: when the button is released, the window's upper left corner will be created
        !           387: at the current cursor location.
        !           388: If the center button is pressed, it indicates one corner of the window should
        !           389: be set at the current mouse location.
        !           390: When the center button is released, the window will be created with the
        !           391: other corner of the window at the current mouse location unless the
        !           392: minimum size has not been met.
        !           393: .FD
        !           394: .IN "Definitions" "XCreateTerm"
        !           395: .IN "XCreateTerm"
        !           396: Window XCreateTerm(prompt, program, geometry, default, frame, minwidth, minheight,
        !           397:        xadder, yadder, cwidth, cheight, f, fwidth, fheight)
        !           398:        char *prompt;   /* prompt string */
        !           399:        char *program;  /* program name for Xdefaults */
        !           400:        char *geometry, *default;       /* geometry specs */
        !           401:        OpaqueFrame *frame;     /* background and border pixmaps in */
        !           402:        int minwidth, minheight;        /* minimum size for the window */
        !           403:        int xadder, yadder;     /* additional space inside window needed */
        !           404:        int *cwidth, *cheight;  /* RETURNs created size of window */
        !           405:        FontInfo *f;    /* font for prompt window */
        !           406:        int fwidth, fheight;    /* size of geometry units */    
        !           407: .FN
        !           408: \fIXCreateTerm\fP
        !           409: does all the work for automatic and manual placement of a window
        !           410: which should be sized in multiples of \fIfwidth\fP and \fIfheight\fP,
        !           411: and is commonly used by most applications for creating text related 
        !           412: windows.
        !           413: .PP
        !           414: The \fIprompt\fP argument is used in a prompt window (if needed) to inform the
        !           415: user what application wants to be placed.
        !           416: The program name must be passed in with the \fIprogram\fP argument (usually
        !           417: it should be \fIargv[0]\fP) so that \fIXGetDefault\fP can find out how the
        !           418: user likes to be prompted to create the window.
        !           419: .PP
        !           420: The geometry and default arguments are used to place the position
        !           421: and/or size of the window.
        !           422: .PP
        !           423: The \fIfwidth\fP and \fIfheight\fP arguments specify the size of the units used in
        !           424: the geometry spec,
        !           425: and the increments the window should be sized in.
        !           426: These are typically the size of a fixed width font, or other
        !           427: graphic object in a window.
        !           428: .PP
        !           429: The \fIframe\fP passed in must include the background and border pixmaps
        !           430: already specified, and the border width of the window.
        !           431: .PP
        !           432: \fIMinwidth\fP and \fIminheight\fP specify the minimum size of the created window in
        !           433: multiples of \fIfwidth\fP and \fIfheight\fP.
        !           434: \fIXadder\fP and \fIyadder\fP is additional interior padding needed in the window.
        !           435: The function returns the window id of the window just created,
        !           436: and all values in the passed in window frame will be set.
        !           437: .PP
        !           438: The window is not `mapped' after creation.
        !           439: .PP
        !           440: The following paragraphs describes the current user interface;
        !           441: it may change in the
        !           442: future somewhat.
        !           443: .IN "XGeometry"
        !           444: .IN "XParseGeometry"
        !           445: If a sufficiently complete geometry specification (see \fIXParseGeometry\fP 
        !           446: and \fIXGeometry\fP)
        !           447: is passed in, the window will be created automatically.
        !           448: If no X or Y locations are set by the geometry spec, the user will be
        !           449: prompted to interactively position the window.
        !           450: A prompt window will be `popped' in the upper left hand corner,
        !           451: and the mouse grabbed.
        !           452: In the prompt window will be appended the width and height of the window
        !           453: in the units specified by \fIfwidth\fP and \fIfheight\fP.
        !           454: .PP
        !           455: .IN "XGrabMouse"
        !           456: .IN "Grabbing" "Mouse"
        !           457: .IN "XGetDefault"
        !           458: The ``MakeWindow'' X defaults ``BodyFont'', ``ReverseVideo'',
        !           459: ``BorderWidth'', ``InternalBorder'', ``Freeze'',
        !           460: ``Foreground'', ``Background'', ``Border''
        !           461: ``Mouse'', ``MouseMask'' control the appearance
        !           462: of a prompt window and the cursor to be used when rubber banding.
        !           463: If ``freeze'' is ``on'', the server will be frozen while the window is being
        !           464: created.
        !           465: So for example, one of these might be specified as ``.MakeWindow.Freeze''
        !           466: in your X defaults file.
        !           467: .IN "XGrabServer"
        !           468: .IN "Grabbing" "Server"
        !           469: A box the size of the minimum window will be rubber banded on the
        !           470: screen.
        !           471: .PP
        !           472: If the left button is pressed, the outline of the default window at the
        !           473: mouse's current position of the default size
        !           474: will be shown; when the button is released, the
        !           475: window will be created.
        !           476: If the right button is pressed, the outline of the default window at its
        !           477: default size and the current location of the mouse will be shown;
        !           478: when the button is released, the window's upper left corner will be created
        !           479: at the current cursor location, and the height of the window will be
        !           480: determined by the height of the screen.
        !           481: If ``.MakeWindow.ClipToScreen'' is ``on'', the window will be
        !           482: clipped to the screen until and unless the minimum size requirements
        !           483: preclude it.
        !           484: If the center button is pressed, it indicates one corner of the window should
        !           485: be set at the current mouse location.
        !           486: When the center button is released, the window will be created with the
        !           487: other corner of the window at the current mouse location unless the
        !           488: minimum size has not been met.

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