X11 basic manual

The explanations for all arguments that you can pass and are returned start with the words specifies and returns. All other pointers passed to these functions are used for reading only. Before your program can use a display, you must establish a connection to the X server. Once you have established a connection, you then can use the Xlib macros and functions discussed in this chapter to return information about the display.

This chapter discusses how to:. To open a connection to the X server that controls a display, use XOpenDisplay. Specifies the hardware display name, which determines the display and communications domain to be used. The encoding and interpretation of the display name are implementation-dependent. Strings in the Host Portable Character Encoding are supported; support for other characters is implementation-dependent.

Specifies a protocol family or an alias for a protocol family. Supported protocol families are implementation dependent. The protocol entry is optional. Specifies the name of the host machine on which the display is physically attached.

You follow the hostname with either a single colon : or a double colon Specifies the number of the display server on that host machine. You may optionally follow this display number with a period. A single CPU can have more than one display. Multiple displays are usually numbered starting with zero. Specifies the screen to be used on that server. Multiple screens can be controlled by a single X server. The XOpenDisplay function returns a Display structure that serves as the connection to the X server and that contains all the information about that X server.

If the protocol is specified as "tcp", "inet", or "inet6", or if no protocol is specified and the hostname is a host machine name and a single colon : separates the hostname and display number, XOpenDisplay connects using TCP streams.

Otherwise, the implementation determines which IP version is used. If the hostname and protocol are both not specified, Xlib uses whatever it believes is the fastest transport. If the hostname is a host machine name and a double colon :: separates the hostname and display number, XOpenDisplay connects using DECnet. A single X server can support any or all of these transport mechanisms simultaneously. A particular Xlib implementation can support many more of these transport mechanisms.

After a successful call to XOpenDisplay , all of the screens in the display can be used by the client. You can access elements of the Display and Screen structures only by using the information macros or functions. For information about using macros and functions to obtain information from the Display structure, see section 2.

X servers may implement various types of access control mechanisms see section 9. The Xlib library provides a number of useful macros and corresponding functions that return data from the Display structure. The macros are used for C programming, and their corresponding function equivalents are for other language bindings. This section discusses the:. All other members of the Display structure that is, those for which no macros are defined are private to Xlib and must not be used. Applications must never directly modify or inspect these private members of the Display structure.

These functions really should be named Screen whatever and XScreen whatever , not Display whatever or XDisplay whatever. Our apologies for the resulting confusion. Applications should not directly modify any part of the Display and Screen structures. The members should be considered read-only, although they may change as the result of other operations on the display.

The following lists the C language macros, their corresponding function equivalents that are for other language bindings, and what data both can return. Both return a value with all bits set to 1 suitable for use in a plane argument to a procedure. Both BlackPixel and WhitePixel can be used in implementing a monochrome application.

These pixel values are for permanently allocated entries in the default colormap. The actual RGB red, green, and blue values are settable on some screens and, in any case, may not actually be black or white. The names are intended to convey the expected relative intensity of the colors.

ConnectionNumber display ;. Both return a connection number for the specified display. Both return the default colormap ID for allocation on the specified screen. Most routine allocations of color should be made out of this colormap. Both return the depth number of planes of the default root window for the specified screen. Other depths may also be supported on this screen see XMatchVisualInfo. To determine the number of depths that are available on a given screen, use XListDepths.

The XListDepths function returns the array of depths that are available on the specified screen. To release the memory allocated for the array of depths, use XFree. Both return the default graphics context for the root window of the specified screen.

This GC is created for the convenience of simple applications and contains the default GC components with the foreground and background pixel values initialized to the black and white pixels for the screen, respectively. You can modify its contents freely because it is not used in any Xlib function. This GC should never be freed.

DefaultRootWindow display ;. Both return the root window for the default screen. DefaultScreenOfDisplay display ;. Both return a pointer to the default screen. Both return a pointer to the indicated screen. DefaultScreen display ;. Both return the default screen number referenced by the XOpenDisplay function. This macro or function should be used to retrieve the screen number in applications that will use only a single screen.

