pod::Prima::X11(3)

💖 NAME 💖

pod::Prima::X11(3) — a.k.a. the User Contributed Perl Documentation page — is literally the manual for Prima::X11: usage guide for the X11 environment 🦋. Bestie, this is your X11 survival kit, no cap.

🌸 DESCRIPTION 🌸

Okay so this document describes the subtle topics one must be aware of when programming or using Prima programs under X11. It covers various aspects of the toolkit and its implementation details, with guidelines for the expected use. Also, some of the X11 programming techniques are visited along the way ✨. It’s giving essential context, periodt.

💅 Basic command-line switches 💅

These are the command-line switches, bestie — memorize the ones you need:

• --help — Prints the available command-line arguments and exits. Iconic.
• --display — Sets the X display address in the Xlib notation. If not set, the standard Xlib behavior applies, i.e. XOpenDisplay(null). Example:

--display=:0.1

• --visual — Sets the X visual to be used by default. Example:

--visual=0x23

• --sync — Turn on the X synchronization.
• --bg, --fg — Set the default background and foreground colors. Example:

--bg=BlanchedAlmond

• --font — Sets the default font in either XLFD or Fontconfig format. Examples:

--font=serif
--font=Arial-16:bold
--font='adobe-helvetica-medium-r-*-*--*-120-*-*-*-*-*-*'

• --no-x11 — Runs Prima without the X11 display initialized. This switch can be used for programs that use only the OS-independent parts of Prima, such as the image subsystem or the PDF generator, in environments where X is not present, for example, from a CGI script. Any attempt to create an instance of the Prima::Application class or otherwise access the X-depended code under such conditions causes the program to abort. 😭

There are alternatives to the command switch. First, there is the module Prima::noX11 for the same purpose, but that is more convenient to use as the

perl -MPrima::noX11

construct. Second, there is the technique to continue execution even if the connection to the X server fails:

use Prima::noX11;
use Prima;

my $error = Prima::XOpenDisplay();
if ( defined $error) {
     print "not connected to display: $error\n";
} else {
     print "connected to the X display\n";
}

The Prima::noX11 module exports the single function XOpenDisplay into the Prima namespace, to connect to the X display explicitly. The display to be connected to is the $ENV{DISPLAY} unless stated otherwise on the command line (with the --display option) or with a parameter to the XOpenDisplay function.

This technique may be useful to programs that use Prima imaging functionality and may or may not use the windowing capabilities. 🫶

🦋 The X11 resources database 🦋

X11 provides XRDB, the X resource database — a named list of arbitrary string values stored on the X server. Each key is a combination of names and classes of widgets in the text format. The key is constructed so that the leftmost substring (the name or the class) corresponds to the top-level item in the hierarchy, usually the application name or class. Although the XRDB can also be written via the native X API, it is rarely done by applications. Instead, the user creates a file usually named .Xdefaults which contains the database in the text form.

The format of the .Xdefaults file directly reflects the XRDB capabilities, one of the most important of which is globbing, manifested via the * (star) character. With the use of the globbing, the user can set up a property value that corresponds to multiple targets:

*.ListBox.backColor: yellow

The string above means that all widgets of the ListBox class must have a yellow background.

The application itself is responsible for parsing the strings and querying the XRDB. Also, both class and widget names, as well as the database values are fully defined in terms of the application. There are some guidelines though, for example, the colors and fonts are best described in the terms native to the X server. Also, classes and names are distinguished by the case: classes must begin with the uppercase letter. Finally, not every character can be stored in the XRDB database (space, for example, cannot be) and therefore the XRDB API automatically converts these to the _ (underscore) characters.

Prima defines its own set of resources, divided into two parts: general toolkit settings and per-widget settings. The general settings functionality is partially overlapping with the command-line arguments. The per-widget settings are the fonts and colors that can be defined for each Prima widget.

All of the general settings apply to the top-level item of the widget hierarchy, named after the application, and the Prima class. Some of these though needed to be initialized before the application instance itself is created, so these can be accessed via the Prima class only, for example, Prima.Visual. Some, on the contrary, may occasionally overlap with the per-widget syntax. In particular, one must be wary not to write

Prima*font: myfont

instead of

Prima.font: myfont

The latter syntax is a general setting and changes the default Prima font only. The former is a per-widget assignment, and explicitly sets the font to all Prima widgets, effectively ruining the toolkit font inheritance scheme. The same is valid for an even more powerful

*font: myfont

record.

