=head1 NAME

Prima::X11 - usage guide for the X11 environment

=head1 DESCRIPTION

This document describes subtle topics one must be aware of when programming or
using Prima programs under X11.  The document covers various aspects of the
toolkit and its implementation details with the guidelines of the expected use.
Also, some of the X11 programming techniques are visited.

=head1 Basic command-line switches

=over

=item C<--help>

Prints the available command-line arguments and exits

=item C<--display>

Sets the X display address in the Xlib notation. If not set, the standard Xlib
( C<XOpenDisplay(null)> ) behavior applies.

Example:

   --display=:0.1

=item C<--visual>

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

   --visual=0x23

=item C<--sync>

Turn on the X synchronization

=item C<--bg>, C<--fg>

Set the default background and foreground colors. Example:

  --bg=BlanchedAlmond

=item C<--font>

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

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

=item C<--no-x11>

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

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

   perl -MPrima::noX11

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

   use Prima::noX11;
   use Prima;

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

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

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

=back

=head1 The X11 resources database

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

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

   *.ListBox.backColor: yellow

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

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

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

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

   Prima*font: myfont

instead of

   Prima.font: myfont

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

   *font: myfont

record.

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

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

   Prima.Submenudelay: 10

or by the

   Prima.submenudelay: 10

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

=head1 Fonts

=head2 Default fonts

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

=over

=item *

font - Application::get_default_font

=item *

caption_font - Application::get_caption_font. Used in C<Prima::MDI>.

=item *

menu_font - Widget::get_default_menu_font. The default font for the pull-down and
pop-up menus.

=item *

msg_font - Application::get_message_font. Used in C<Prima::MsgBox>.

=item *

widget_font - Widget::get_default_font.

=back

All of the global font properties can only be set via the C<Prima> class, no
application name is recognized. Also, these properties are identical to
C<--font>, C<--menu-font>, C<--caption-font>, C<--msg-font>, and
C<--widget-font> command-line arguments.  The per-widget properties are C<font>
and C<popupFont>, of class C<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 .

=head2 X core fonts

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

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

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

=head2 Xft fonts

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

   Palatino-12

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

   Arial-10:BI

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

=over

=item C<--no-xft>

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

=item C<--no-core-fonts>

Disables all X11 core fonts, except the C<fixed> font. The C<fixed>
font is selected for the same reasons that the X server is designed
to provide at least one font, which usually is C<fixed>.

It is valid to combine C<--no-core-fonts> and C<--no-xft>. Moreover, adding
C<--noscaled> to these gives Prima programs the very classic X look.

=item C<--font-priority>

Can be set to either C<xft> or C<core>, to select the font provider mechanism
to match unknown or incompletely specified fonts against.

Default value: C<xft> ( if compiled in ), C<core> otherwise.

=item C<--no-aa>

If set, turns off the Xft font antialiasing.

=back

=head1 Colors

=head2 XRDB conventions

The X11 is traditionally shipped with the color names database, usually a text
file named F<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 display
capabilities.  Thus, it is customary to write

   color: green

for many applications, and these in turn call the C<XParseColor> function to
convert strings into RGB values.

Prima can also support this functionality. Each widget can assign eight color
properties: C<color>, C<hiliteBackColor>, C<disabledColor>, C<dark3DColor>
C<backColor>, C<hiliteColor>, C<disabledBackColor>, C<light3DColor> by their name:

   Prima.backColor: #cccccc

Additionally, the following command-line arguments allow overriding the default
values for these properties:

=over

=item *

C<--fg> - color

=item *

C<--bg> - backColor

=item *

C<--hilite-fg> - hiliteColor

=item *

C<--hilite-bg> - hiliteBackColor

=item *

C<--disabled-fg> - disabledColor

=item *

C<--disabled-bg> - disabledBackColor

=item *

C<--light> - light3DColor

=item *

C<--dark> - dark3DColor

=back

=head2 Visuals

The colors in the X11 protocol require the pixel values to be explicitly
defined. A pixel value is a 32-bit unsigned integer that encodes color in the
display format. There are two different color coding schemes - the direct color
and the indexed color. The direct color-coded pixel value can unambiguously be
converted into an RGB value without any additional information.  The
indexed-color scheme represents the pixel value as an index in a palette that
resides on the X server. The X11 display can contain more than one palette, and
allow ( or disallow ) modification of the palette color cells depending on the
visual the palette is attached to.

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

To switch to a non-default visual, use the C<Prima.Visual> XRDB property or
the C<--visual> command-line argument. The list of visuals can be produced
by the standard C<xdpyinfo> command from the Xorg distribution, where each
class of the visual corresponds to one of the six following classes:

=over

=item StaticGray

All color cells are read-only and contain monochrome values only.  A typical
example is a two-color, black-and-white monochrome display.  This visual is
extremely rare.

=item GrayScale

Contains a modifiable color palette, and is capable of displaying monochrome
values only. Theoretically, any paletted display on a monochrome monitor can be
treated as a GrayScale visual. For both I<GrayScale> and I<StaticGray> visuals
Prima resorts to dithering if it cannot get at least 32 evenly spaced gray
values from black to white.