Both return the default visual type for the specified screen. For further information about visual types, see section 3. Both return the number of entries in the default colormap. Both return the depth of the root window of the specified screen. For an explanation of depth, see the glossary.

DisplayString display ;. Both return the string that was passed to XOpenDisplay when the current display was opened. These are useful to applications that invoke the fork system call and want to open a new connection to the same display from the child process as well as for printing error messages.

The XExtendedMaxRequestSize function returns zero if the specified display does not support an extended-length protocol encoding; otherwise, it returns the maximum request size in 4-byte units supported by the server using the extended-length encoding. The XMaxRequestSize function returns the maximum request size in 4-byte units supported by the server without using an extended-length protocol encoding.

Single protocol requests to the server can be no larger than this size unless an extended-length protocol encoding is supported by the server. The protocol guarantees the size to be no smaller than units bytes. LastKnownRequestProcessed display ;.

Both extract the full serial number of the last request known by Xlib to have been processed by the X server. Xlib automatically sets this number when replies, events, and errors are received.

NextRequest display ;. Both extract the full serial number that is to be used for the next request. Serial numbers are maintained separately for each display connection. ProtocolVersion display ;. Both return the major version number 11 of the X protocol associated with the connected display.

ProtocolRevision display ;. Both return the minor protocol revision number of the X server. QLength display ;. Both return the length of the event queue for the connected display. Note that there may be more events that have not been read into the queue yet see XEventsQueued. Both return the root window. These are useful with functions that need a drawable of a particular screen and for creating top-level windows.

ScreenCount display ;. Both return the number of available screens. ServerVendor display ;. Both return a pointer to a null-terminated string that provides some identification of the owner of the X server implementation. Otherwise, the contents of the string are implementation-dependent. VendorRelease display ;. Both return a number related to a vendor's release of the X server.

Applications are required to present data to the X server in a format that the server demands. To help simplify applications, most of the work required to convert the data is provided by Xlib see sections 8. The XPixmapFormatValues structure provides an interface to the pixmap format information that is returned at the time of a connection setup. It contains:. To obtain the pixmap format information for a given display, use XListPixmapFormats.

The following lists the C language macros, their corresponding function equivalents that are for other language bindings, and what data they both return for the specified server and screen. These are often used by toolkits as well as by simple applications. ImageByteOrder display ;. Both specify the required byte order for images for each scanline unit in XY format bitmap or for each pixel value in Z format.

XBitmapUnit display ;. Both return the size of a bitmap's scanline unit in bits. The scanline is calculated in multiples of this value. BitmapBitOrder display ;. Within each bitmap unit, the left-most bit in the bitmap as displayed on the screen is either the least significant or most significant bit in the unit. BitmapPad display ;. Each scanline must be padded to a multiple of bits returned by this macro or function. Both return an integer that describes the height of the screen in pixels.

Both return the height of the specified screen in millimeters. Both return the width of the screen in pixels. Both return the width of the specified screen in millimeters.

The following lists the C language macros, their corresponding function equivalents that are for other language bindings, and what data they both can return. These macros or functions all take a pointer to the appropriate screen structure. BlackPixelOfScreen screen ;. Both return the black pixel value of the specified screen. XWhitePixelOfScreen screen ;.

Both return the white pixel value of the specified screen. CellsOfScreen screen ;. Both return the number of colormap cells in the default colormap of the specified screen. DefaultColormapOfScreen screen ;. Both return the default colormap of the specified screen. DefaultDepthOfScreen screen ;. Both return the depth of the root window. DefaultGCOfScreen screen ;.

Both return a default graphics context GC of the specified screen, which has the same depth as the root window of the screen.

The GC must never be freed. XDefaultVisualOfScreen screen ;. Both return the default visual of the specified screen. For information on visual types, see section 3. DoesBackingStore screen ;. Both return a value indicating whether the screen supports backing stores. DoesSaveUnders screen ;.

