1pod::Prima::X11(3) User Contributed Perl Documentation pod::Prima::X11(3)
2
6 Prima::X11 - usage guide for X11 environment
7
9 This document describes subtle topics one must be aware when
10 programming or using Prima programs under X11.
11 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
17 "--help"
18 Prints the command-line arguments available and exits.
19 "--display"
21 Sets X display address in Xlib notation. If not set, standard Xlib
22 ( "XOpenDisplay(null)" ) behavior applies.
23 Example:
25 --display=:0.1
27 "--visual"
29 Sets X visual, to be used by default. Example:
30 --visual=0x23
32 "--sync"
34 Turn off X synchronization
35 "--bg", "--fg"
37 Set default background and foreground colors. Example:
38 --bg=BlanchedAlmond
40 "--font"
42 Sets default font. Example:
43 --font='adobe-helvetica-medium-r-*-*--*-120-*-*-*-*-*-*'
45 "--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 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 perl -MPrima::noX11
59 construct. Second, there is a technique to continue execution even
61 if connection to a X server failed:
62 use Prima::noX11;
64 use Prima;
65 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 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 This technique may be useful to programs that use Prima imaging
80 functionality and may or may not use windowing capabilites.
81
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 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 *.ListBox.backColor: yellow
98 The string above means that all widgets of ListBox class must have
100 yellow background.
101 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 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 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 Prima.font: some-font
126 with
128 Prima*font: some-font
130 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 *font: some-font
137 record.
139 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 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 Prima.Submenudelay: 10
152 or
154 Prima.submenudelay: 10
156 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
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 • font - Application::get_default_font
174 • caption_font - Application::get_caption_font. Used in "Prima::MDI".
176 • menu_font - Widget::get_default_menu_font. Default font for pull-
178 down and pop-up menus.
179 • msg_font - Application::get_message_font. Used in "Prima::MsgBox".
181 • widget_font - Widget::get_default_font.
183 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 Prima*Dialog.font: my-fancy-dialog-font
191 Prima.FontDialog.font: some-conservative-font
192 By default, Prima font is 12.Helvetica .
194 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 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 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 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 Palatino-12
226 A font with name "Palatino" and size 12.
228 Arial-10:BI
230 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 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 Xft.maxglyphmemory: 10485760
242 (f.ex. for 10M per program cache) to the input for your xrdb.
244 "--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 "--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 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 "--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 Default value: "xft" ( if compiled in ), "core" otherwise.
263 "--no-aa"
265 If set, turns off Xft antialiasing.
266
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 color: green
276 for many applications, and these in turn call "XParseColor" to convert
278 strings into RGB values.
279 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 Prima.backColor: #cccccc
286 Additionally, set of command-line arguments allows overriding default
288 values for these:
289 • "--fg" - color
291 • "--bg" - backColor
293 • "--hilite-fg" - hiliteColor
295 • "--hilite-bg" - hiliteBackColor
297 • "--disabled-fg" - disabledColor
299 • "--disabled-bg" - disabledBackColor
301 • "--light" - light3DColor
303 • "--dark" - dark3DColor
305 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 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 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 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 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 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 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 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 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
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 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 To disable shared memory with images, use "--no-shmem" switch in
389 command-line arguments.
390 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 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
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 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 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 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 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 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 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
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 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 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 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 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 Clipboard
486 Prima supports UTF8 text in clipboard via "UTF8_STRING" transparently,
487 although not by default.
488 Prima::Application-> wantUnicodeInput(1)
490 is the easiest ( see Prima::Application ) way to initiate UTF8
492 clipboard text exchange.
493 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
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 Blinkinvisibletime.blinkinvisibletime: MSEC
514 Cursor stays invisible MSEC milliseconds.
515 Default value: 500
517 Blinkvisibletime.blinkvisibletime: MSEC
519 Cursor stays visible MSEC milliseconds.
520 Default value: 500
522 Clicktimeframe.clicktimeframe MSEC
524 If 'mouse down' and 'mouse up' events are follow in MSEC, 'mouse
525 click' event is synthesized.
526 Default value: 200
528 Doubleclicktimeframe.doubleclicktimeframe MSEC
530 If 'mouse click' and 'mouse down' events are follow in MSEC, 'mouse
531 double click' event is synthesized.
532 Default value: 200
534 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 Default value: 200
540 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 "Scrollfirst" is a 'first' timeout.
552 Default value: 200
554 Scrollnext.scrollnext MSEC
556 A timeout used for same reasons as "Scrollfirst", but after it is
557 expired.
558 Default value: 50
560 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 Identical to "--visual" command-line argument.
572 See Color for more information.
574 Wheeldown.wheeldown BUTTON
576 BUTTON is a number of X mouse button event, treated as 'mouse wheel
577 down' event.
578 Default value: 5 ( default values for wheeldown and wheelup are
580 current de-facto most popular settings ).
581 Wheelup.wheelup BUTTON
583 BUTTON is a number of X mouse button event, treated as 'mouse wheel
584 up' event.
585 Default value: 4
587
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 • C - clipboard
595 • E - events subsystem
597 • F - fonts
599 • M - miscellaneous debug info
601 • P - palettes and colors
603 • X - XRDB
605 • A - all of the above
607 Example:
609 --debug=xf
611 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 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 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 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
635 Dmitry Karasik, <dmitry@karasik.eu.org>.
636
638 Prima, Prima::gp-problems, Prima::Widget, Nye A, Xlib programming
639 manual. O'Reilly & Associates, 1995.
640perl v5.34.1 2022-04-20 pod::Prima::X11(3)