The allowed per-widget settings are the color and font settings only (see the corresponding sections). It is an arguably useful feature to map all the widget properties onto XRDB, but Prima does not implement this, primarily because no one asked for it, and also because this creates unnecessary latency when the enumeration of all possible widget properties takes place for every widget.

All of the global settings’ classes and names are identical except for their first letter. For example, to set the Submenudelay value, one can do it either by the

Prima.Submenudelay: 10

or by the

Prima.submenudelay: 10

syntax. Despite that, these calls are different, in a way that one reaches for the whole class and another for the name, for the majority of these properties it does not matter. To avoid confusion all class names are camelcase while the property names are lowercase.

🎀 Fonts 🎀

Default fonts

Prima::Application defines the set of get_default_XXX_font functions, where each returns the font that is predefined by the system or by the user through the system settings, to be displayed correspondingly in menus, messages, window captions, and all other widgets. While in f ex Win32 these are indeed the configurable user options, the raw X11 protocol doesn’t define any. If the toolkit is compiled with the GTK, then the default fonts can be read from the GTK settings. Nevertheless, as the high-level code relies on these, the corresponding resources are defined. These are:

• font — Application::get_default_font
• caption_font — Application::get_caption_font. Used in Prima::MDI.
• menu_font — Widget::get_default_menu_font. The default font for the pull-down and pop-up menus.
• msg_font — Application::get_message_font. Used in Prima::MsgBox.
• widget_font — Widget::get_default_font.

All of the global font properties can only be set via the Prima class, no application name is recognized. Also, these properties are identical to --font, --menu-font, --caption-font, --msg-font, and --widget-font command-line arguments. The per-widget properties are font and popupFont, of class Font, settable via XRDB only:

Prima*Dialog.font: my-fancy-dialog-font
Prima.FontDialog.font: some-conservative-font

By default, Prima font is 12.helvetica.

X core fonts

The values of the font entries are standard XLFD strings, formatted with the default *-*-*-*-*-*-*-*-*-*-*-*-*-*-* pattern, where each star character can be replaced by a particular font property, such as name, size, charset, and so on. To interactively select an appropriate font, use the standard xfontsel program from the Xorg distribution.

Note, that the encoding part of the font is recommended to be left unspecified, otherwise it may clash with the LANG environment variable that is used by the Prima font subsystem to determine which font to select when no encoding is given. This advice, though, is correct only when both the LANG and encoding part of the desired font match. To force a particular font encoding, the property Prima.font must contain one.

Alternatively, and/or to reduce X font traffic, one may set the IgnoreEncodings.ignoreEncodings property, which is a semicolon-separated list of encodings Prima must not use. This feature has limited usability when for example fonts in the Asian encodings result in large font requests. Another drastic measure to decrease font traffic is the boolean property Noscaledfonts.noscaledfonts, which, if set to 1, restricts the choice of fonts to the non-scalable fonts only.

Xft fonts

Prima can compile with the Xft library, which contrary to core X font API, can make use of the client-side fonts. Plus, the Xft library offers appealing features such as font antialiasing, unicode, and arguably a better font syntax. The Xft font syntax is inherited from the fontconfig library and is to be consulted from man fonts-conf. For example:

Palatino-12

A font with the name Palatino and a size of 12 points.

Arial-10:BI

A font with the name Arial, size of 10 points, bold, and italic. The fontconfig syntax allows more than that, for example, arbitrary matrix transformations, but Prima can make use only of the font name, size, and style flags.

• --no-xft — The --no-xft command-line argument, and the corresponding boolean UseXFT.usexft XRDB property can be used to disable the use of the Xft library.
• --no-core-fonts — Disables all X11 core fonts, except the fixed font. The fixed font is selected for the same reasons that the X server is designed to provide at least one font, which usually is fixed. It is valid to combine --no-core-fonts and --no-xft. Moreover, adding --noscaled to these gives Prima programs the very classic X look.
• --font-priority — Can be set to either xft or core, to select the font provider mechanism to match unknown or incompletely specified fonts against. Default value: xft (if compiled in), core otherwise.
• --no-aa — If set, turns off the Xft font antialiasing.

🌈 Colors 🌈

Okay so X11 has this whole tradition of shipping with a color names database, usually a text file named rgb.txt. Check your X manual for where exactly that file lives and what its format is. The whole idea? Users get portable literal color names, and the actual color values can be transparently adjusted to whatever the display can do. That’s why it’s customary to write stuff like color: green for a bunch of applications, and those apps call the XParseColor function to turn those strings into RGB values. 💅