Both return a Boolean value indicating whether the screen supports save unders. If True , the screen supports save unders. If False , the screen does not support save unders see section 3. DisplayOfScreen screen ;. Both return the display of the specified screen. ScreenNumberOfScreen screen ;. EventMaskOfScreen screen ;. Both return the event mask of the root window for the specified screen at connection setup time. WidthOfScreen screen ;. Both return the width of the specified screen in pixels.

HeightOfScreen screen ;. Both return the height of the specified screen in pixels. WidthMMOfScreen screen ;. HeightMMOfScreen screen ;. MaxCmapsOfScreen screen ;. Both return the maximum number of installed colormaps supported by the specified screen see section 9.

MinCmapsOfScreen screen ;. Both return the minimum number of installed colormaps supported by the specified screen see section 9. PlanesOfScreen screen ;. RootWindowOfScreen screen ;. Both return the root window of the specified screen. To free in-memory data that was created by an Xlib function, use XFree. The XFree function is a general-purpose Xlib routine that frees the specified data.

You must use it to free any objects that were allocated by Xlib, unless an alternate function is explicitly specified for the object. A NULL pointer cannot be passed to this function. To close a display or disconnect from the X server, use XCloseDisplay. The XCloseDisplay function closes the connection to the X server for the display specified in the Display structure and destroys all windows, resource IDs Window , Font , Pixmap , Colormap , Cursor , and GContext , or other resources that the client has created on this display, unless the close-down mode of the client has been changed see XSetCloseDownMode.

Therefore, these windows, resource IDs, and other resources should never be referenced again or an error will be generated. Xlib provides a function to permit the resources owned by a client to survive after the client's connection is closed. Specifies the client close-down mode. The XSetCloseDownMode function defines what will happen to the client's resources at connection close.

A connection starts in DestroyAll mode. When the X server's connection to a client is closed either by an explicit call to XCloseDisplay or by a process that exits, the X server performs the following automatic operations:. It disowns all selections owned by the client see XSetSelectionOwner.

It performs an XUngrabServer if the client has grabbed the server. It marks all resources including colormap entries allocated by the client either as permanent or temporary, depending on whether the close-down mode is RetainPermanent or RetainTemporary. However, this does not prevent other client applications from explicitly destroying the resources see XSetCloseDownMode.

When the close-down mode is DestroyAll , the X server destroys all of a client's resources as follows:. It examines each window in the client's save-set to determine if it is an inferior subwindow of a window created by the client.

The save-set is a list of other clients' windows that are referred to as save-set windows. If so, the X server reparents the save-set window to the closest ancestor so that the save-set window is not an inferior of a window created by the client. The reparenting leaves unchanged the absolute coordinates with respect to the root window of the upper-left outer corner of the save-set window.

It performs a MapWindow request on the save-set window if the save-set window is unmapped. The X server does this even if the save-set window was not an inferior of a window created by the client.

It performs the appropriate free request on each nonwindow resource created by the client in the server for example, Font , Pixmap , Cursor , Colormap , and GContext. Additional processing occurs when the last connection to the X server closes. An X server goes through a cycle of having no connections and having some connections.

It resets its state as if it had just been started. The X server begins by destroying all lingering resources from clients that have terminated in RetainPermanent or RetainTemporary mode. It deletes all properties on all root windows see section 4. It resets all device maps and attributes for example, key click, bell volume, and acceleration as well as the access control list. However, the X server does not reset if you close a connection with a close-down mode set to RetainPermanent or RetainTemporary.

On systems that have threads, support may be provided to permit multiple threads to use Xlib concurrently. To initialize support for concurrent threads, use XInitThreads. The XInitThreads function initializes Xlib support for concurrent threads. This function must be the first Xlib function a multi-threaded program calls, and it must complete before any other Xlib call is made.

