Developing Local X Client Applications

You can use the WinaXe Plus XDK to develop local X clients. Local X clients are X client applications built to run on a PC (under MS Windows) instead of a UNIX host.

Local X support permits X clients to be started and/or displayed locally or remotely on other X servers in the network. Local X support also permits local X clients to run on stand-alone PCs without network support.

To create a local X client, you can use the contents of the WinaXe Plus XDK in conjunction with the MS Visual Studio 6.0 application development tool.

The WinaXe Plus XDK lets you create two types of local X client applications:

• GUI application (Win32) - Makes use of the Local X Console application to display output.
  
  
• Console application - Runs in a DOS shell. These X applications use STDIN for console input and STDOUT and STDERR for console output.

You can create a local X client of either type with one of two methods: you can write your own code from scratch, or you can port an existing X client from the UNIX or Linux host to your PC and rebuild it. For both methods, your X client code must reflect the differences between the X Window System (as described in the MIT documentation) and the WinaXe Plus XDK.

X Window Application Development Overview

This section describes WinaXe Plus XDK particulars that you need to understand in order to develop a local X client application program.

Overview of X Window System

The X Window System, typically referred to as X (or X11), is a network transparent windowing system based on the client-server model. X is a combination of:

• The X Display Server
• X Clients
• The X Protocol
• Xlib

The X Display server (or X server) is the process executing on a workstation and managing the graphics output and input from the workstation display (i.e., its monitor(s), keyboard, and mouse).

X Clients are applications that use the workstation display. The X clients, whether running locally or on a remote computer, send request to the X server using a communication channel. The X client application and the X server can run on the same machine.

X Clients communicate with X servers (usually through a network) using the X Protocol. In the X Protocol, data is exchanged in an asynchronous manner over a two-way communication channel that enables transmission of a stream of 8-bit bytes.

All X needs is a reliable data path between X clients and the X server. As long as there is a common networking protocol (e.g., TCP/IP) available for data transfer, the X server can display output from any X client regardless of the operating system under which the client executes.

Xlib is a library of more than 300 utility routines that programmers use to access the X protocol. The Xlib functions are used to accomplish the major tasks in an X application.

With X running on a workstation, the X server is listening to the network connections at a specific port and acting on the X protocol requests sent by X clients. The X server manages regions of the screen known as windows, where the output from an X client is displayed. When X applications are running, everything on the screen appears in windows and each window is associated with a specific X client.

Creating a window is one of the basic X protocol requests that an X server handles. The X server considers anything you do with the keyboard and mouse as events to be reported to the X clients. When you press and release a mouse button, the X server sends these input events to the X client that created the window containing the mouse pointer. The X server also sends another kind of events to X clients. These events inform an X client if anything happens to its window.

It is very difficult to build a large application with Xlib. X Toolkits, another set of routines to implement commonly created window objects, such as pushbuttons, lists, and menus, can be used to build a graphical user interface (GUI). The X Window System comes with the X Toolkit (Xt) intrinsics that use an object-oriented approach to implement basic building blocks called widgets. Other toolkits, such as the Motif toolkit (Xm) from the Open Software Foundation (OSF), use a higher level of abstraction.

X applications primarily call routines from a toolkit. The toolkit may call routines from Xt, which in turn call Xlib. An X application might also make some direct calls to some Xlib routines for generating text and graphics output in a window.

The current version of X Window specification is 11 and hence the name "X11" is used. There are different revisions in version 11. The revisions currently in use are R5 and R6.

Structure of a Typical X Application Program

A typical X application program has three major sections:

• Initialization
• Event Loop
• Clean-Up

The initialization section sets up the window system for user interaction. In this system, it invokes the routines provided in X11, Xt, and Xm libraries to draw the various windows and graphics. The call XtAppInitialize() provided by the X11 library creates a top-level window for the application. All the other windows are created as children of this top-level window.

After initialization, the program enters a loop in which it repeatedly tries to get events from the window system and processes them. The call XtAppMainLoop() provided by the X11 library is for entering the event loop.

