1pod::Prima::X11(3)    User Contributed Perl Documentation   pod::Prima::X11(3)
2
3
4

NAME

6       Prima::X11 - usage guide for X11 environment
7

DESCRIPTION

9       This document describes subtle topics one must be aware when
10       programming or using Prima programs under X11.
11
12       The document covers various aspects of the toolkit and their
13       implementation details with guidelines of the expected use. Also,
14       standard X11 user-level and programming techniques are visited.
15

Basic command-line switches

17       "--help"
18           Prints the command-line arguments available and exits.
19
20       "--display"
21           Sets X display address in Xlib notation. If not set, standard Xlib
22           ( "XOpenDisplay(null)" ) behavior applies.
23
24           Example:
25
26              --display=:0.1
27
28       "--visual"
29           Sets X visual, to be used by default. Example:
30
31              --visual=0x23
32
33       "--sync"
34           Turn off X synchronization
35
36       "--bg", "--fg"
37           Set default background and foreground colors. Example:
38
39             --bg=BlanchedAlmond
40
41       "--font"
42           Sets default font. Example:
43
44              --font='adobe-helvetica-medium-r-*-*--*-120-*-*-*-*-*-*'
45
46       "--no-x11"
47           Runs Prima without X11 display initialized. This switch can be used
48           for programs that use only OS-independent parts of Prima, such as
49           image subsystem or PostScript generator, in environments where X is
50           not present, for example, a CGI script.  Obviously, any attempt to
51           create instance of "Prima::Application" or otherwise access
52           X-depended code under such conditions causes the program to abort.
53
54           There are alternatives to use the command switch. First, there is
55           module "Prima::noX11" for the same purpose but more convenient to
56           use as
57
58              perl -MPrima::noX11
59
60           construct. Second, there is a technique to continue execution even
61           if connection to a X server failed:
62
63              use Prima::noX11;
64              use Prima;
65
66              my $error = Prima::XOpenDisplay();
67              if ( defined $error) {
68                   print "not connected to display: $error\n";
69              } else {
70                   print "connected to display\n";
71              }
72
73           The Prima::noX11 module exports a single function "XOpenDisplay"
74           into "Prima" namespace, to connect to the X display explicitly. The
75           display to be connected to is $ENV{DISPLAY}, unless started
76           otherwise on command line ( with --display option) or with
77           parameter to the "XOpenDisplay" function.
78
79           This technique may be useful to programs that use Prima imaging
80           functionality and may or may not use windowing capabilites.
81

X resources database

83       X11 provides XRDB, the X resource database, a keyed list of arbitrary
84       string values stored on the X server. Each key is a combination of
85       names and classes of widgets, each in string form. The key is
86       constructed so the leftmost substring ( name or class ) corresponds to
87       the top-level item in the hierarchy, usually the application name or
88       class. Although the XRDB can be changed via native X API, it is rarely
89       done by applications. Instead, the user creates a file, usually named
90       .Xdefaults, which contains the database in the string form.
91
92       The format of .Xdefaults directly reflects XRDB capabilities, one of
93       the most important of which is globbing, manifested via * ( star )
94       character. Using globbing, the user can set up a property value that
95       corresponds to multiple targets:
96
97          *.ListBox.backColor: yellow
98
99       The string above means that all widgets of ListBox class must have
100       yellow background.
101
102       The application itself is responsible for parsing the strings and
103       querying the XRDB.  Also, both class names and widget names, as well as
104       database values are fully defined in terms of the application. There
105       are some guidelines though, for example, colors and fonts best
106       described in terms, native to the X server.  Also, classes and names
107       are distinguished by the case: classes must begin with the upper
108       register letter. Also, not every character can be stored in the XRDB
109       database ( space, for example, cannot) , and therefore XRDB API
110       automatically converts these to _ ( underscore ) characters.
111
112       Prima defines its all set of resources, divided in two parts: general
113       toolkit settings and per-widget settings. The general settings
114       functionality is partially overloaded by command-line arguments. Per-
115       widget settings are fonts and colors, definable for each Prima widget.
116
117       All of the general settings are applicable to the top-level item of
118       widget hierarchy, named after the application, and "Prima" class. Some
119       of these, though, are needed to be initialized before the application
120       instance itself is created, so these can be accessed via "Prima" class
121       only, for example, "Prima.Visual".  Some, on the contrary, may
122       occasionally overlap with per-widget syntax.  In particular, one must
123       vary not to mix
124
125          Prima.font: some-font
126
127       with
128
129          Prima*font: some-font
130
131       The former syntax is a general setting, and sets the default Prima
132       font.  The latter is a per-widget assignment, and explicitly sets font
133       to all Prima widgets, effectively ruining the toolkit font inheritance
134       scheme. The same is valid for an even more oppressive
135
136          *font: some-font
137
138       record.
139
140       The allowed per-widget settings are colors and font settings only ( see
141       corresponding sections ). It is an arguably useful feature to map all
142       widget properties onto XRDB, but Prima does not implement this,
143       primarily because no one asked for it, and also because this creates
144       unnecessary latency when enumeration of all properties for each widget
145       takes place.
146
147       All global settings have identical class and name, varied in the case
148       of the first letter. For example, to set "Submenudelay" value, one can
149       do it either by
150
151          Prima.Submenudelay: 10
152
153       or
154
155          Prima.submenudelay: 10
156
157       syntax. Despite that these calls are different, in a way that one
158       reaches for the whole class and another for the name, for the majority
159       of these properties it does not matter. To avoid confusion, for all
160       properties their names and class are given as
161       "PropetyClass.propertyname" index.
162