Prima can support this vibe too. Every widget can assign these eight color properties by name: color, hiliteBackColor, disabledColor, dark3DColor, backColor, hiliteColor, disabledBackColor, and light3DColor. Like:

Prima.backColor: #cccccc

Also, these command-line arguments let you override the default values for those properties:

• --fg — maps to color
• --bg — maps to backColor
• --hilite-fg — maps to hiliteColor
• --hilite-bg — maps to hiliteBackColor
• --disabled-fg — maps to disabledColor
• --disabled-bg — maps to disabledBackColor
• --light — maps to light3DColor
• --dark — maps to dark3DColor

---

✨ XRDB conventions ✨

This is the part where the X resources database does its little magic: set the property name in your XRDB and Prima picks it up. That’s the convention, bestie. 🎀

🦋 Visuals 🦋

So the colors in the X11 protocol require pixel values to be explicitly defined. A pixel value is a 32-bit unsigned integer that encodes color in the display format. There are two different color coding schemes: direct color and indexed color.

A direct color-coded pixel value can be unambiguously converted into an RGB value without any additional information. The indexed-color scheme represents the pixel value as an index in a palette that lives on the X server. An X11 display can contain more than one palette, and it can allow (or disallow) modification of the palette color cells depending on the visual the palette is attached to.

A visual is an X server resource with a specific representation of the color coding scheme, color bit depth, and modifiability of the palette. The X server can (and usually does) provide more than one visual, plus different pixel bit depths. There are six classes of visuals in the X11 paradigm. Prima behaves differently in each one, and also depending on the display bit depth available. In particular, color dithering can be used on displays with less than 12-bit color depth. On displays with a modifiable color palette, Prima can install its own values in palettes, which may result in an effect known as palette flashing. 😭

To switch to a non-default visual, use the Prima.Visual XRDB property or the --visual command-line argument. You can get the list of visuals from the standard xdpyinfo command from the Xorg distribution, where each class of the visual corresponds to one of these six:

• StaticGray — all color cells are read-only and contain monochrome values only. A typical example is a two-color, black-and-white monochrome display. This visual is extremely rare. 💀
• GrayScale — contains a modifiable color palette, and is capable of displaying monochrome values only. Theoretically, any paletted display on a monochrome monitor can be treated as a GrayScale visual. For both GrayScale and StaticGray visuals, Prima resorts to dithering if it cannot get at least 32 evenly spaced gray values from black to white.
• StaticColor — all color cells are read-only. A typical example is a PC display in the 16-color EGA mode. This visual is extremely rare.
• PseudoColor — all color cells are modifiable. Typically, 8-bit displays define this class as the default visual. For both StaticColor and PseudoColor visuals, dithering is always used, although on the PseudoColor visuals Prima resorts to that only if the X server cannot allocate a required color.
• TrueColor — each pixel value is explicitly coded as RGB. Typical examples are 16, 24, or 32-bit display modes. This visual class is the best in terms of visual quality. 👑
• DirectColor — same as TrueColor, but additionally each pixel value can be reprogrammed. Not all hardware supports this visual, and usually this visual is not set as the default one. Prima supports this mode in the same way it does the TrueColor visual, without any additional features.

On the PseudoColor and GrayScale visuals, Prima allocates a small fixed set of colors, not used for palette modifications. When a pixmap is to be exported via clipboard, displayed in the menu, or sent to the window manager as an icon to be attached to a window, it is resampled so that it uses these colors only, which are guaranteed to stay immutable through the life of the application. 🫶

---

🎀 Images 🎀

The X11 protocol does not standardize the pixel memory format for TrueColor and DirectColor visuals, so there’s a chance Prima won’t work on some bizarre hardware. Currently, Prima knows how to compose pixels of 15, 16, 24, and 32 bit depth, of contiguous (not interspersed) red-green-blue memory layout. Any other pixel memory layout causes Prima to fail. Like, hard fail, bestie. 💀

Prima supports the shared memory image X extension, which greatly speeds up displaying images on X servers running on the same machine as the X client. The price for this? If the Prima program aborts, the shared memory will never be returned to the OS. To remove the leftover segments, use your OS facilities, for example ipcrm on Linux and BSD.

To disable the use of shared memory with images, use the --no-shmem switch in the command-line arguments. ✨

