---

Chapter 9.0 X Windows Continues...

Back to Sections 9.2.2 through 9.2.2.12

9.2.3 The X Server Program

9.2.3.1 X Server Start Up Options
9.2.3.2 Mouse Button Mapping
9.2.3.3 Keyboard Mapping
9.2.3.4 Server Error Logging
9.2.3.5 X Server Performance Tuning Guide
9.2.3.6 The Default Font Path

9.2.4 X Display Management Under CodeBuilder

9.3 CodeBuilder X Window Software Overview

9.3.1 Preparing Your Macintosh Control Panels
9.3.2 Getting Started With X
9.3.3 Building X Applications

9.3.3.1 Running X Client Applications
9.3.3.2 The X11 Application Development Environment Under CodeBuilder
9.3.3.3 Programming Notes

9.4 X Window Software Frequently Asked Questions

9.2.3 The X Server Program

9.2.3.1 X Server Start Up Options

9.2.3.2 Mouse Button Mapping

The X server may also be configured to accept the Macintosh Option key in combination with the selected button keystroke using the -mo start up parameter described in the previous section. This allows keyboard keys to function both as normal keys and, when the Option key is pressed, as mouse buttons.

If the default mouse button configuration is modified or you use the Macintosh Option key in combination with another key to simulate a mouse button, all arrow keys revert to their original functions.

Example Three Button Mouse Configuration. Suppose you own a Logitech Mouse and would like to map the middle and right mouse buttons to the <Option-F14> and <Option-F15> key combinations when running the CodeBuilder X server. Your Logitech MouseMan Control Panel would look something like this:

Figure 35. Logitech MouseMan Control Panel

-mo -mbm 107 -mbr 113 -cmdkey meta

9.2.3.3 Keyboard Mapping

To change the X default U.S. keyboard layout, enter the following from a CodeBuilder terminal window prior to starting the X server for the first time:

ln /usr/lib/X11/xinit/Xmodmap-XX/usr/lib/X11/xinit/Xmodmap

9.2.3.4 Server Error Logging

ln /dev/console /var/adm/X0msgs

9.2.3.5 X Server Performance Tuning Guide

• Turn off Apple File Sharing when not in use.
  
  
• Close all open Control Panels on your Macintosh desktop.
  
  
• Macintosh and X screen saver client applications will conflict with one another when run simultaneously. Hide the X server and run your favorite Macintosh screen saver package to protect your screen during idle periods; or run an X screen saver application (e.g. xlock) with your Macintosh screen saver disabled.
  
  
• When using MultiFinder to switch from the X desktop to Finder, a CodeBuilder terminal window, or other Macintosh applications, iconify any X clients that are actively drawing to the display prior to hiding the X desktop.

9.2.3.6 The Default Font Path

Font databases are created by running the mkfontdir(n) program in the directory containing the compiled versions of the fonts (the .pcf files). Whenever fonts are added to a directory, mkfontdir should be rerun so that the server can find the new fonts. If mkfontdir is not run, the server will not be able to find any fonts in the directory.

9.2.4 X Display Management Under CodeBuilder

9.3 CodeBuilder X Window Software Overview

The main client development and run-time library components provided are:

The software in this release is contained on CD-ROM. When installed, the X11 software will reside in the following directories after the installation:

9.3.1 Preparing Your Macintosh Control Panels

Figure 36. The Monitors Control Panel

Figure 37. The Mouse Control Panel

Figure 38. The Keyboard Control Panel

Figure 39. The Control Strip Control Panel

Figure 40. The CodeBuilder Control Panel

9.3.2 Getting Started With X

• Beginning launch and use of the X server is found in section "9.1 The X Desktop".
  
  
• If you want to reconfigure the default X server or learn more about its capabilities before launching it, refer to section "9.2.3 The X Server Program". Three button mouse, remote font server and International (non-US) keyboard users must consult this section before launching the X server.
  
  
• The online manual pages XMachTen, XServer and X are useful and convenient references.
  
  
• Some frequently asked questions about the X server, including troubleshooting issues, are answered in section "9.4 X Window Software Frequently Asked Questions".
  
  
• General information on the operation of CodeBuilder is found in this User's Guide.