Fonts

164   Default fonts
165       Prima::Application defines set of "get_default_XXX_font" functions,
166       where each returns some user-selected font, to be displayed
167       correspondingly in menu, message, window captions, all other widgets,
168       and finally a default font. While in other OS'es these are indeed
169       standard configurable user options, raw X11 doesn't define any.
170       Nevertheless, as the high-level code relies on these, corresponding
171       resources are defined. These are:
172
173       •   font - Application::get_default_font
174
175       •   caption_font - Application::get_caption_font. Used in "Prima::MDI".
176
177       •   menu_font - Widget::get_default_menu_font. Default font for pull-
178           down and pop-up menus.
179
180       •   msg_font - Application::get_message_font. Used in "Prima::MsgBox".
181
182       •   widget_font - Widget::get_default_font.
183
184       All of the global font properties can only be set via "Prima" class, no
185       application name is recognized. Also, these properties are identical to
186       "--font", "--menu-font", "--caption-font", "--msg-font", and
187       "--widget-font" command-line arguments.  The per-widget properties are
188       "font" and "popupFont", of class "Font", settable via XRDB only:
189
190          Prima*Dialog.font: my-fancy-dialog-font
191          Prima.FontDialog.font: some-conservative-font
192
193       By default, Prima font is 12.Helvetica .
194
195   X core fonts
196       The values of the font entries are standard XLFD strings, the default
197       "*-*-*-*-*-*-*-*-*-*-*-*-*-*-*" pattern, where each star character can
198       be replaced by a particular font property, as name, size, charset, and
199       so on. To interactively select an appropriate font, use standard
200       "xfontsel" program from X11 distribution.
201
202       Note, that encoding part of the font is recommended to left
203       unspecified, otherwise it may clash with LANG environment variable,
204       which is used by Prima font subsystem to determine which font to select
205       when no encoding is given.  This advice, though, is correct only when
206       both LANG and encoding part of a desired font match. In order to force
207       a particular font encoding, the property "Prima.font" must contain one.
208
209       Alternatively, and/or to reduce X font traffic, one may set
210       "IgnoreEncodings.ignoreEncodings" property, which is a semicolon-
211       separated list of encodings Prima must not account. This feature has
212       limited usability when for example fonts in Asian encodings result in
213       large font requests.  Another drastic measure to decrease font traffic
214       is a boolean property "Noscaledfonts.noscaledfonts", which, if set to
215       1, restricts the choice of fonts to the non-scalable fonts only.
216
217   Xft fonts
218       Prima can compile with Xft library, which contrary to core X font API,
219       can make use of client-side fonts. Plus, Xft offers appealing features
220       as font antialiasing, unicode, and arguably a better font syntax. The
221       Xft font syntax is inherited from "fontconfig" library and to be
222       consulted from "man fonts-conf", but currently ( November 2003 ) basic
223       font descriptions can be composed as follows:
224
225          Palatino-12
226
227       A font with name "Palatino" and size 12.
228
229          Arial-10:BI
230
231       A font with name "Arial", size 10, bold, italic. The "fontconfig"
232       syntax allows more than that, for example, arbitrary matrix
233       transformations, but Prima can make use only of font name, size, and
234       style flags.
235
236       The XFT library does internal memory management that is not necessary
237       optimal for text with large amount of glyphs, f.ex. chinese. If display
238       of these text is slow, try to increase memory for glyph caching by
239       setting
240
241         Xft.maxglyphmemory: 10485760
242
243       (f.ex. for 10M per program cache) to the input for your xrdb.
244
245       "--no-xft"
246           "--no-xft" command-line argument, and boolean "UseXFT.usexft" XRDB
247           property can be used to disable use of the Xft library.
248
249       "--no-core-fonts"
250           Disables all X11 core fonts, except "fixed" fonts. The "fixed" font
251           is selected for the same reasons that X server is designed to
252           provide at least one font, which usually is "fixed".
253
254           It is valid to combine "--no-core-fonts" and "--no-xft". Moreover,
255           adding "--noscaled" to these gives Prima programs a 'classic' X
256           look.
257
258       "--font-priority"
259           Can be set to either "xft" or "core", to select a font provider
260           mechanism to match unknown or incompletely specified fonts against.
261
262           Default value: "xft" ( if compiled in ), "core" otherwise.
263
264       "--no-aa"
265           If set, turns off Xft antialiasing.
266