Finally, before exiting, the program performs any necessary cleanups. Usually the exit code is in a program that is called when the user clicks on the Exit button provided by the application (or on the Close button on the window frame on the right top of the window).

Specifying Resources

All X Window programs have associated resource files where options for colors, fonts, etc in the application can be specified. To take advantage of this capability, programs should be written such that hard coding of resources is avoided, so that resources specified in the configuration files are used.

The resource configuration file for an X application will have the same name as the application specified in the call to XtAppInitialize(). It can be located in the directory where the application is launched, or else X will search for this file in the directory specified by the variable XAPPLRESDIR.

We recommend you to keep your resource files for newly developed X applications in the home\x11\app-defaults directory of WinaXe Plus (where the resource file for the xfb application is already placed).

Building an X Window Application

An application code is written in C or C++ and compiled using any of the available C/C++ compilers in the system. All source code must be compliant with X11 standards.

An X application needs to be linked to the X libraries, X11 (for Xlib), Xt (for Xt), and/or Xm (for the Motif toolkit).

To build your application (i.e. to create an executable), you can use either GUI (e.g., the Build menu item in Microsoft Visual Studio 6.0) or the command line mode (i.e. by using Makefile).

To create the X application executable (the .exe file), you compile and link your application as a Microsoft Windows 9x/ME/NT4/2000/XP application.

When creating a GUI application, you also need the standard files required for compiling and linking a Microsoft Windows 9x/ME/NT4/2000/XP application (for example, an .rc resource file).

Preparing Your Code

You need to prepare the source code for your X client for MS Visual C++ development in the following way:

1. Make the following changes to the source code:
   

   a) If you are creating a GUI application X client, change all instances of the fprintf function to STDERR or STDOUT to calls to printf, lprintf, or some other means of displaying output.

   b) Change memory allocation and de-allocation routines to their Xlib counterparts.

2. Check for any incompatibilities between MS Windows 9x/ME/NT4/2000/XP and UNIX, including the following:
   

   a) Ensure that there is no UNIX-dependent code that is incompatible with MS Windows 9x/ME/NT4/2000/XP. For example, you must rewrite code that uses such items as timers, mailboxes, and STDIN (for GUI applications).

   b) Ensure that the code does not use any keywords reserved for the MS Windows 9x/ME/NT4/2000/XP C compiler as variables, labels, or application-defined function names.

3. Ensure that all functions are properly prototyped.
   
   
4. Ensure that the compiler and linker options are correct. You can find the correct options in the sample make files in the source directory.

Building an X Application in MS Visual Studio

To create and build your X application (i.e. to create an executable) in MS Visual Studio 6.0, you can use the following procedure:

1. Create an empty MS Visual C project:
   

   a) On the File menu of MS Visual Studio C++, click New and then click the Projects tab.

   b) In the main window of this tab, select either Win32 Application (for a GUI application) or Win32 Console Application (for a console application).

   c) Specify a location for the project. You can browse for a location or type one directly into the field.

   d) Specify a project name and click OK.

   e) In the resulting dialog box, choose to create an empty project and click Finish. Scan the resulting new project information to make sure it is correct and click OK.

2. Customize the project to work with the WinaXe Plus XDK:
   

   a) On the Project menu, click Settings and then click the C/C++ tab. In the upper left of the tab, from the Settings For drop-down list, select All Configurations. (All of the subsequent settings described in this procedure, regardless of the tab on which they are located, should be for All Configurations).

   b) Also on the C/C++ tab, from the Category drop-down list, select Code Generation. From the Use run-time library drop-down list, select Multithreaded DLL.

   c) Still on the C/C++ tab, from the Category drop-down list, select Preprocessor. In the Additional include directories field, type the WinaXe Plus XDK include path (the location at which you have installed the WinaXe Plus XDK include files).

   d) Click the Link tab of the Settings dialog box. From the Category drop-down list, select Input. In the Additional library path field, type the WinaXe Plus XDK lib path (the location at which you have installed the WinaXe Plus XDK lib files).

   e) When finished, click OK to save the settings and close the dialog box.