The clipboard exchange of images is incompletely implemented, since Prima does not accompany (and neither reads) COLORMAP, FOREGROUND, and BACKGROUND clipboard data, which contains the RGB values for the paletted image. As a palliative, the clipboard-bound images are downgraded to the safe immutable set of colors.

A note on images in the clipboard: contrary to text in the clipboard, which can be used several times, images seemingly cannot. The Bitmap or Pixmap descriptor stored in the clipboard is rendered invalid after it has been read once. This does not apply to the more modern clipboard exchange protocol based on images being encoded as binary data, f ex in PNG format. Prima prefers this exchange protocol whenever possible. 🦋

---

💅 Window managers 💅

The original design of the X protocol did not include the notion of a window manager, and the latter was implemented as an ad-hoc patch, which results in possible race conditions when configuring widgets. 🙈

Prima was tested with alternating success under the following window managers: mutter, marco, mwm, kwin, wmaker, fvwm, fvwm2, enlightenment, sawfish, blackbox, 9wm, olvm, twm, and in a no-WM environment.

🔥 Protocols 🔥

Prima makes use of the WM_DELETE_WINDOW and WM_TAKE_FOCUS protocols. The WM_DELETE_WINDOW protocol usage is straightforward and needs no further attention. The WM_TAKE_FOCUS protocol can be tricky, though, since X11 defines several input modes for a widget, and they behave differently for each WM. In particular, the “focus follows pointer” policy gives problems under twm and mwm when navigation of drop-down combo boxes is greatly hindered by the window manager. The drop-down list is programmed so it is dismissed as soon as its focus is gone; these window managers withdraw focus even if the pointer is over the focused widget’s border. 😭

🌸 Hints 🌸

Size, position, icons, and other standard X hints are passed to the WM in a standard way, and, as the inter-client communication manual (ICCCM) allows, are often misinterpreted by window managers. Many (like wmaker, for example) apply the coordinates given by the program not to the top-level widget itself, but to its decoration. mwm defines a list of accepted icon sizes, so these can be absurdly large, which adds to the confusion for an X client that can create an icon of any size but is unable to determine the best one. 🌀

⭐ Non-standard properties ⭐

