X11ViewersDoc.tioga
Copyright © 1990, 1993 by Xerox Corporation. All rights reserved.
Created by: Christian Jacobi, May 23, 1990 8:51:53 pm PDT
Christian Jacobi, May 26, 1993 6:58 pm PDT
X11ViewersDoc
X11Viewers implements the Cedar Viewers "system" in a single X window.
For documentation about
X windows in general: look at X11Doc.tioga
Cedar in general: look at CedarDocDoc.tioga
Contents:
What is X11Viewers
Starting and stopping X11Viewers
Commander commands for X11Viewers
Xrdb data base options
The X11Viewers button in the viewers header
Cut and Paste
Porting X11Viewers to a different X server
What is X11Viewers
X11Viewers implements the Cedar Viewers "system" in a single X window.
Once in the glorious future we will have a different system, where each top level "viewer" is an X window of its own. We will give that system a different name.
X11Viewers basically does one X window request: PutImage. Cedar images into a bitmap which is refreshed using X windows. If the client and the server share the same machine it tries to use shared memory to increase performance. X11Viewers takes advantage of the shared memory extension when it is available. X11Viewers can also take advantage of other packages creating imager contexts in X11 (ImagerX11).
Starting and stopping X11Viewers
This describes how to start or stop X11Viewers; not how to start X windows.
Starting
From a Unix shell
The dynamicly loaded world is started with the commands
% enable cedar10.1
% CedarCommander X11Viewers
The packaged X11Viewers world is started with the commands
% enable cedar10.1
% X11Viewersworld
From window manager menus
The "PARC standard" window manager menus have an entry to directly start packaged X11Viewers. At least twm and olwm have nicely set up pop up menus. You have to use the prepared initialization files of course.
Special start up sequence for slow communication bandwidth.
When using X11Viewers through slow phone or ISDN lines it could be started up so that ImagerX11 is used right from the beginning. (So that X11Viewers never tries to send large bitmaps through the X protocol...). Don't forget the DISPLAY environment vriable.
% enable cedar10.1
% CedarCommander X11ViewersI
On the other side, using compression might be advantagous to using ImagerX11. In particular when the fonts do not match.
Stopping
From a Cedar commander
Use the ExitWorld command
From the X11Viewers pop up menu
There is an "exit cedar" option
From window managers
Olwm's "quit" option will do the right thing: It offers a pop up menu to either get the main X11Viewers pop up menu, or, to "exit cedar".
Twm's pop up menus contain the right entry "delete window". Do not use the "destroy connection" option.
Fine point: Destroy the window correctly. ("Correctly" means to use the ICCCM delete window convention. Simply destroying the connection would NOT work. A broken connection is thought to be a communication failure; the X11Viewers world tries to create a new connection).
From a unix shell
Use the kill command. Do NOT use the "-9" option; this option prevents some crucial clean up and forces eventually to reboot the workstation.
Commander commands for X11Viewers
X11
Executes the remainder of the commandline with a particular X display selected.
Format: X11 [-display ServerName] [-sync] [-check] [-geometry wXh[+x+y]] -- Real Command
X11DefaultServer
Defines what X server to be used when an application defaults the server name
Format: [name-of-application] name-of-x-server
X11ViewersKillConnection
Kills the current connection. Hopefully a new connection will be created.
X11DefaultSynch
Debugging feature: Set synchronization toggel for new connection of X11Viewers.
X11Identification
Print Identification.
X11ViewersImagerX11
Several options: {status|on|off|cond|load}
status: prints current status
on: tries to use ImagerX11 when possible (for next connection)
off: does not use ImagerX11 for next connection
cond: tries to use ImagerX11 when thex server is remote (for next connection)
load: tries load the ImagerX11 package
X11ViewersSetCursorColor
Set cursor color (r,g,b: REAL)
X11ViewersMove
Initates widget migration
X11ViewersWithdraw
Withdraws the window. You must have a remote means to issue commands to undo this.
X11ViewersReOpen
Re-opens window if withdrawn. Note that you can not type this command, you need some remote commander to execute this.
Xrdb data base options
Cedar runs fine even without any database entry.
Cedar reads the xrdb database from the X server directly. The database itself is typically set up with the program xrdb using the file ~/.Xresources. While Cedar shares the database with other C programs, it does not share the key format which is more powerful. In general capitalization for keys matters; it has nothing to do with the standard class/instance hierarchy of Xt.
The database query mechanism used in Cedar is described in CustomizeDoc.tioga.
Geometry settings
! Cedar Viewers World
! (bw | color | anyscreen) (CedarViewers | CedarViewers-NameOfHost) geometry:
! width x height + x-pos + y-pos
! -0-0 makes position relative to lower right corner.
anyscreen.CedarViewers.geometry: 985x800-0-0
bw.CedarViewers.geometry: 1100x900-0-0
Input focus settings
Dependent on the used window managers policy use either
Cedar.InputFocusMode: realestate
or
Cedar.InputFocusMode: click-to-type
It matters that cedar and the window manager agree on whether click-to-type or realestate mode is used; otherwise minor confusion occurs.
Color mode
For efficiency reasons it might be advantagous to restrict display to one bit per pixel
This entry is specified differently for Cedar worlds with or without shared memory.
Either color or black and white works only if the server supports the mode.
Cedar.shared.BWOnlyMode: false
Cedar.remote.BWOnlyMode: true
The X11Viewers button in the viewers header
Shows a popup menu with X11Viewer specific options. These may change faster then the documentation, but some entries are quite stable.
Surface units
Works on black and white display mode only.
Shows a sub menu with
normal scale
double scale
support "real estate" X
support "click to type" X
A switch telling PCedar what kind of window manager is used. Depending on this switch PCedar interacts differently with the X input focus. Input focus really works only correctly when Cedar and the window manager agree on which convention is used.
Color mode
Shows a sub menu with
BW always
color/BW from DB
color <- if possible
Restrict to black and white might improve performance a little. Either Color or BW works only if the server really suports that mode.
Rescues
Shows a sub menu with
assert keys up
De-confuse keyboard cache.
destroy connection
Closes the current connection... A new one will be generated soon.
This is mainly a debugging tool.
exit pcedar
Terminates world and windows.
Applications
Shows a sub menu with
scren spy
Starts an instance of the screen spy program.
migration tool
Starts an instance of the migration tool program.
Imager-X11
Shows a sub menu with
always
never
conditional
Whether the ImagerX11 method of creating imager context ought be used.
In case of viewer wedge the popup menu can still be activated by deleting the X window and choosing the appropriate entry in the deletion query. This is the reason why some of these entries appear in this menu at all.
Cut and Paste; Interoperability
X11Viewers understands many different interoperability conventions. Of course none of the X window "cut buffer" conventions understands Tioga formatting. Cedar tries to be smart and use the "right" convention.
Copy: (Key) Puts current Tioga selection into X server "cut buffer".
Paste: (Key) Pastes contents of X server "cut buffer" to current Tioga position.
All X11Viewers (but not Viewers) related pop up menus and labels put their text in the "cut buffer" when the Cut key is pressed while the cursor points to the label.
The ICCCM (X consortiums Inter Client Communication Convention Manual) defines many communication schemes.
Cut buffer: Defined by ICCCM, but later discouraged by ICCCM. Useful to communicate with "xterm"s.
Primary selection: Complex selection exchange convention defined by ICCCM.
Clipboard selection: Complex selection exchange convention defined by ICCCM.
On a "cut" operation Cedar simply puts its data into all above mentioned cut buffers.
The "paste" is more difficult. While Sun Microsystems representatives in the ICCCM definition gremium are extremely arrogant, the Sun implementations of ICCCM is painful buggy. It is not possible to get a timestamp and a selection in an atomic way from sun deskset tools. Furthermore Sun uses some private undocumented conventions. Sun makes it impossible to simply get all 3 selections and then decide from timestamps which to use. Cedar asks the cut buffers in the "right" order until one returns a value which looks reasonable. I hope the order is defined reasonably, but I can't help if for some application it wouldn't work.
The X11Viewers pop up menu (in the Applications sub menu) has an entry called "Clipboard tool". This tool allows to cut and paste data by explicitely specifying which cut bufer shall be used.
Porting X11Viewers to a different X server
(This is not about different host machines, but about different server machines. )
The X protocol is the X protocol... It simply ought to work.
However the following gotchas exist:
0) There are known and unknown bugs in server implementations.
Many known bugs are compensated and do not cause problems...
The early versions of X11R2 used to have a bug in the put image request. For reasons of speed, once X11R4 got popular this bug is not compensated for anymore. (See XlBitmapWindowImpl.mesa)
Sun's beta version of openwindow-3 did send certain DestryNotify events twice. This used to kill X11Viewers; this was UNSAFE in the Cedar sense. However this bug is compensated for.
1) Sofar X11Viewers have never been knowingly used on a little endian machine
I am very interested in knowing whether it simply works, or, whether there are any problems.
I once tried X11Viewers displaying on an IBM PC. It failed dismally but I believe that this particular X server was of very poor quality and didn't really debug it.
2) Fonts.
Make sure the server supports a resonable font to be used as default font for XTk. XTk will search hard to find a default font, but setting up the resource database can give a much better choice.
3) Keyboard mapping.
Make sure the keyboard mapping contains the special keysyms used by cedar. Note that PCedar2.0 and Cedar10.1 have different definitions for some keysyms. (For some reasons the values PCedar2.0 were at the wrong place).
Typically the Swat and Look keysyms might be missing.
Swat: 0x10070015
Look: 0x10070016
To get the position for keysyms in an .Xmodmap file right (So that standard C applications won't break): Put the cedar keysyms last. If the number of non-cedar keysyms is either one or three, repeat the last non-cedar keysym once before the cedar keysyms.
4) The ImagerX11 package has some funny setup with fonts.
Using ImagerX11 might work, or, it might not. Blame or thank the ImagerX11 implementors; there is nothing which can be done in X11ViewersImpl directly.
Related commands
ScreenSpy.
See ScreenSpyDoc.tioga.
Color issues
Cedar tries first if the X server has a "standard" color map defined. If so, this is used, except that a few important colors are added.
If the X server does not have a "standard" color map installed, the standard X window program "xstdcmap" might be used to define it. Use the man page to find out how.
If no "standard" color map is available Cedar tries to allocate entries in the default color map. It tries first a large color-ramp and successively smaller color-ramps.
If the default color map is too small even for relative small color-ramps, Cedar allocates a color map of its own.
Tioga selections are implemented with "invert" function. This requires the color map to have black and white at "opposite" ends. Cedar tries hard to find such entries, but sometimes the X colormap simply doesn't have free cells left. We do not use this as a reason to allocate color maps of our own but fail to invert properly.
Finally: If colors fail, the X11Viewers menu allows the selection of black and white mode.