Colors

268   XRDB conventions
269       X traditionally contains a color names database, usually a text file
270       named rgb.txt.  Check your X manual where exactly this file resides and
271       what is its format.  The idea behind it is that users can benefit from
272       portable literal color names, with color values transparently
273       adjustable to displays capabilities.  Thus, it is customary to write
274
275          color: green
276
277       for many applications, and these in turn call "XParseColor" to convert
278       strings into RGB values.
279
280       Prima is no exception to the scheme. Each widget can be assigned eight
281       color properties: "color", "hiliteBackColor", "disabledColor",
282       "dark3DColor" "backColor", "hiliteColor", "disabledBackColor",
283       "light3DColor" by their name:
284
285          Prima.backColor: #cccccc
286
287       Additionally, set of command-line arguments allows overriding default
288       values for these:
289
290       •   "--fg" - color
291
292       •   "--bg" - backColor
293
294       •   "--hilite-fg" - hiliteColor
295
296       •   "--hilite-bg" - hiliteBackColor
297
298       •   "--disabled-fg" - disabledColor
299
300       •   "--disabled-bg" - disabledBackColor
301
302       •   "--light" - light3DColor
303
304       •   "--dark" - dark3DColor
305
306   Visuals
307       X protocol works with explicitly defined pixel values only.  A pixel
308       value, maximum 32-bit value, represents a color in a display. There are
309       two different color coding schemes - direct color and indexed color.
310       The direct color-coded pixel value can unambiguously be converted into
311       a RGB-value, without any external information.  The indexed-color
312       scheme represents pixel value as an index in a palette, which resided
313       on X server. Depending on the color cell value of the palette, RGB
314       color representation can be computed. A X display can contain more than
315       one palette, and allow ( or disallow ) modification of palette color
316       cells depending on a visual, the palette is attributed to.
317
318       A visual is a X server resource, containing representation of color
319       coding scheme, color bit depth, and modificability of the palette. X
320       server can ( and usually does ) provide more than one visual, as well
321       as different bit depths.  There are six classes of visuals in X
322       paradigm. In each, Prima behaves differently, also depending on display
323       bit depth available.  In particular, color dithering can be used on
324       displays with less than 12-bit color depth. On displays with modifiable
325       color palette, Prima can install its own values in palettes, which may
326       result in an effect known as display flashing. To switch to a non-
327       default visual, use "Prima.Visual" XRDB property or "--visual" command-
328       line argument.  List of visuals can be produced interactively by
329       standard "xdpyinfo" command from X distribution, where each class of
330       visual corresponds to one of six visual classes:
331
332       StaticGray
333           All color cells are read-only, and contain monochrome values only.
334           A typical example is a two-color, black-and-white monochrome
335           display.  This visual is extremely rarely met.
336
337       GrayScale
338           Contains modifiable color palette, and capable of displaying
339           monochrome values only. Theoretically, any paletted display on a
340           monochrome monitor can be treated as a GrayScale visual. For both
341           GrayScale and StaticGray visuals Prima resorts to dithering if it
342           cannot get at least 32 evenly spaced gray values from black to
343           white.
344
345       StaticColor
346           All color cells are read-only.  A typical example is a PC display
347           in a 16-color EGA mode.  This visual is rarely met.
348
349       PseudoColor
350           All color cells are modifiable. Typically, 8-bit displays define
351           this class for a default visual. For both StaticColor and
352           PseudoColor visuals dithering is always used, although for
353           "PseudoColor" Prima resorts to that only if X server cannot
354           allocate another color.
355
356           On "PseudoColor" and "GrayScale" Prima allocates a small set of
357           colors, not used in palette modifications. When a bitmap is to be
358           exported via clipboard, or displayed in menu, or sent to a window
359           manager as an icon to be displayed, it is downgraded to using these
360           colors only, which are though guaranteedly to stay permanent
361           through life of the application.
362
363       TrueColor
364           Each pixel value is explicitly coded as RGB. Typical example are
365           16, 24, or 32-bit display modes. This visual class is the best in
366           terms of visual quality.
367
368       DirectColor
369           Same as TrueColor, but additionally each pixel value can be
370           reprogrammed.  Not all hardware support this visual, and usually by
371           default it is not set.  Prima supports this mode in exactly same
372           way as TrueColor without additional features.
373

