XF86Setup README

Introduction

XF86Setup is a new program to aid in the configuration of the XFree86 servers. It is unlike previous programs (such as ConfigXF86 and xf86config) in that it is specifically designed to do as much as possible while in graphics mode.

However, xf86config is not being replaced. XF86Setup's resource requirements are considerably greater than those of xf86config. It also is not usable for OS/2 configuration (at least not yet).

XF86Setup requires that both the VGA16 and card-appropriate servers be installed. Furthermore, the servers must include the XKEYBOARD, XFree86-VidModeExtension, and XFree86-Misc extensions. If the dialog program is installed, it will be used, but is not required.

If you wish to run XF86Setup without installing it first, you need to set the environment variable XF86SETUPLIB to point to the source directory.

The command line options are documented in the XF86Setup man page. For instructions regarding the use of the program, see the Quick Start Guide to XFree86 Configuration and the on-line help.

The rest of this file contains information that is mainly of use to someone interested in hacking on the code.

Manifest

CHANGELOG: List of changes in each version
Imakefile: Imakefile to generate the program
LICENSE: Redistribution license and disclaimer
README: ASCII version of the README
README.html: HTML version of the README
TODO: Things to be done or at least considered
XF86Setup.man: The man page
main.c: Main prog that starts the Tcl interpreter
tclcards.c: Routines to connect Tcl and the Cards database reading functions
tclkbd.c: Routines to connect to the XKB extension
tclmisc.c: Routines to connect to the XFree86-Misc extension
tclmisc.h: Prototypes for above
tclother.c: Routines to implement misc Tcl commands
tclvidmode.c: Routines to connect Tcl and XFree86-VidModeExtension
tclvidmode.h: Prototypes for above
tclxfconf.c: Interface to xf86Config.c for reading an existing XF86Config file
xfsconf.h: Prototypes for above
tclxkbui.c: Tk widget interface to the xkbui library
tkother.c: Routines to implement misc commands requiring Tk
card.tcl: Device configuration routines
carddata.tcl: Information regarding supported chips and such that is used by card.tcl
done.tcl: Routines that are used once the user has finished the various configuration steps
filelist.tcl: Lists of files that should be checked for proper installation
keyboard.tcl: Routines for keyboard and other configuration
modeselect.tcl: Mode selection routines
mondata.tcl: Default monitor sync rates and modes
monitor.tcl: Monitor configuration routines
mouse.tcl: Mouse configuration routines
phase1.tcl: Tcl commands to do Phase I
phase2.tcl: Tcl commands for Phase II
phase3.tcl: Tcl commands for Phase III
phase4.tcl: Tcl commands for Phase IV
phase5.tcl: Tcl commands for Phase V
setuplib.tcl: Library of XF86Setup specific Tcl procs
srvflags.tcl: Configuration routines for server flags
pics: Directory containing bitmaps used by program
scripts: Directory of other scripts that use XF86Setup as an interpreter to implement other clients
tcllib: Directory containing Tcl code to set the standard widget bindings (from the Tcl & Tk 4.0p3 distributions) and with misc tcl routines and the combobox widget
texts: Directory containing helps and messages (The subdirectories "generic" and "ja" correspond to English and Japanese respectively)

New Tcl commands

The program includes a Tcl interpreter which has been extended with additional commands (in addition to those in the Tk toolkit). They are explained below.

Interfacing with the Cards database

Two commands have been added to read data from the Cards database (as used by xf86config)

xf86cards_getlist: Return the full list of card names
xf86cards_getentry: Get complete info on a card

A valid card name should be supplied as an argument to xf86cards_getentry

XFree86-VidModeExtension commands

Several commands have been added which allow the program to communicate with the XFree86-VidModeExtension server extension, namely:

xf86vid_addmodeline: Add a new mode to the list of video modes
xf86vid_checkmodeline: Checks that a mode is usable
xf86vid_deletemodeline: Removes a mode from the list of valid modes
xf86vid_getversion: Query extension version
xf86vid_getbasevals: Get the ErrorBase and EventBase
xf86vid_getmodeline: Get the current video mode settings
xf86vid_getallmodelines: Get video settings for all modes
xf86vid_getmonitor: Get monitor specs
xf86vid_lockmodeswitch: Turn on/off mode switching
xf86vid_switchmode: Switch to next/previous mode
xf86vid_switchtomode: Switch to a mode

Only the last two take an argument, which is either lock or unlock in the case of xf86vid_lockmodeswitch and either next or prev in the case of xf86vid_switchmode.

xf86vid_getversion returns the version as a floating point number (e.g., 1.2), whereas xf86vid_getbasevals returns a Tcl list containing two elements.

The xf86vid_getmodeline command returns a string which contains the standard mode line values including flags, if any, with each value separated by a single space.

xf86vid_getallmodelines returns a Tcl list. The number of elements corresponds to the number of valid video modes. Each element is in the format returned by xf86vid_getmodeline. The first element contains the mode info for the current mode.

xf86vid_getmonitor also returns a Tcl list. The first element is the vendor name. The second is the model name. The third element contains all of the horizontal sync rates as comma separated ranges (so for example if the sync rates were 31.5, 35-40, and 45-55 the return value would be: 31.50-31.50,35.00-40.00,45.00-55.00). The last element contains the vertical sync rates in the same format.

XFree86-Misc extension commands

Communication with the XFree86-Misc extension is possible using these new commands:

xf86misc_getversion: Query extension version
xf86misc_getbasevals: Get the ErrorBase and EventBase
xf86misc_getmouse: Get the current mouse settings
xf86misc_setmouse: Set the current mouse settings
xf86misc_getkeyboard: Get the current keyboard settings
xf86misc_setkeyboard: Set the current keyboard settings

XF86Config file reading commands

Two commands are available for reading XF86Config file:

xf86config_findfile: Locate the XF86Config that would be used by the server
xf86config_readfile: Read in the XF86Config file and set the values from it

XKEYBOARD extension commands

A few commands are available for communicating with the XKEYBOARD extension:

xkb_components: List the components that make up the given keyboard
xkb_free: Free a previously allocated keyboard description structure
xkb_getrulesprop: Read the _XKB_RULES_NAMES root property
xkb_listcomponents: Returns a list of available components
xkb_listrules: Returns a list of available rules defs and their descriptions
xkb_load: Change the keyboard setup for the specified components
xkb_read: Get keyboard information from the server
xkb_setrulesprop: Set the _XKB_RULES_NAMES root property
xkb_resolvecomponents: Use the XKB rules to determine the components necessay for an appropriate keymap (requires XKB library support that might not yet be in the XFree86 tree).

The xkbview widget is also available as interface to the xkbui library.

Miscellaneous

Other commands added to the interpreter are:

getuid: Returns the real uid of the user
server_running: Returns true if a server is running on the specified display
process_running: Checks if the specified process is running
has_symlinks: Returns true if running on an OS that supports symbolic links
link: Makes a (soft or hard) link from one file to another
unlink: Removes the specified file
mkdir: Create the named directory
rmdir: Remove the named directory
umask: Set the file creation mode mask
sleep: Sleeps for the specified number of seconds
clock: Obtain and manipulate time
findfocuswindow: Search along an axis for a window which accepts focus (added to the interpreter after Tk has been initialized)

getuid just returns the numeric result of getuid().

The server_running command simply tries to perform an XOpenDisplay() on its argument. If the call fails, it returns false (0), otherwise it calls XCloseDisplay() and returns true (1).