=item StaticColor

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

=item PseudoColor

All color cells are modifiable. Typically, the 8-bit displays define this class
as the default visual. For both I<StaticColor> and I<PseudoColor> visuals
dithering is always used, although on the C<PseudoColor> visuals Prima resorts
to that only if the X server cannot allocate a required color.

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

=item TrueColor

Each pixel value is explicitly coded as RGB. Typical examples are 16, 24, or 32-bit
display modes. This visual class is the best in terms of visual quality.

=item DirectColor

Same as I<TrueColor>, but additionally each pixel value can be reprogrammed.
Not all hardware supports this visual, and usually this visual is not set as the
default one.  Prima supports this mode in the same way as it does the I<TrueColor>
visual without any additional features.

=back

=head1 Images

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

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

To disable the user of the shared memory with images use the C<--no-shmem>
switch in the command-line arguments.

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

A note on the 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. This does not apply to the more modern clipboard exchange protocol based
on images being encoded as binary data, f ex in PNG format. Prima prefers this
exchange protocol whenever possible.

=head1 Window managers

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

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

=head2 Protocols

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

=head2 Hints

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

=head2 Non-standard properties

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

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

=head1 Unicode

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

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

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

=head2 Clipboard

Prima supports the UTF8 text in the clipboard via the C<UTF8_STRING> format.

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

=head1 Other XRDB resources

=head2 Timeouts

The X11 protocol provides no such GUI helpers as the double-click event, cursor,
or menu.  Neither does it provide the related time how often, for example,
a cursor should blink. Therefore Prima emulates these but allows the user to
reprogram the corresponding timeouts. Prima recognizes the following
properties, accessible either via the application name or the Prima class key.
All timeouts are integer values, the number of milliseconds for the
corresponding timeout property.

=over

=item Blinkinvisibletime.blinkinvisibletime: MSEC

The cursor stays invisible in MSEC milliseconds.

Default value: 500

=item Blinkvisibletime.blinkvisibletime: MSEC

The cursor stays visible in MSEC milliseconds.

Default value: 500

=item Clicktimeframe.clicktimeframe MSEC

If the 'mouse down' and 'mouse up' events follow each other within MSEC
milliseconds, the 'mouse click' event is synthesized.

Default value: 200

=item Doubleclicktimeframe.doubleclicktimeframe MSEC

If the 'mouse click' and 'mouse down' events follow each other within MSEC
milliseconds, the 'mouse double click' event is synthesized.

Default value: 200

=item Submenudelay.submenudelay MSEC

When the user clicks on a menu item that points to a lower-level menu window,
the latter is displayed after MSEC milliseconds.

Default value: 200

=item 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, the 'first' and the 'next' delay. These actions are not simulated within
Prima core, and the corresponding timeouts are advisory for the programmer.
Prima widgets use it for automatic scrolling, either by a scrollbar or by
any other means.  Also, the C<Prima::Button> widgets can use these timeouts for
the emulation of a key press in the C<autoRepeat> mode.

C<Scrollfirst> is a 'first' timeout.

Default value: 200

=item Scrollnext.scrollnext MSEC

Same as C<Scrollfirst> but for the 'next' delay event.

Default value: 50

=back

=head2 Miscellaneous

=over

=item Visual.visual: VISUAL_ID

Selects the display visual VISUAL_ID which usually has a form of C<0x??>
hexadecimal number.  Different visuals provide different color depth and pixel
encoding schemes. Some X servers have badly chosen default visuals (for
example, the default IRIX workstation setup has an 8-bit default visual selected), so
this property can be used to fix things. A list of the visuals supported by the X
display can be produced interactively by the standard C<xdpyinfo> command from
Xorg distribution.

Identical to the C<--visual> command-line argument.

See L<Color> for more information.

=item Wheeldown.wheeldown BUTTON

BUTTON is the numeric ID of the X mouse button, which corresponds to the mouse wheel 'down' event.

Default value: 5 ( default values for wheeldown and wheelup are current
de-facto most popular settings ).

=item Wheelup.wheelup BUTTON

BUTTON is the numeric ID of the X mouse button, which that is corresponds to the mouse wheel 'up' event.

Default value: 4

=back

=head1 Debugging

The famous 'use the source' call is highly actual with Prima. However, some
debug information comes already compiled in, and can be activated by the
C<--debug> command-line key. Its parameter is a combination of letters where
each activates the debugging of different subsystems:

=over

=item *

C - clipboard

=item *

E - events subsystem

=item *

F - fonts

=item *

M - miscellaneous debug info

=item *

P - palettes and colors

=item *

X - XRDB

=item *

A - all of the above

=back

Example:

   --debug=xf

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

=head2 GTK

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

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

=head2 Quartz

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

=head1 AUTHOR

Dmitry Karasik, E<lt>dmitry@karasik.eu.orgE<gt>.

=head1 SEE ALSO

L<Prima>, L<Prima::gp-problems>, L<Prima::Widget>,
Nye A, Xlib programming manual. O'Reilly E<amp> Associates, 1995.