9.3.3 Building X Applications

1. First, you must create a working area for X11 development:

mkdir /base/macppc/X11
cd /base/macppc/X11
lndir /base/src/X11

2. To build a single X client, e.g. xlogo, make the Makefile and executable:

cd /base/macppc/src/X11/R6/mit/clients/xlogo
xmkmf
make

3. To install the application(s) in /usr/X11/bin/ type:

make install

4. To install the application manual page(s) in /usr/X11/man/mann type:

make install.man

5. If you chose to install the client(s), you may free up disk space by deleting the extra copy of the executable image(s):

make clean

6. Make the master Makefile using the xmkmf utility:

cd /base/macppc/X11/R6/mit/clients
xmkmf

7. Build the application Makefiles and executables:

make Makefiles
make

then follow steps 3 through 5, above.

9.3.3.1 Running X Client Applications

/usr/X11/bin/xlogo &

9.3.3.2 The X11 Application Development Environment Under CodeBuilder

1. Keep all source file names to 12 characters or less. This is the maximum number of characters that older System V file systems allow when using a source code control system.
   
   
2. If you absolutely must use Makefiles instead of Imakefiles, link against -lX11 instead of -lX. If you are using imake, use the symbolic names $(XAWLIB), $(XMULIB), $(XTOOLLIB), $(EXTENSIONLIB), and $(XLIB). Xaw clients may use the symbol XawClientLibs to refer to the appropriate libraries.
   
   
3. Include header files using the syntax <X11/file.h> instead of X11/file.h, <X/file.h>, or X/file.h.
   
   
4. Include <X11/Xos.h> if you need types.h, string.h or strings.h (then use the routines index and rindex instead of strchr and strrchr), file.h, time.h, or unistd.h.
   
   
5. If you need to put in System V vs. BSD dependencies, use #ifdef SYSV. If you need SVR3 vs. SVR2, use #ifdef USG.
   
   
6. Do not assume that the root window's Visual (returned by the DefaultVisual macro) is the only one available. Some color screens may use a black and white window for the root or could provide StaticColor as well as PseudoColor visuals. Unfortunately, most libraries do not have adequate support for locating visuals to use. In the meantime, use XGetVisualInfo().
   
   
7. Use -display displayname to specify the X server to contact. Do not simply assume that a command line argument that has a colon in it is a displayname. If you accept command line abbreviations, make sure that you also accept the full -display.
   
   
8. Use -geometry geomspec to specify window geometry. Do not simply assume that command line argument that begins with an equal sign is a window geometry. If you accept command line abbreviations, make sure that you also accept the full -geometry.
   
   
9. Use the .man suffix for program manual page sources.

9.3.3.3 Programming Notes

#ifdef MachTenPPCArchitecture
LOCAL_LDFLAGS = -Xlstack=<stacksize>
#endif

LOCAL_LDFLAGS = -Xlstack=100000

9.4 X Window Software Frequently Asked Questions

• The X server does not start up or dies unexpectedly. What is wrong?

You must be running wind(8) when you start the X server. Log into an account under CodeBuilder and be certain the wind process is running before launching the X server.

The X server depends on /usr/X11/bin/ present in your directory search path. Under CodeBuilder for the PowerPC, /usr/bin/X11 is soft linked to /usr/X11/bin. XMachTen, the X server binary, and all server support applications reside in this directory. If you are running a custom shell (e.g., zsh or ksh), make certain your X11 search path is set up before you start the wind process. The sample .login and .profile files in /usr/share/skel show examples of adding to your search path to include /usr/X11/bin.

You may have accidently installed the X software on a target volume other than the volume containing your CodeBuilder folders.

You may have moved your CodeBuilder folders to a subfolder on the target volume prior to installing the X Window Software. Use Finder to temporarily relocate the CodeBuilder folder to the top level of the target volume before installing the X software.

Read section "9.3.1 Preparing Your Macintosh Control Panels".

The log files /var/adm/X0msgs and /var/tmp/startXmsgs'do not exist or have the wrong permissions. The following commands illustrate how to create and set the proper permissions:

cp /dev/null /var/tmp/X0msgs
chmod 666 /var/tmp/X0msgs