Images

375       As described in the previous section, X does not standardize pixel
376       memory format for TrueColor and DirectColor visuals, so there is a
377       chance that Prima wouldn't work on some bizarre hardware. Currently,
378       Prima knows how to compose pixels of 15, 16, 24, and 32 bit depth, of
379       contiguous ( not interspersed ) red-green-blue memory layout. Any other
380       pixel memory layout causes Prima to fail.
381
382       Prima supports shared memory image X extension, which speeds up image
383       display for X servers and clients running on same machine. The price
384       for this is that if Prima program aborts, the shared memory will never
385       be returned to the OS.  To remove the leftover segments, use your OS
386       facilities, for example, "ipcrm" on *BSD.
387
388       To disable shared memory with images, use "--no-shmem" switch in
389       command-line arguments.
390
391       The clipboard exchange of images is incompletely implemented, since
392       Prima does not accompany ( and neither reads ) COLORMAP, FOREGROUND,
393       and BACKGROUND clipboard data, which contains pixel RGB values for a
394       paletted image. As a palliative, the clipboard-bound images are
395       downgraded to a safe set of colors, locked immutable either by X server
396       or Prima core.
397
398       On images in the clipboard: contrary to the text in the clipboard,
399       which can be used several times, images seemingly cannot. The Bitmap or
400       Pixmap descriptor, stored in the clipboard, is rendered invalid after
401       it has been read once.
402

Window managers