This function returns a nonzero status if initialization was successful; otherwise, it returns zero. On systems that do not support threads, this function always returns zero. It is only necessary to call this function if multiple threads might use Xlib concurrently. If all calls to Xlib functions are protected by some other access mechanism for example, a mutual exclusion lock in a toolkit or through explicit client programming , Xlib thread initialization is not required.

It is recommended that single-threaded programs not call this function. To lock a display across several Xlib calls, use XLockDisplay.

The XLockDisplay function locks out all other threads from using the specified display. Other threads attempting to use the display will block until the display is unlocked by this thread. This function has no effect unless Xlib was successfully initialized for threads using XInitThreads. To unlock a display, use XUnlockDisplay. The XUnlockDisplay function allows other threads to use the specified display again. Any threads that have blocked on the display are allowed to continue.

Nested locking works correctly; if XLockDisplay has been called multiple times by a thread, then XUnlockDisplay must be called an equal number of times before the display is actually unlocked. In addition to the connection to the X server, an Xlib implementation may require connections to other kinds of servers for example, to input method servers as described in chapter Toolkits and clients that use multiple displays, or that use displays in combination with other inputs, need to obtain these additional connections to correctly block until input is available and need to process that input when it is available.

Simple clients that use a single display and block for input in an Xlib event function do not need to use these facilities.

To track internal connections for a display, use XAddConnectionWatch. The XAddConnectionWatch function registers a procedure to be called each time Xlib opens or closes an internal connection for the specified display.

This function can be called at any time after a display is opened. If internal connections already exist, the registered procedure will immediately be called for each of them, before XAddConnectionWatch returns. XAddConnectionWatch returns a nonzero status if the procedure is successfully registered; otherwise, it returns zero.

The registered procedure should not call any Xlib functions. If the procedure directly or indirectly causes the state of internal connections or watch procedures to change, the result is not defined. If Xlib has been initialized for threads, the procedure is called with the display locked and the result of a call by the procedure to any Xlib function that locks the display is not defined unless the executing thread has externally locked the display using XLockDisplay.

To stop tracking internal connections for a display, use XRemoveConnectionWatch. The XRemoveConnectionWatch function removes a previously registered connection watch procedure. To process input on an internal connection, use XProcessInternalConnection.

The XProcessInternalConnection function processes input available on an internal connection. This function should be called for an internal connection only after an operating system facility for example, select or poll has indicated that input is available; otherwise, the effect is not defined. To obtain all of the current internal connections for a display, use XInternalConnectionNumbers. The XInternalConnectionNumbers function returns a list of the file descriptors for all internal connections currently open for the specified display.

When the allocated list is no longer needed, free it by using XFree. This functions returns a nonzero status if the list is successfully allocated; otherwise, it returns zero. On some display hardware, it may be possible to deal with color resources in more than one way.

For example, you may be able to deal with a screen of either bit depth with arbitrary mapping of pixel to color pseudo-color or bit depth with 8 bits of the pixel dedicated to each of red, green, and blue. These different ways of dealing with the visual aspects of the screen are called visuals. For each screen of the display, there may be a list of valid visual types supported at different depths of the screen. Because default windows and visual types are defined for each screen, most simple applications need not deal with this complexity.

Xlib provides macros and functions that return the default root window, the default depth of the default root window, and the default visual type see sections 2.

Xlib uses an opaque Visual structure that contains information about the possible color mapping. The visual utility functions see section The following concepts may serve to make the explanation of visual types clearer. The screen can be color or grayscale, can have a colormap that is writable or read-only, and can also have a colormap whose indices are decomposed into separate RGB pieces, provided one is not on a grayscale screen.

This leads to the following diagram:. Conceptually, as each pixel is read out of video memory for display on the screen, it goes through a look-up stage by indexing into a colormap.

Colormaps can be manipulated arbitrarily on some hardware, in limited ways on other hardware, and not at all on other hardware. The visual types affect the colormap and the RGB values in the following ways:.

