Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages


home | help
pod::Prima::X11(3)    User Contributed Perl Documentation   pod::Prima::X11(3)

       Prima::X11 - usage guide	for X11	environment

       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
	   Prints the command-line arguments available and exits.

	   Sets	X display address in Xlib notation. If not set,	standard Xlib
	   ( "XOpenDisplay(null)" ) behavior applies.



	   Sets	X visual, to be	used by	default. Example:


	   Turn	off X synchronization

       "--bg", "--fg"
	   Set default background and foreground colors. Example:


	   Sets	default	font. Example:


	   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


	  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


       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


	  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.

   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:

       o   font	- Application::get_default_font

       o   caption_font	- Application::get_caption_font. Used in "Prima::MDI".

       o   menu_font - Widget::get_default_menu_font. Default font for pull-
	   down	and pop-up menus.

       o   msg_font - Application::get_message_font. Used in "Prima::MsgBox".

       o   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
       Prima can 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:


       A font with name	"Palatino" and size 12.


       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.

       The XFT library does internal memory management that is not necessary
       optimal for text	with large amount of glyphs, f.ex. chinese. If display
       of these	text is	slow, try to increase memory for glyph caching by

	 Xft.maxglyphmemory: 10485760

       (f.ex. for 10M per program cache) to the	input for your xrdb.

	   "--no-xft" command-line argument, and boolean "UseXFT.usexft" XRDB
	   property can	be used	to disable use of the Xft library.

	   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

	   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.

	   If set, turns off Xft antialiasing.

   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:

       o   "--fg" - color

       o   "--bg" - backColor

       o   "--hilite-fg" - hiliteColor

       o   "--hilite-bg" - hiliteBackColor

       o   "--disabled-fg" - disabledColor

       o   "--disabled-bg" - disabledBackColor

       o   "--light" - light3DColor

       o   "--dark" - dark3DColor

       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:

	   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.

	   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

	   All color cells are read-only.  A typical example is	a PC display
	   in a	16-color EGA mode.  This visual	is rarely met.

	   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.

	   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.

	   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.

       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.

       To disable shared memory	with images, use "--no-shmem" switch in
       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 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.

       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.

       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 ) 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.

       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

       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.

       Prima does not support extended input methods ( XIM etc ), primarily
       because the authors are not acquainted with CIJK	problem	domain.
       Volunteers are welcome.

       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
       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

	   Default value: 50

       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

       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:

       o   C - clipboard

       o   E - events subsystem

       o   F - fonts

       o   M - miscellaneous debug info

       o   P - palettes	and colors

       o   X - XRDB

       o   A - all of the above



       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.

       Prima can be compiled with GTK, and can use its colos and font scheme,
       and GTK file dialogs. This can be disabled with "--no-gtk" command line

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

       Prima can be compiled with Cocoa	library	on MacOSX, that	gives access
       to screen scraping functionality	of Application.get_image, that is
       otherwise is non-functional with	XQuartz. To disable it,	use
       "--no-quartz" runtime switch.

       Dmitry Karasik, <>.

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

perl v5.32.1			  2020-07-08		    pod::Prima::X11(3)

NAME | DESCRIPTION | Basic command-line switches | X resources database | Fonts | Colors | Images | Window managers | Unicode | Other XRDB resources | Debugging | AUTHOR | SEE ALSO

Want to link to this manual page? Use this URL:

home | help