Provided by: libprima-perl_1.28-1.4_amd64 
NAME
Prima::X11 - usage guide for X11 environment
DESCRIPTION
This document describes subtle topics one must be aware when programming or using Prima
programs under X11.
The document covers various aspects of the toolkit and their implementation details with
guidelines of the expected use. Also, standard X11 user-level and programming techniques
are visited.
Basic command-line switches
"--help"
Prints the command-line arguments available and exits.
"--display"
Sets X display address in Xlib notation. If not set, standard Xlib (
"XOpenDisplay(null)" ) behavior applies.
Example:
--display=:0.1
"--visual"
Sets X visual, to be used by default. Example:
--visual=0x23
"--sync"
Turn off X synchronization
"--bg", "--fg"
Set default background and foreground colors. Example:
--bg=BlanchedAlmond
"--font"
Sets default font. Example:
--font='adobe-helvetica-medium-r-*-*--*-120-*-*-*-*-*-*'
"--no-x11"
Runs Prima without X11 display initialized. This switch can be used for programs that
use only OS-independent parts of Prima, such as image subsystem or PostScript
generator, in environments where X is not present, for example, a CGI script.
Obviously, any attempt to create instance of "Prima::Application" or otherwise access
X-depended code under such conditions causes the program to abort.
There are alternatives to use the command switch. First, there is module
"Prima::noX11" for the same purpose but more convenient to use as
perl -MPrima::noX11
construct. Second, there is a technique to continue execution even if connection to a
X server failed:
use Prima::noX11;
use Prima;
my $error = Prima::XOpenDisplay();
if ( defined $error) {
print "not connected to display: $error\n";
} else {
print "connected to display\n";
}
The Prima::noX11 module exports a single function "XOpenDisplay" into "Prima"
namespace, to connect to the X display explicitly. The display to be connected to is
$ENV{DISPLAY}, unless started otherwise on command line ( with --display option) or
with parameter to the "XOpenDisplay" function.
This technique may be useful to programs that use Prima imaging functionality and may
or may not use windowing capabilites.
X resources database
X11 provides XRDB, the X resource database, a keyed list of arbitrary string values stored
on the X server. Each key is a combination of names and classes of widgets, each in string
form. The key is constructed so the leftmost substring ( name or class ) corresponds to
the top-level item in the hierarchy, usually the application name or class. Although the
XRDB can be changed via native X API, it is rarely done by applications. Instead, the user
creates a file, usually named .Xdefaults, which contains the database in the string form.
The format of .Xdefaults directly reflects XRDB capabilities, one of the most important of
which is globbing, manifested via * ( star ) character. Using 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 ListBox class must have yellow background.
The application itself is responsible for parsing the strings and querying the XRDB.
Also, both class names and widget names, as well as database values are fully defined in
terms of the application. There are some guidelines though, for example, colors and fonts
best described in terms, native to the X server. Also, classes and names are
distinguished by the case: classes must begin with the upper register letter. Also, not
every character can be stored in the XRDB database ( space, for example, cannot) , and
therefore XRDB API automatically converts these to _ ( underscore ) characters.
Prima defines its all set of resources, divided in two parts: general toolkit settings and
per-widget settings. The general settings functionality is partially overloaded by
command-line arguments. Per-widget settings are fonts and colors, definable for each Prima
widget.
All of the general settings are applicable to the top-level item of widget hierarchy,
named after the application, and "Prima" class. Some of these, though, are needed to be
initialized before the application instance itself is created, so these can be accessed
via "Prima" class only, for example, "Prima.Visual". Some, on the contrary, may
occasionally overlap with per-widget syntax. In particular, one must vary not to mix
Prima.font: some-font
with
Prima*font: some-font
The former syntax is a general setting, and sets the default Prima font. The latter is a
per-widget assignment, and explicitly sets font to all Prima widgets, effectively ruining
the toolkit font inheritance scheme. The same is valid for an even more oppressive
*font: some-font
record.
The allowed per-widget settings are colors and font settings only ( see corresponding
sections ). It is an arguably useful feature to map all 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 enumeration of all properties for each widget takes
place.
All global settings have identical class and name, varied in the case of the first letter.
For example, to set "Submenudelay" value, one can do it either by
Prima.Submenudelay: 10
or
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, for all properties their names and class are given as
"PropetyClass.propertyname" index.
Fonts
Default fonts
Prima::Application defines set of "get_default_XXX_font" functions, where each returns
some user-selected font, to be displayed correspondingly in menu, message, window
captions, all other widgets, and finally a default font. While in other OS'es these are
indeed standard configurable user options, raw X11 doesn't define any. Nevertheless, as
the high-level code relies on these, 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. Default font for 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 "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, the default
"*-*-*-*-*-*-*-*-*-*-*-*-*-*-*" pattern, where each star character can be replaced by a
particular font property, as name, size, charset, and so on. To interactively select an
appropriate font, use standard "xfontsel" program from X11 distribution.
Note, that encoding part of the font is recommended to left unspecified, otherwise it may
clash with LANG environment variable, which is used by Prima font subsystem to determine
which font to select when no encoding is given. This advice, though, is correct only when
both LANG and encoding part of a desired font match. In order to force a particular font
encoding, the property "Prima.font" must contain one.
Alternatively, and/or to reduce X font traffic, one may set
"IgnoreEncodings.ignoreEncodings" property, which is a semicolon- separated list of
encodings Prima must not account. This feature has limited usability when for example
fonts in Asian encodings result in large font requests. Another drastic measure to
decrease font traffic is a boolean property "Noscaledfonts.noscaledfonts", which, if set
to 1, restricts the choice of fonts to the non-scalable fonts only.
Xft fonts
Recently, Prima was made to compile with Xft library, which contrary to core X font API,
can make use of client-side fonts. Plus, Xft offers appealing features as font
antialiasing, unicode, and arguably a better font syntax. The Xft font syntax is inherited
from "fontconfig" library and to be consulted from "man fonts-conf", but currently (
November 2003 ) basic font descriptions can be composed as follows:
Palatino-12
A font with name "Palatino" and size 12.
Arial-10:BI
A font with name "Arial", size 10, bold, italic. The "fontconfig" syntax allows more than
that, for example, arbitrary matrix transformations, but Prima can make use only of font
name, size, and style flags.
"--no-xft"
"--no-xft" command-line argument, and boolean "UseXFT.usexft" XRDB property can be
used to disable use of the Xft library.
"--no-core-fonts"
Disables all X11 core fonts, except "fixed" fonts. The "fixed" font is selected for
the same reasons that 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 a 'classic' X look.
"--font-priority"
Can be set to either "xft" or "core", to select a 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 Xft antialiasing.
Colors
XRDB conventions
X traditionally contains a color names database, usually a text file named rgb.txt. Check
your X manual where exactly this file resides and what is its format. The idea behind it
is that users can benefit from portable literal color names, with color values
transparently adjustable to displays capabilities. Thus, it is customary to write
color: green
for many applications, and these in turn call "XParseColor" to convert strings into RGB
values.
Prima is no exception to the scheme. Each widget can be assigned eight color properties:
"color", "hiliteBackColor", "disabledColor", "dark3DColor" "backColor", "hiliteColor",
"disabledBackColor", "light3DColor" by their name:
Prima.backColor: #cccccc
Additionally, set of command-line arguments allows overriding default values for these:
• "--fg" - color
• "--bg" - backColor
• "--hilite-fg" - hiliteColor
• "--hilite-bg" - hiliteBackColor
• "--disabled-fg" - disabledColor
• "--disabled-bg" - disabledBackColor
• "--light" - light3DColor
• "--dark" - dark3DColor
Visuals
X protocol works with explicitly defined pixel values only. A pixel value, maximum 32-bit
value, represents a color in a display. There are two different color coding schemes -
direct color and indexed color. The direct color-coded pixel value can unambiguously be
converted into a RGB-value, without any external information. The indexed-color scheme
represents pixel value as an index in a palette, which resided on X server. Depending on
the color cell value of the palette, RGB color representation can be computed. A X display
can contain more than one palette, and allow ( or disallow ) modification of palette color
cells depending on a visual, the palette is attributed to.
A visual is a X server resource, containing representation of color coding scheme, color
bit depth, and modificability of the palette. X server can ( and usually does ) provide
more than one visual, as well as different bit depths. There are six classes of visuals
in X paradigm. In each, Prima behaves differently, also depending on display bit depth
available. In particular, color dithering can be used on displays with less than 12-bit
color depth. On displays with modifiable color palette, Prima can install its own values
in palettes, which may result in an effect known as display flashing. To switch to a non-
default visual, use "Prima.Visual" XRDB property or "--visual" command-line argument.
List of visuals can be produced interactively by standard "xdpyinfo" command from X
distribution, where each class of visual corresponds to one of six visual classes:
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 rarely
met.
GrayScale
Contains modifiable color palette, and 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 a 16-color EGA
mode. This visual is rarely met.
PseudoColor
All color cells are modifiable. Typically, 8-bit displays define this class for a
default visual. For both StaticColor and PseudoColor visuals dithering is always used,
although for "PseudoColor" Prima resorts to that only if X server cannot allocate
another color.
On "PseudoColor" and "GrayScale" Prima allocates a small set of colors, not used in
palette modifications. When a bitmap is to be exported via clipboard, or displayed in
menu, or sent to a window manager as an icon to be displayed, it is downgraded to
using these colors only, which are though guaranteedly to stay permanent through life
of the application.
TrueColor
Each pixel value is explicitly coded as RGB. Typical example 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 support this visual, and usually by default it is not set. Prima supports
this mode in exactly same way as TrueColor without additional features. During
testing, it appeared that non-default DirectColor visuals require explicit assignment
of each pixel used, which is inappropriate for color-rich images, and therefore Prima
refuses to work on a non-default DirectColor visual.
Images
As described in the previous section, X does not standardize pixel memory format for
TrueColor and "DirectColor" visuals, so there is a chance that Prima wouldn'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.
Prima supports shared memory image X extension, which speeds up image display for X
servers and clients running on same machine. The price for this is that if 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 *BSD.
The clipboard exchange of images is incompletely implemented, since Prima does not
accompany ( and neither reads ) COLORMAP, FOREGROUND, and BACKGROUND clipboard data, which
contains pixel RGB values for a paletted image. As a palliative, the clipboard-bound
images are downgraded to a safe set of colors, locked immutable either by X server or
Prima core.
On images in the clipboard: contrary to the 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.
Window managers
The original design of X protocol did not include the notion of a window manager, and
latter is was implemented as an ad-hoc patch, which results in race conditions when
configuring widgets. The extreme situation may well happen when even a non-top level
widget may be influenced by a window manager, when for example a top-level widget was
reparented into another widget, but the window manager is not aware or this yet.
The consequences of this, as well as programming guidances are described in
"Prima::Window". Here, we describe other aspects of interactions with WMs, as WM
protocols, hints, and properties.
Prima was tested with alternating success under the following window managers: mwm, kwin,
wmaker, fvwm, fvwm2, enlightment, sawfish, blackbox, 9wm, olvm, twm, and in no-WM
environment.
Protocols
Prima makes use of "WM_DELETE_WINDOW" and "WM_TAKE_FOCUS" protocols. While
"WM_DELETE_WINDOW" use is straightforward and needs no further attention, "WM_TAKE_FOCUS"
can be tricky, since X defines several of input modes for a widget, which behave
differently for each WM. In particular, 'focus follows pointer' gives pains under twm and
mwm, where navigation of drop-down combo boxes is greatly hindered by window manager. The
drop-down list is programmed so it is dismissed as soon 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 WM in a standard way, and,
as inter-client communication manual ( ICCCM ) allows, repeatedly misinterpreted by window
managers. Many ( wmaker, for example ) apply the coordinates given from the program not to
the top-level widget itself, but to its decoration. mwm defines list of accepted icon
sizes so these can be absurdly high, which adds confusion to a client who can create icon
of any size, but unable to determine the best one.
Non-standard properties
Prima tries to use WM-specific hints, known for two window managers: mwm and kwin. For
mwm ( Motif window manager ) Prima sets hints of decoration border width and icons only.
For kwin ( and probably to others, who wish to conform to specifications of
http://www.freedesktop.org/ ) Prima uses "NET_WM_STATE" property, in particular its
maximization and task-bar visibility hints.
Use of these explicitly contradicts ICCCM, and definitely may lead to bugs in future ( at
least with "NET_WM_STATE", since Motif interface can hardly expected to be changed ). To
disable the use of non-standard WM properties, "--icccm" command-line argument can be set.
Unicode
X does not support unicode, and number of patches were applied to X servers and clients to
make the situation change. Currently ( 2003 ) standard unicode practices are not emerged
yet, so Prima copes up with what ( in author's opinion ) is most promising: Xft and iconv
libraries.
Fonts
X11 supports 8-bit and 16-bit text string display, and neither can be used effectively to
display unicode strings. A "XCreateFontSet" technique, which combines several fonts under
one descriptor, or a similarly implemented technique is the only way to provide correct
unicode display.
Also, core font transfer protocol suffers from ineffective memory representation, which
creates latency when fonts with large span of glyphs is loaded. Such fonts, in still
uncommon though standard iso10646 encoding, are the only media to display multi-encoding
text without falling back to hacks similar to "XCreateFontSet".
These, and some other problems are efficiently solved by 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 iconv charset convertor library.
Input
Prima does not support extended input methods ( XIM etc ), primarily because the authors
are not acquainted with CIJK problem domain. Volunteers are welcome.
Clipboard
Prima supports UTF8 text in clipboard via "UTF8_STRING" transparently, although not by
default.
Prima::Application-> wantUnicodeInput(1)
is the easiest ( see Prima::Application ) way to initiate UTF8 clipboard text exchange.
Due to the fact that any application can take ownership over the clipboard at any time,
"open"/"close" brackets are not strictly respected in X11 implementation. Practically,
this means that when modern X11 clipboard daemons ( KDE klipper, for example ) interfere
with Prima clipboard, the results may not be consistent from the programmer's view, for
example, clipboard contains data after "clear" call, and the like. It must be noted though
that this behavior is expected by the users.
Other XRDB resources
Timeouts
Raw X11 provides no such GUI helpers as double-click event, cursor, or menu. Neither does
it provide the related time how often, for example, a cursor would blink. Therefore Prima
emulates these, but allows the user to reprogram the corresponding timeouts. Prima
recognizes the following properties, accessible either via application name or Prima class
key. All timeouts are integer values, representing number of milliseconds for the
corresponding timeout property.
Blinkinvisibletime.blinkinvisibletime: MSEC
Cursor stays invisible MSEC milliseconds.
Default value: 500
Blinkvisibletime.blinkvisibletime: MSEC
Cursor stays visible MSEC milliseconds.
Default value: 500
Clicktimeframe.clicktimeframe MSEC
If 'mouse down' and 'mouse up' events are follow in MSEC, 'mouse click' event is
synthesized.
Default value: 200
Doubleclicktimeframe.doubleclicktimeframe MSEC
If 'mouse click' and 'mouse down' events are follow in MSEC, 'mouse double click'
event is synthesized.
Default value: 200
Submenudelay.submenudelay MSEC
When the used clicks on a menu item, which points to a lower-level menu window, the
latter is displayed after MSEC milliseconds.
Default value: 200
Scrollfirst.scrollfirst MSEC
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 - 'first' and
'next' delay. These actions are not simulated within Prima core, and the corresponding
timeouts are merely advisable to the programmer. Prima widgets use it for automatic
scrolling, either by a scrollbar or by any other means. Also, "Prima::Button" in
"autoRepeat" mode uses these timeouts for emulation of a key press.
"Scrollfirst" is a 'first' timeout.
Default value: 200
Scrollnext.scrollnext MSEC
A timeout used for same reasons as "Scrollfirst", but after it is expired.
Default value: 50
Miscellaneous
Visual.visual: VISUAL_ID
Selects display visual by VISUAL_ID, which is usually has a form of "0x??". Various
visuals provide different color depth and access scheme. Some X stations have badly
chosen default visuals (for example, default IRIX workstation setup has 8-bit default
visual selected), so this property can be used to fix things. List of visuals,
supported by a X display can be produced interactively by standard "xdpyinfo" command
from X distribution.
Identical to "--visual" command-line argument.
See Color for more information.
Wheeldown.wheeldown BUTTON
BUTTON is a number of X mouse button event, treated as 'mouse wheel down' event.
Default value: 5 ( default values for wheeldown and wheelup are current de-facto most
popular settings ).
Wheelup.wheelup BUTTON
BUTTON is a number of X mouse button event, treated as 'mouse wheel up' event.
Default value: 4
Debugging
The famous 'use the source' call is highly actual with Prima. However, some debug
information comes compiled in, and can be activated by "--debug" command-line key.
Combination of letters to the key activates debug printouts of different subsystems:
• 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 X protocol synchronization (
at expense of operation slowdown though ) is activated with "--sync" command-line
argument, and can be used to ease the debugging.
AUTHOR
Dmitry Karasik, <dmitry@karasik.eu.org>.
SEE ALSO
Prima, Prima::gp-problems, Prima::Widget, Nye A, Xlib programming manual. O'Reilly &
Associates, 1995.