GrayScale is treated the same way as PseudoColor except that the primary that drives the screen is undefined. Thus, the client should always store the same value for red, green, and blue in the colormaps. For DirectColor , a pixel value is decomposed into separate RGB subfields, and each subfield separately indexes the colormap for the corresponding value. The RGB values can be changed dynamically. These RGB values are server dependent but provide linear or near-linear ramps in each primary.

StaticColor is treated the same way as PseudoColor except that the colormap has predefined, read-only, server-dependent RGB values. StaticGray is treated the same way as StaticColor except that the RGB values are equal for any single pixel value, thus resulting in shades of gray. StaticGray with a two-entry colormap can be thought of as monochrome. Each has one contiguous set of bits with no intersections.

Actual RGB values are unsigned bit numbers. For DirectColor and TrueColor , this is the size of an individual pixel subfield. All InputOutput windows have a border width of zero or more pixels, an optional background, an event suppression mask which suppresses propagation of events from children , and a property list see section 4.

The window border and background can be a solid color or a pattern, called a tile. All windows except the root have a parent and are clipped by their parent. If a window is stacked on top of another window, it obscures that other window for the purpose of input.

If a window has a background almost all do , it obscures the other window for purposes of output. Attempts to output to the obscured area do nothing, and no input events for example, pointer motion are generated for the obscured area.

Windows also have associated property lists see section 4. Both InputOutput and InputOnly windows have the following common attributes, which are the only attributes of an InputOnly window:. If you specify any other attributes for an InputOnly window, a BadMatch error results.

InputOnly windows are used for controlling input events in situations where InputOutput windows are unnecessary. InputOnly windows are invisible; can only be used to control such things as cursors, input event generation, and grabbing; and cannot be used in any graphics requests. Note that InputOnly windows cannot have InputOutput windows as inferiors.

Windows have borders of a programmable width and pattern as well as a background pattern or tile. Pixel values can be used for solid colors. The background and border pixmaps can be destroyed immediately after creating the window if no further explicit references to them are to be made. The pattern can either be relative to the parent or absolute. If ParentRelative , the parent's background is used.

When windows are first created, they are not visible not mapped on the screen. Any output to a window that is not visible on the screen and that does not have backing store will be discarded. An application may wish to create a window long before it is mapped to the screen. When a window is eventually mapped to the screen using XMapWindow , the X server generates an Expose event for the window if backing store has not been maintained. A window manager can override your choice of size, border width, and position for a top-level window.

Your program must be prepared to use the actual size and position of the top window. It is not acceptable for a client application to resize itself unless in direct response to a human command to do so.

Instead, either your program should use the space given to it, or if the space is too small for any useful work, your program might ask the user to resize the window.

The border of your top-level window is considered fair game for window managers. To set an attribute of a window, set the appropriate member of the XSetWindowAttributes structure and OR in the corresponding value bitmask in your subsequent calls to XCreateWindow and XChangeWindowAttributes , or use one of the other convenience functions that set the appropriate attribute. The symbols for the value mask bits and the XSetWindowAttributes structure are:.

The following lists the defaults for each window attribute and indicates whether the attribute is applicable to InputOutput and InputOnly windows:. Only InputOutput windows can have a background. You can set the background of an InputOutput window by using a pixel or a pixmap. The background-pixmap attribute of a window specifies the pixmap to be used for a window's background.

This pixmap can be of any size, although some sizes may be faster than others. The background-pixel attribute of a window specifies a pixel value used to paint a window's background in a single color. You can set the background-pixmap to a pixmap, None default , or ParentRelative. You can set the background-pixel of a window to any pixel value no default.

If you specify a background-pixel, it overrides either the default background-pixmap or any value you may have set in the background-pixmap. A pixmap of an undefined size that is filled with the background-pixel is used for the background. Range checking is not performed on the background pixel; it simply is truncated to the appropriate number of bits. If you set the background-pixmap, it overrides the default. The background-pixmap and the window must have the same depth, or a BadMatch error results.