Prima tries to use the WM-specific hints for two window managers it knows about: mwm and kwin. For mwm (Motif window manager), Prima sets hints for the decoration border width and icons. For kwin (and probably others that conform to the specifications of http://www.freedesktop.org/), Prima uses the NET_WM_STATE property, in particular for the implementation of the window maximization and the visibility of windows in the taskbar.

Use of these properties explicitly contradicts ICCCM and definitely might lead to bugs in the future (at least with NET_WM_STATE, since the Motif interface can hardly be expected to be changed). To disable the use of the non-standard WM properties, the --icccm command-line argument can be set. ⚠️

---

👑 Unicode 👑

The core X11 protocol does not support unicode, and a number of patches were applied to X servers and clients to make the situation change. Prima can only effectively support unicode text shaping and rendering if compiled with the Xft, fontconfig, harfbuzz, and fribidi libraries.

The core X11 protocol supports text rendering when the text is sent as either 8-bit or 16-bit integers, but neither can be used to display unicode strings properly. Also, the core font transfer protocol suffers from ineffective memory representation, which creates latency when fonts with a large span of glyphs are loaded. Such fonts, in the still uncommon but standard iso10646 encoding, are the only media to display multi-encoding text if the Xft services are unavailable.

These and some other problems are efficiently solved by the Xft library, a superset of X core font functionality. Xft features Level 1 (November 2003) unicode display and supports 32-bit text strings as well as UTF8-coded strings. Xft does not operate with charset encodings, and these are implemented in Prima using the iconv charset converter library. 🧚

🍓 Clipboard 🍓

Prima supports UTF8 text in the clipboard via the UTF8_STRING format.

Because any application can take ownership of the clipboard at any time, open/close brackets are not strictly respected in the X11 implementation. Practically, this means that when modern X11 clipboard daemons (KDE klipper, for example) interfere with the Prima clipboard, the results may not be consistent from the programmer’s view — for example, the clipboard contains data after a clear call. It must be noted though that this behavior is expected by the users. 💖

✨ Other XRDB resources ✨

So here's the tea, bestie: XRDB has more little knobs besides the font/color/image stuff. These are the extra settings Prima recognizes, and they are lowkey essential for making your app feel right.

⏰ Timeouts ⏰

Real talk: the X11 protocol does not provide GUI helpers like the double-click event, cursor, or menu. It also does not give you the related timing — like how often a cursor should blink, for example. So Prima emulates these things, but lets you reprogram the matching timeouts. Prima recognizes the following properties, and you can reach them either through the application name or the Prima class key. Every timeout is an integer value: the number of milliseconds for the corresponding timeout property.

• Blinkinvisibletime.blinkinvisibletime: MSEC — the cursor stays invisible for MSEC milliseconds. Default value: 500.
• Blinkvisibletime.blinkvisibletime: MSEC — the cursor stays visible for MSEC milliseconds. Default value: 500.
• Clicktimeframe.clicktimeframe MSEC — if the 'mouse down' and 'mouse up' events follow each other within MSEC milliseconds, the 'mouse click' event is synthesized. Default value: 200.
• Doubleclicktimeframe.doubleclicktimeframe MSEC — if the 'mouse click' and 'mouse down' events follow each other within MSEC milliseconds, the 'mouse double click' event is synthesized. Default value: 200.
• Submenudelay.submenudelay MSEC — when the user clicks on a menu item that points to a lower-level menu window, the latter is displayed after MSEC milliseconds. Default value: 200.
• Scrollfirst.scrollfirst MSEC — this is the 'first' timeout. When an auto-repetitive action, similar to keystroke events resulting from a long key press on the keyboard, is to be simulated, two timeout values are used: the 'first' and the 'next' delay. These actions are not simulated within Prima core, and the corresponding timeouts are advisory for the programmer. Prima widgets use it for automatic scrolling, either by a scrollbar or by any other means. Also, the Prima::Button widgets can use these timeouts for the emulation of a key press in the autoRepeat mode. Scrollfirst is a 'first' timeout. Default value: 200.
• Scrollnext.scrollnext MSEC — same as Scrollfirst but for the 'next' delay event. Default value: 50.

🎀 Miscellaneous 🎀

• Visual.visual: VISUAL_ID — selects the display visual VISUAL_ID, which usually has the form of a "0x??" hexadecimal number. Different visuals provide different color depth and pixel encoding schemes. Some X servers have badly chosen default visuals (for example, the default IRIX workstation setup has an 8-bit default visual selected), so this property can be used to fix things. A list of the visuals supported by the X display can be produced interactively by the standard xdpyinfo command from the Xorg distribution. Identical to the --visual command-line argument. See Color for more information.
• Wheeldown.wheeldown BUTTON — BUTTON is the numeric ID of the X mouse button that corresponds to the mouse wheel 'down' event. Default value: 5 (the default values for wheeldown and wheelup are the current de-facto most popular settings).
• Wheelup.wheelup BUTTON — BUTTON is the numeric ID of the X mouse button that corresponds to the mouse wheel 'up' event. Default value: 4.

---

🐛 Debugging 🐛

The famous 'use the source' call is super relevant with Prima. But some debug information comes already compiled in, and you can activate it with the --debug command-line key. Its parameter is a combination of letters, and each letter turns on debugging for a different subsystem:

• C — clipboard
• E — events subsystem
• F — fonts
• M — miscellaneous debug info
• P — palettes and colors
• X — XRDB
• A — all of the above

Example:

--debug=xf

Also, the built-in X API XSynchronize call — which enables the X protocol synchronization, at the expense of operation slowdown though — is activated with the --sync command-line argument, and can be used to ease the debugging.

🌈 GTK 🌈

Prima can be compiled with GTK and can use its colors and font schemes, and also the standard GTK file dialogs. This can be disabled with the --no-gtk command line switch.

On MacOSX, GTK usually comes compiled with the Quartz backend, which means that Prima will get into problems with the remote X11 connections. Prima tries to detect this condition, but if the trouble persists, please use the --no-gtk switch (and please file a bug report so this can be fixed, too).

🍓 Quartz 🍓

Prima can be compiled with the Cocoa library on MacOSX that gives access to the screen scraping functionality that is used by the Application.get_image method and which otherwise is non-functional with XQuartz. To disable this feature use the --no-quartz command-line switch.

👑 AUTHOR 👑

Dmitry Karasik, <dmitry@karasik.eu.org>.

🦋 SEE ALSO 🦋

Prima, Prima::gp-problems, Prima::Widget, Nye A, Xlib programming manual. O'Reilly & Associates, 1995.

---

That's the whole vibe, bestie! This page is pod::Prima::X11(3), Perl v5.42.0, dated 2024-08-20 — now go be the main character of your X11 setup 💅✨