
<<X11Doc.tioga>>
<<Copyright © 1988, 1989, 1990, 1991, 1992 by Xerox Corporation.  All rights reserved.>>
<<Created by: Christian Jacobi, April 20, 1988 9:49:16 am PDT>>
<<Christian Jacobi, June 28, 1993 2:49 pm PDT>>
The X Window system version 11.  

Abstract:  A low level library and a high level toolkit for the X window system.
Created by: Christian Jacobi
Maintained by: Christian Jacobi:
Keywords: Window system, User interface, toolkit, X Windows, 

This text documents how to use the X software;
For client programmer Xl level information, see: X11ClientsDoc.tioga
For client programmer XTk toolkit level information, see: XTkDoc.tioga
For implementor information, see: X11ImplDoc.tioga
For a list of messages, see: X11MessagesDoc.tioga
For Cedar X11Viewers information, see: X11ViewersDoc.tioga
For information about the Remote-Cedar-in-X, see: X11RemoteCedarDoc.tioga


Contents
1. How to run the X Window System
2. The X Window System and your Cedar program
3. How to drive the olwm Window Manager 
4. Other Documentation 
5. X11 Demo Programs 
6. The xrdb database 

1. How to run the X Window System 

You might as well read the standard unix X documentation for better explanations.

There are many different ways to start X windows.  While some some people are confused and blame X windows, I am tired of keeping 
old outdated methods working.  In truth this actually makes sense: X window defines what it does, but how to start it is not really 
a part of the standard but of the operating system command language.  

There is the PARC standard, using runx.  I recommend this.
There is the way you have always done it.  Also recommended.
There is the old way it was set up for Cedar.  I do NOT recommended this.

See also
/import/Xmisc/top/README

Today's most recommended method
Say "man runx"
Do it exactly as described for standard runx, it will work for Cedar.
For small improvements for Cedar application, look at Christian Jacobi's version of the set up files.

Window manager
If you are an old entrenched X user, use whatever window manager you want.
If you are a new X user, use the olwm window manager; it is better for Cedar then twm.