The X server maintains a log file in /var/adm/X0msgs. Consult this file if you have difficulties starting or operating the X server. You can redirect entries logged to this file to the CodeBuilder Console terminal window using the command:

ln /dev/console /var/adm/X0msgs

• My arrow keys stop working when I run the X server. Why?

By default, the X server uses the left-arrow for mouse button two, the right-arrow for mouse button three, the down arrow as a Control key, and the up arrow as a Meta key. When the Option key is pressed with an arrow key, the arrow key's original function is temporarily restored. When you re-map mouse button keys two and three in your .xserverrc file, all arrow keys' original functions are permanently restored. You may also use the -mo server start up option to restore normal functionality to your arrow keys.

Refer to section "9.2.3.2 Mouse Button Mapping" and the example in the sample X server start up file /usr/X11/lib/X11/xinit/xserverrc.

• What three button mouse do you recommend?

Both the Logitech MouseMan and the MouseSystems A/3 Optical Mouse have been tested successfully with the X server.

• My X desktop Macintosh menu bar changes colors when I run certain X color applications. Why?

When the X desktop is visible, X client applications have precedence over the MacOS when competing for the limited number of colors that can be displayed simultaneously. The menu bar is drawn by the MacOS based on the best matching colors available.

Consider running the X server with no Macintosh menu bar as described in section "9.2.3.1 X Server Start Up Options".

• When I type twm, CodeBuilder responds twm: Command not found. Where are the clients located on my system?

Make certain that either the /usr/bin/X11 or /usr/X11/bin directory is in your directory search path.

• I am using a French keyboard. When I type an 'a' into an X window application, the application echoes a 'q'. Why?

You must load a French keyboard mapping file when the X server is launched to re-map the default U.S. X keyboard map. Refer to section "9.2.3.3 Keyboard Mapping".

• I have a .Xdefaults file in my home directory, but my X applications are not affected by its contents. Why?

The X server has a local database which takes precedence over the .Xdefaults file. This database originates from a previous running of the xrdb(n) program with the -load or -merge options.

You can force your .Xdefaults file to be read by the application by defining the XENVIRONMENT shell variable:

setenv XENVIRONMENT .Xdefaults 

Resources defined via XENVIRONMENT override duplicate resources contained in the X server's database.

Alternatively, the .Xdefaults file is read if the database is removed from the server:

xrdb -remove

• My X application requests a large color cursor. Why does it show up on the server as a small arrow?

The X server takes advantage of the Macintosh firmware cursor for maximum performance and a lively tactile response. The Macintosh cursor is limited to a fixed 16 x 16 pixel size, so when an application tries to display a cursor larger than 16 x 16 pixels, the server substitutes a standard arrow cursor. The X server currently does not support color cursors with this Macintosh cursor.

Both of these problems can be avoided by using the "-swc" flag with the X server.

• How do I use different colors for the application I am running?

If you have a color monitor, you can specify a custom foreground and background color for your application using the -fg and -bg command line options. For example:

xlogo -bg yellow -fg green &

Alternatively, you can copy the default application resource file (for example, XLogo) from /usr/X11/lib/X11/app-defaults (if present) for the program you are running to your home directory and modify it to suit your tastes:

XLogo*background: green
XLogo*foreground: yellow

Refer to the manual page for the client you are running for a description of the color resources available to the application.

Note that command line options take precedence over resource definitions.

• Where can I obtain other X client applications for CodeBuilder?

A directory of contributed (and unsupported) X client applications in CodeBuilder executable format is maintained on Internet host ftp.tenon.com in the /pub/applications/X11 directory.

• Why does my X application crash when I am using the CodeBuilder unix kernel?

The application has a fixed 36KB stack size when operating in a real memory environment (unix) and may require more stack space in order to run. Increase the program's stack allocation using the example in section "9.3.3.3 Programming Notes".

• I use emacs. I noticed that Meta-% and Meta-! don't do what I expect them to do. What is the problem?

The MacOS reserves all Command-Shift-number keystroke combinations for special effects. Since the default X Meta key is the Command key, the Meta-Shift-number key sequence is not delivered to the X client. Use the xmodmap(n) utility to re-map Meta to something other than the Command key.