404       The original design of X protocol did not include the notion of a
405       window manager, and latter is was implemented as an ad-hoc patch, which
406       results in race conditions when configuring widgets. The extreme
407       situation may well happen when even a non-top level widget may be
408       influenced by a window manager, when for example a top-level widget was
409       reparented into another widget, but the window manager is not aware or
410       this yet.
411
412       The consequences of this, as well as programming guidances are
413       described in "Prima::Window". Here, we describe other aspects of
414       interactions with WMs, as WM protocols, hints, and properties.
415
416       Prima was tested with alternating success under the following window
417       managers: mwm, kwin, wmaker, fvwm, fvwm2, enlightment, sawfish,
418       blackbox, 9wm, olvm, twm, and in no-WM environment.
419
420   Protocols
421       Prima makes use of "WM_DELETE_WINDOW" and "WM_TAKE_FOCUS" protocols.
422       While "WM_DELETE_WINDOW" use is straightforward and needs no further
423       attention, "WM_TAKE_FOCUS" can be tricky, since X defines several of
424       input modes for a widget, which behave differently for each WM.  In
425       particular, 'focus follows pointer' gives pains under twm and mwm,
426       where navigation of drop-down combo boxes is greatly hindered by window
427       manager. The drop-down list is programmed so it is dismissed as soon
428       its focus is gone; these window managers withdraw focus even if the
429       pointer is over the focused widget's border.
430
431   Hints
432       Size, position, icons, and other standard X hints are passed to WM in a
433       standard way, and, as inter-client communication manual ( ICCCM )
434       allows, repeatedly misinterpreted by window managers. Many ( wmaker,
435       for example ) apply the coordinates given from the program not to the
436       top-level widget itself, but to its decoration.  mwm defines list of
437       accepted icon sizes so these can be absurdly high, which adds confusion
438       to a client who can create icon of any size, but unable to determine
439       the best one.
440
441   Non-standard properties
442       Prima tries to use WM-specific hints, known for two window managers:
443       mwm and kwin.  For mwm ( Motif window manager ) Prima sets hints of
444       decoration border width and icons only. For kwin ( and probably to
445       others, who wish to conform to specifications of
446       http://www.freedesktop.org/ ) Prima uses "NET_WM_STATE" property, in
447       particular its maximization and task-bar visibility hints.
448
449       Use of these explicitly contradicts ICCCM, and definitely may lead to
450       bugs in future ( at least with "NET_WM_STATE", since Motif interface
451       can hardly expected to be changed ).  To disable the use of non-
452       standard WM properties, "--icccm" command-line argument can be set.
453

Unicode

455       X does not support unicode, and number of patches were applied to X
456       servers and clients to make the situation change. Currently ( 2003 )
457       standard unicode practices are not emerged yet, so Prima copes up with
458       what ( in author's opinion ) is most promising: Xft and iconv
459       libraries.
460
461   Fonts
462       X11 supports 8-bit and 16-bit text string display, and neither can be
463       used effectively to display unicode strings. A "XCreateFontSet"
464       technique, which combines several fonts under one descriptor, or a
465       similarly implemented technique is the only way to provide correct
466       unicode display.
467
468       Also, core font transfer protocol suffers from ineffective memory
469       representation, which creates latency when fonts with large span of
470       glyphs is loaded. Such fonts, in still uncommon though standard
471       iso10646 encoding, are the only media to display multi-encoding text
472       without falling back to hacks similar to "XCreateFontSet".
473
474       These, and some other problems are efficiently solved by Xft library, a
475       superset of X core font functionality. Xft features Level 1 ( November
476       2003 ) unicode display and supports 32-bit text strings as well as
477       UTF8-coded strings.  Xft does not operate with charset encodings, and
478       these are implemented in Prima using iconv charset convertor library.
479
480   Input
481       Prima does not support extended input methods ( XIM etc ), primarily
482       because the authors are not acquainted with CIJK problem domain.
483       Volunteers are welcome.
484
485   Clipboard
486       Prima supports UTF8 text in clipboard via "UTF8_STRING" transparently,
487       although not by default.
488
489          Prima::Application-> wantUnicodeInput(1)
490
491       is the easiest ( see Prima::Application ) way to initiate UTF8
492       clipboard text exchange.
493
494       Due to the fact that any application can take ownership over the
495       clipboard at any time, "open"/"close" brackets are not strictly
496       respected in X11 implementation. Practically, this means that when
497       modern X11 clipboard daemons ( KDE klipper, for example ) interfere
498       with Prima clipboard, the results may not be consistent from the
499       programmer's view, for example, clipboard contains data after "clear"
500       call, and the like. It must be noted though that this behavior is
501       expected by the users.
502

Other XRDB resources

504   Timeouts
505       Raw X11 provides no such GUI helpers as double-click event, cursor, or
506       menu.  Neither does it provide the related time how often, for example,
507       a cursor would blink. Therefore Prima emulates these, but allows the
508       user to reprogram the corresponding timeouts. Prima recognizes the
509       following properties, accessible either via application name or Prima
510       class key. All timeouts are integer values, representing number of
511       milliseconds for the corresponding timeout property.
512
513       Blinkinvisibletime.blinkinvisibletime: MSEC
514           Cursor stays invisible MSEC milliseconds.
515
516           Default value: 500
517
518       Blinkvisibletime.blinkvisibletime: MSEC
519           Cursor stays visible MSEC milliseconds.
520
521           Default value: 500
522
523       Clicktimeframe.clicktimeframe MSEC
524           If 'mouse down' and 'mouse up' events are follow in MSEC, 'mouse
525           click' event is synthesized.
526
527           Default value: 200
528
529       Doubleclicktimeframe.doubleclicktimeframe MSEC
530           If 'mouse click' and 'mouse down' events are follow in MSEC, 'mouse
531           double click' event is synthesized.
532
533           Default value: 200
534
535       Submenudelay.submenudelay MSEC
536           When the used clicks on a menu item, which points to a lower-level
537           menu window, the latter is displayed after MSEC milliseconds.
538
539           Default value: 200
540
541       Scrollfirst.scrollfirst MSEC
542           When an auto-repetitive action, similar to keystroke events
543           resulting from a long key press on the keyboard, is to be
544           simulated, two timeout values are used - 'first' and 'next' delay.
545           These actions are not simulated within Prima core, and the
546           corresponding timeouts are merely advisable to the programmer.
547           Prima widgets use it for automatic scrolling, either by a scrollbar
548           or by any other means.  Also, "Prima::Button" in "autoRepeat" mode
549           uses these timeouts for emulation of a key press.
550
551           "Scrollfirst" is a 'first' timeout.
552
553           Default value: 200
554
555       Scrollnext.scrollnext MSEC
556           A timeout used for same reasons as "Scrollfirst", but after it is
557           expired.
558
559           Default value: 50
560
561   Miscellaneous
562       Visual.visual: VISUAL_ID
563           Selects display visual by VISUAL_ID, which is usually has a form of
564           "0x??".  Various visuals provide different color depth and access
565           scheme. Some X stations have badly chosen default visuals (for
566           example, default IRIX workstation setup has 8-bit default visual
567           selected), so this property can be used to fix things. List of
568           visuals, supported by a X display can be produced interactively by
569           standard "xdpyinfo" command from X distribution.
570
571           Identical to "--visual" command-line argument.
572
573           See Color for more information.
574
575       Wheeldown.wheeldown BUTTON
576           BUTTON is a number of X mouse button event, treated as 'mouse wheel
577           down' event.
578
579           Default value: 5 ( default values for wheeldown and wheelup are
580           current de-facto most popular settings ).
581
582       Wheelup.wheelup BUTTON
583           BUTTON is a number of X mouse button event, treated as 'mouse wheel
584           up' event.
585
586           Default value: 4
587

Debugging

589       The famous 'use the source' call is highly actual with Prima. However,
590       some debug information comes compiled in, and can be activated by
591       "--debug" command-line key. Combination of letters to the key activates
592       debug printouts of different subsystems:
593
594       •   C - clipboard
595
596       •   E - events subsystem
597
598       •   F - fonts
599
600       •   M - miscellaneous debug info
601
602       •   P - palettes and colors
603
604       •   X - XRDB
605
606       •   A - all of the above
607
608       Example:
609
610          --debug=xf
611
612       Also, the built-in X API "XSynchronize" call, which enables X protocol
613       synchronization ( at expense of operation slowdown though ) is
614       activated with "--sync" command-line argument, and can be used to ease
615       the debugging.
616
617   GTK
618       Prima can be compiled with GTK, and can use its colos and font scheme,
619       and GTK file dialogs. This can be disabled with "--no-gtk" command line
620       switch.
621
622       On MacOSX, GTK usually comes with Quartz implementation, which means
623       that Prima will get into problems with remote X11 connections. Prima
624       tries to detect this condition, but if trouble persists, please use
625       "--no-gtk" switch (and please file a bug report so this can be fixed,
626       too).
627
628   Quartz
629       Prima can be compiled with Cocoa library on MacOSX, that gives access
630       to screen scraping functionality of Application.get_image, that is
631       otherwise is non-functional with XQuartz. To disable it, use
632       "--no-quartz" runtime switch.
633

AUTHOR

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

SEE ALSO

638       Prima, Prima::gp-problems, Prima::Widget, Nye A, Xlib programming
639       manual. O'Reilly & Associates, 1995.
640
641
642
643perl v5.34.0                      2021-07-22                pod::Prima::X11(3)
Impressum