Some handy files...
look at /cedar10.1/CedarEssentials/X/*
and use the ones you like.

.twmrc
Set-up file for the twm window manager.  Use this file only if you really want to use twm.    
This version of .twmrc has some entries which are useful for Cedar.
You can perfectly run Cedar in an X window without this file.

.openwin-menu
A file which sets up the olwm window manager (think user profile).  This file is highly editable and Christians copy has lots of 
comments.  
I believe this file (if it exists) must be stored on your root directory and must have this name. 
This file is only read by the olwm window manager.
You can perfectly run Cedar in an X window without this file.

.xinitrc
This script really describes how X should be started.  
I believe this file must be stored on your root directory and must have this name.
It is a text file and my version has lots of comments inside.  File names in .xinitrc must not use "~".  X wizards have their own 
private versions.  Cedar folks may personalize it because the standard version calls a command file.  However it is also 
discouraged to edit this file because the parc standard set up will overwrite it and your edits are lost.  Many standard set up 
methods have a place in .xinitrc where a personalized version is called.
Cedar in an X window does not directly care about this file, however Cedar requires xmodmap to be called, which is typically done 
from within .xinitrc, or, .xinit-personal.

.Xmodmap 
Defines the mapping between hardware keys and what glyphs the software sees when a key is pressed down.  In X (and in Cedar) 
terminology the mapping between KeyCode's and KeySym's.  This is very hardware dependant.  Christians version, and, the version in 
CedarEssentials are defined for sun type 4 keyboards.
This file may be stored on any directory with any name; it is accessed from an xmodmap command (in .xinitrc or .xinit-personal).  
It is a text file and many version have lots of comments inside.  
Important for Cedar: You could run Cedar in an X window without this file, but certain keys and commands would not work without.   

All three: The PARC standard version for Sun keyboards type4, Christians version, and, the version in CedarEssentials define 
keysyms very carefully so that 4 classes of programs can run concurrently.  
1) Standard X window application (from X consortium)
2) Sun's openwindow-2 deskset applications
3) Cedar10.1
4) PCedar2.0
If another version of .Xmodmap is used most programs work fine, except that some few keys or key combinations won't work.


Gotchas

- Cedar applications, in particular X11Viewers, like click to type mode.  I recommend (but it is not mandatory) using a window 
manager which does click to type well.   In general twm may be a good window manager, but, olwm has a much better click to type 
mode.

- Set auto repeat off.  Autorepeat might confuse some multi key combinations which are used slowly by some users.

- Cedar recognizes some special keysyms.  See the paragraph on .Xmodmap above. 

Set access permissions to the X server

This is not strictly necessary.  The setup procedures might already do it, but you might want to change access permission while X 
is running.
To a shell [in X!] type "xhost name-of-host", or, type "xhost +" to allow access to anybody.
2. The X Window System and your Cedar program

Make your program find the right X server...

For programmers only: 

Defaulting the server will do the right thing.

For interactive users: 

PrincOps on D-Machines
Make sure you have an X11.ServerName user profile entry:
X11.ServerName: "name-of-sun"

Cedar10.1 machines

Application started from a Cedar commander:
Use the X11 command to set up server.  Syntax:
X11 [-display name-of-display] [-sync] [-check] [-geometry geometry-without-space] -- Real command

If nothing is set up, the local display will be accessed.

If connection to a non local machine is desired, set the environment variable DISPLAY to the name of the machine.
e.g., to use lyrane, type
setenv DISPLAY lyrane
Don't forget to clear the environment variable afterwards; otherwise you will get all your X windows on the specified display.

Fine point for X experts: 
Cedar understands the display and screen numbers exactly like any c programs  
e.g. to use lyrane's second display, type
setenv DISPLAY lyrane:0.1

DF files 

Cedar X interfaces
/Cedar10.1/top/X11.df
/Cedar10.1/top/X11....df

PrincOps
/CedarChest7.0/top/X11RemoteCedar.df
/CedarChest7.0/top/X11.df


3. How to drive the olwm Window Manager

This is a very short summary; use man olwm to get better information
Resize a window: left click a corner and move it
Move a window: left click an edge and move it
InputFocus: Does click to type right.   Watch this: some system administrators talk you into using real estate mode.   This is way 
inferior to click to type.
Window commands: Right click on window border, header or icon.
Background commands: Right click on background.
Iconify: Window menu, or, left click icon symbol in header.
Open icon: Window menu, or, left double click on icon.

 
You might want to set up Cedar for click to type mode:
Cedar.InputFocusMode: clickToType 

 
4. Other Documentation 

See [Cedar10.1]<Top>CedarEssentials.df
[Cedar10.1]<CedarEssentials>CedarEssentialsDoc.tioga
Command files for automating set up of X Window System 

/import/Xmisc/top/README

5. X11 Demo programs 

All these demo programs are not completely minimal in size for three reasons
1)    There are some extra variables for debugging (I use them to test out X11)
2)    Sometimes I put extra stuff in temporarily (Re-using demos for makedo).
3)    Instances are handled explicitely.  I'm afraid of programs without instance data being used as template....

These demo programs implement a command matching the program name.  Executing that command creates an instance widget.

From /Cedar10.1/Top/X11Demos.df

X11Hello              Minimal program; "Hello world" 
X11BounceDemo     Bouncing squares; each square is a separate process.  Also demonstrates toolkit. 
X11TextDemo         Rotating text. 
X11TilingDemo       Making ridiculously many small X windows.  
                        Not that good an example program, but interesting for benchmark purpose.

From other places

Slate                    In /Cedar10.1/Top/Slate.df.  A nice little application.
Handwriting recognition        In /Cedar10.1/Top/X11Handwriting.df.

6. The xrdb database
Geometry resources: 

To specify the geometry resource with the xrdb database, use the standard Cedar XTk geometry resource syntax:  

screenspec.application.geometry: ...

Note that the XTk standard resource syntax does NOT expose the widget hierarchy, which is considered private to the implementor of 
the application.  On the other side XTk requires a screen specification, as many people have multiple screens.  XTk does not 
strictly play the silly class/instance game like Xt but allows an arbitrary number of options.  However, shells (and some other 
things I made) use only one single option.  (BTW: these generalization lead to a substantial [exponential!] performance advantage 
for XTk over Xt in resource handling)

To specify a geometry string, XTk uses the regular X standard.


Examples:
anyscreen.Slate.geometry: 200x200-4+7
bw.Slate.geometry: 200x400
color.Slate.geometry: 400x200