If you set background-pixmap to None , the window has no defined background. If you set the background-pixmap to ParentRelative :. The parent window's background-pixmap is used. The child window, however, must have the same depth as its parent, or a BadMatch error results. If the parent window has a background-pixmap of None , the window also has a background-pixmap of None. A copy of the parent window's background-pixmap is not made.

The parent's background-pixmap is examined each time the child window's background-pixmap is required. The background tile origin always aligns with the parent window's background tile origin. If the background-pixmap is not ParentRelative , the background tile origin is the child window's origin. Setting a new background, whether by setting background-pixmap or background-pixel, overrides any previous background. The background-pixmap can be freed immediately if no further explicit reference is made to it the X server will keep a copy to use when needed.

If you later draw into the pixmap used for the background, what happens is undefined because the X implementation is free to make a copy of the pixmap or to use the same pixmap.

When no valid contents are available for regions of a window and either the regions are visible or the server is maintaining backing store, the server automatically tiles the regions with the window's background unless the window has a background of None.

If the background is None , the previous screen contents from other windows of the same depth as the window are simply left in place as long as the contents come from the parent of the window or an inferior of the parent. Otherwise, the initial contents of the exposed regions are undefined. Expose events are then generated for the regions, even if the background-pixmap is None see section Only InputOutput windows can have a border.

You can set the border of an InputOutput window by using a pixel or a pixmap. The border-pixmap attribute of a window specifies the pixmap to be used for a window's border.

The border-pixel attribute of a window specifies a pixmap of undefined size filled with that pixel be used for a window's border. The border tile origin is always the same as the background tile origin. You can also set the border-pixmap to a pixmap of any size some may be faster than others or to CopyFromParent default.

You can set the border-pixel to any pixel value no default. If you set a border-pixmap, it overrides the default. The border-pixmap and the window must have the same depth, or a BadMatch error results. If you set the border-pixmap to CopyFromParent , the parent window's border-pixmap is copied. Subsequent changes to the parent window's border attribute do not affect the child window.

However, the child window must have the same depth as the parent window, or a BadMatch error results. The border-pixmap can be freed immediately if no further explicit reference is made to it. If you later draw into the pixmap used for the border, what happens is undefined because the X implementation is free either to make a copy of the pixmap or to use the same pixmap.

If you specify a border-pixel, it overrides either the default border-pixmap or any value you may have set in the border-pixmap. All pixels in the window's border will be set to the border-pixel. Setting a new border, whether by setting border-pixel or by setting border-pixmap, overrides any previous border. Output to a window is always clipped to the inside of the window. Therefore, graphics operations never affect the window border.

The bit gravity of a window defines which region of the window should be retained when an InputOutput window is resized. Download F-Droid Version 1. Permissions modify or delete the contents of your shared storage. This app can get your approximate location from location services while the app is in use. Location services for your device must be turned on for the app to get location. This app can get your precise location from location services while the app is in use.

This may increase battery usage. Allows the app to create network sockets and use custom network protocols. The browser and other applications provide means to send data to the internet, so this permission is not required to send data to the internet. XBasic uses functionallity of the gmp library, the GNU multiple precision arithmetic library, Version 5. Copyright , , , , , , , , , , , , , , , Free Software Foundation, Inc.

XBasic uses the lodepng code for the PNG bitmap graphics support. Copyright c Lode Vandevenne. XBasic uses a md5 algorithm Copyright c by Alexander Peslyak public domain. The sources for libx11basic and the XBasic user manual are maintained in the XBasic main repository, called "X11Basic" and hosted on codeberg.

They are just cloned into this repository. The build scrips are there but require a bit linux environment. So far, I haven't managed to built these libraries myself, so a little trust in that external project is still required.

Remember cloning this repository with the --recursive option, because it has submodules libgmp :. This website works better with JavaScript. Codeberg Community Issues Documentation Blog. Register Sign In. Watch 2. Star 3.