3. On the Project menu, click Add To Project and then Files. Add all source files to your project.
   
   
4. On the Project menu, click Settings and then click the Link tab. From the Category drop-down list, select Input. In the Object/library modules field, type the names of the necessary libraries for your X client.
   

   When finished, click OK to save the settings and close the dialog box.

5. On the Build menu, click Build ProjectName (where ProjectName is the name for your project that MS Visual Studio automatically inserts into the menu item).
   
   
6. On the Build menu, click Execute ProjectName (where ProjectName is the name of your project that MS Visual Studio automatically inserts into the menu item).

Using Imakefile and xmkmf

Normally, you should have or create a Makefile and run it in the command line mode (within some development-time environment) to build your application.

Typically a Makefile is created for compiling and building an X application as it involves references to many X11, Xt and Xm library paths, include paths, etc. X Window system developers typically use a utility called 'xmkmf' to generate the Makefiles for building X applications (with the 'make' UNIX system command).

Imakefile is the input to xmkmf, and provides the necessary information specifically required for building an X application, such as the file names, installation directory, library names, paths, include paths, etc.

System-related information, such as specific compiler flags required and basic include and library files and paths, are stored in various system configuration files. These system configuration files are used by xmkmf along with Imakefile to generate the Makefile for an application.

You can write your Makefile from scratch but this way is rather tedious. Or, as a source template, you can use a Makefile from MS Windows SDK (in this case, you may have to make minimal edits in the make file) or UNIX SDK (in this case, you must make some edits in it).

Building an X Client Using a Makefile

You can build an X client using a Microsoft Visual C++ Makefile. To build an X client using a Makefile:

1. Locate the source files for your X application (either files you have written from scratch or ones you have copied from the UNIX host to your PC).
   
   
2. Create a Makefile that contains the proper WinaXe Plus XDK include and library paths.
   
   
3. Build your X application.

Running an X Window Application on Microsoft Windows

To run an X application (on MS Windows or any other operating system) one needs an X server. The X server is available on all UNIX machines, typically supplied by the operating system vendor.

The X servers running on MS Windows (e.g., XServer of WinaXe Plus) can be considered as X Window emulators on MS Windows. They work in two modes: Single Window mode or Multiple Window mode.

In the Single Window mode, all X applications run within one single window. The advantage of this mode is that users get access to a complete X desktop, which gives access to various X applications.

In the Multiple Window mode, each X application runs within a separate window. In this mode, the X Window resource usage on the X server is lower compared to the Single window mode.

For more information, refer to sections Single Window Mode and Multiple Window Mode in chapter Using XServer.)

Setting the DISPLAY Variable

Any X application uses the variable DISPLAY to determine where the X server is located. Therefore, you must set the DISPLAY explicitly even when the application is running on WinaXe Plus (even though you might expect the application to use the X server on the local machine).

If you run an X client from XServer of WinaXe Plus, DISPLAY is set to 127.0.0.1 (i.e. to localhost). If you try to run the X application directly (say by double-clicking the application icon in Explorer) then the value for DISPLAY should be set in the MS Windows environment or passed directly to the X application via the command line in the shortcut. In WinaXe Plus, if you do not specify the command line parameter for DISPLAY, the default value will be 127.0.0.1 (i.e. localhost).

Using Multiple Screens for Local X Clients

The WinaXe Plus XDK lets you use different screens with your local X clients. If the display name is specified as :0.S (where S is the screen number), Xlib assumes that the local client is to be displayed locally to LOCALPC:0.S.

Re-directing Standard Output

Typically, X Window applications are started on UNIX from a terminal. All the standard output calls direct the output to this UNIX terminal. If the application is not started from a terminal, the output goes to /dev/null.

In MS Windows, when an X client application is launched by double-clicking the application icon in Explorer, a command window is started and all the standard output is re-directed to it.

Font Usage

Some X applications might use fonts specifically provided by an X server on the existing system (on UNIX), which need not be provided by the X server running on your PC. If this is the case, then the program might not display the fonts properly or even crash during run-time giving error messages.

The solution to this problem is to replace such fonts with the fonts available in XServer of WinaXe Plus. (Refer to chapter Font Control.)