Click here to Skip to main content
Full site     10M members (36.9K online)    
Visit CodeProject.TV
Discuss CodeProject.TV

Programming Xlib with Mono Develop - Part 1: Low-level (proof of concept)

Introduction

This article shows how to access Xlib/X11 API from C# using Mono Develop. A lot of API calls are ready-to-use defined and tested and some challenges are mastered, e.g., transparent bitmap display or modal dialog.

Background

A lot of little helpful Unix/Linux tools are, still today, coded in C/C++ against Xlib/X11. A migration to C# can simplify the maintenance and offer new opportunities. But developers tend to stick to their inherent development environment. On the one hand a change from the GUI development environment Xlib/X11 to GTK or Qt has many advantages, like rapid prototyping or ready-to-use high-level GUI elements. On the othrer hand it requires to leave old habits, to refuse problem-optimized solutions implemented with low-level API and to loose control over some beloved GUI implementation details. Further more programmers see GUI toolkits come and go in rapid succession, esecially on Windows platforms, and are careful with radical changes.

Those, who are willing to change from an old-fashioned language/IDE like C/GCC to a modern one like C#/Mono Develop, might be afraid of the effort or imponderables of switching the GUI development environment simultaneously. But to change the language and to stick to the approved GUI development environment is possible. 

If a programmer don't want to miss the control over the bits and bobs of his GUI, if he relies on the speed and zero overhead costs or if he just has fun or feels comfortable coding against the Xlib/X11, he will find some helpful information to communicate from C# to Xlib/X11 and vice versa provided with this little sample application. 

Using the code

The sample application was written with Mono Develop 2.4.1 for Mono 2.8.1 on OPEN SUSE 11.3 Linux 32 bit EN and GNOME desktop. Neither the port to any older nor to any newer version should be a problem. The sample application's solution consists of two projects (the complete sources are provided for download):

Since C# doesn't support type declarations like

#typedef unsigned long Pixel;

the specific X11 type names can not be emulated. The compromise i found was to define enumerations like

public enum TChar : sbyte {};

but there are no automatic casts and all cast operation must be specified explicitly, like

TChar c1 = (TChar)'a';

Nevertheless, to avoid type mismatch during development some of those types, that might confuse through same names for different value ranges or different names for same value ranges - like long (in C/C++) which is int (in C#) for 32 bit -, are defined as enumeration.

The sample application is also tested with Mono Develop 3.0.6 for Mono 3.0.4 on OPEN SUSE 12.3 Linux 64 bit DE and GNOME desktop, IceWM, TWM und Xfce.

The only difference between the 32 bit and the 64 bit solution is the definition of some types:

public enum TLong : int            {};  // X11    32 Bit: 4 Bytes:                    0 to 65535
//public enum TLong : long        {};  // X11 64    Bit: 8 Bytes: -9223372036854775807 to 9223372036854775807
public enum TUlong : uint        {};  // X11    32 Bit: 4 Bytes:          -2147483647 to 2147483647
//public enum TUlong : ulong        {};  // X11 64    Bit: 8 Bytes:                    0 to 18446744073709551615
public enum TPixel : uint        {};  // X11    32 Bit: 4 Bytes:          -2147483647 to 2147483647
//public enum TPixel : ulong        {};  // X11 64    Bit: 8 Bytes:                    0 to 18446744073709551615
public enum XtArgVal : int        {};  // X11    32 Bit: 4 Bytes:                    0 to 65535
//public enum XtArgVal : long        {};  // X11 64    Bit: 8 Bytes: -9223372036854775807 to 9223372036854775807
public enum XtVersionType : uint    {};  // X11    32 Bit: 4 Bytes:          -2147483647 to 2147483647
//public enum XtVersionType : ulong    {};  // X11 64    Bit: 8 Bytes:                    0 to 18446744073709551615

The application itself has 243 lines of code only. The generic GUI code is released to several Xrw* classes. The function prototypes of the Xlib/X11 and some necessary structures / enumerations calls are defined in the X11lib class. The application shows

  1. a menu bar with 4 buttons, all with callbacks,
  2. a dropdown menu with two entries,
  3. setting the application title and icon title,
  4. an application icon with transparency,
  5. a status bar and
  6. a modal message box. 

somple application on GNOME desktop 32 bit somple application on Xfce 64 bit

Look & feel on GNOME desktop 32 bit                                 and on Xfce 64 bit   

Passing data between managed/unmanaged code

Although the memory management via [MarshalAs(UnmanagedType.*)] is very reliable in Mono, there are some rare cases in which the programmer will (or must) control the behaviour. Some simple rules dealing with the System.Runtime.InteropServices.Marshal class, we can state, are: 

Marshaling data from Xlib/X11 to C#

The first sample to demonstrate one possible turnaround of passing complex structures between managed and unmanaged code is X11lib.XGetClassHint(). This call returns the XClassHint structure on success and the caller is responsible for release of the allocated memory after use - in other words: C# has to release the memory allocated during a X11lib.XGetClassHint()  call.  

// Tested: O.K.
/// <summary> Return the class hint of the specified window to the members of the structure.
/// If the data returned by the server is in the Latin Portable Character Encoding, then the
/// returned strings are in the Host Portable Character Encoding. Otherwise, the result is
/// implementation dependent. To free res_name and res_class when finished with the strings,
/// use XFree() on each individually. </summary>
/// <param name="x11display"> The display pointer, that specifies the connection to the X
/// server. <see cref="System.IntPtr"/> </param>
/// <param name="x11window"> The window to get
/// the class hint for. <see cref="System.IntPtr"/>
/// </param>
/// <param name="classHint"> The class hint
/// to get. <see cref="X11._XClassHint"/> </param>
/// <returns> Nonzero on success, or zero otherwise. <see cref="X11.TInt"/> </returns>
[DllImport("libX11", EntryPoint = "XGetClassHint")]
extern private static TInt _XGetClassHint (IntPtr x11display, IntPtr x11window,
                                           ref _XClassHint classHint); 
// Tested: O.K.
/// <summary> Return a XClassHint structure of the specified window to the members of the
/// structure. If the data returned by the server is in the Latin Portable Character Encoding,
/// then the returned strings are in the Host Portable Character Encoding. Otherwise, the result
/// is implementation dependent. </summary
/// <param name="x11display"> The display pointer, that specifies the connection to the X server.
/// <see cref="System.IntPtr"/> </param>
/// <param name="x11window"> The window to get the class hint for. <see cref="System.IntPtr"/>
/// </param>
/// <param name="classHint"> The class hint to get. <see cref="X11.XClassHint"/> </param>
/// <returns> Nonzero on success, or zero otherwise. <see cref="System.Int32"/> </returns>
public static int XGetClassHint (IntPtr x11display, IntPtr x11window, out XClassHint classHint)
{
    _XClassHint _classHint = _XClassHint.Zero;
    
    if (_XGetClassHint (x11display, x11window, ref _classHint) == (TInt)0)
    {
        // Clean up unmanaged memory.
        // --------------------------
        // Typically: _classHint.res_name == IntPtr.Zero
        // Freeing a IntPtr.Zero is not prohibited.
        // Use first member (at offset 0) to free the structure itself.
        XFree (_classHint.res_name);
        
        classHint = XClassHint.Zero;
        return 0;
    }
    else
    {
        classHint = new XClassHint();
        // Marshal data from an unmanaged block of memory to a managed object.
        classHint.res_name  = (string)Marshal.PtrToStringAnsi (_classHint.res_name );
        classHint.res_class = (string)Marshal.PtrToStringAnsi (_classHint.res_class);
        
        // Clean up unmanaged memory.
        // --------------------------
        // Freeing a IntPtr.Zero is not prohibited.
        // First structure member (at offset 0) frees  the structure itself as well.
        XFree (_classHint.res_name);
        XFree (_classHint.res_class);
        
        return 1;
    }
}

The solution I chose divides the call into two parts. The C# method XGetClassHint() calls the native code via the renamed function _XGetClassHint() and postprocesses the returned structure. To be able to release the allocated memory, the structure returned from native code is defined using the two memory pointer res_name and res_class.

/// <summary> Internal memory mapping structure for XClassHint structure. </summary>
/// <remarks> First structure element is on offset 9.
/// This can be used to free the structute itself. </remarks>
[StructLayout(LayoutKind.Sequential)]
private struct _XClassHint
{
    /// <summary> The application name (might be changed during runtime). </summary>
    /// <remarks> Must be freed separately. </remarks>
    public IntPtr res_name;
    /// <summary> The application class name (should be constant during runtime). </summary>
    /// <remarks> Must be freed separately. </remarks>
    public IntPtr res_class;
    
    public static _XClassHint Zero = new _XClassHint ();
}

And the structure returned to the application is defined using two managed strings of the same name.

[StructLayout(LayoutKind.Sequential)]
public struct XClassHint
{
    [MarshalAs(UnmanagedType.LPStr)] public string res_name;
    [MarshalAs(UnmanagedType.LPStr)] public string res_class;
    
    public static XClassHint Zero = new XClassHint ();
}

The C# method XGetClassHint() manages conversion and memory release explicit and offers full control over the two memory pointer res_name and res_class.

Marshaling data from C# to Xlib/X11

The second sample i will show is the implementation of XrwGraphic class, which provides the application with bitmap graphics that are very easy to handle and support transparency (actually based on white color pixel #FFFFFF). The implemented procedure to apply a transparent bitmap to a drawable includes:

Although the XrwGraphic class is not optimized for speed, memory usage or different color depth (currently tested only with true color 24 bit display) this class took the longest time of all provided classes to get it work - because of insufficient information about the procedure to be implemented and the details to be considered. 

The sample application uses XrwGraphic class three times and shows transparent graphics for application icon, status bar label and message box label. To provide a transparent graphic for application icon some of the steps mentioned above are done by the X11lib.XSetWMHints() automatically, but the procedure in general is the same.

The creation of the two XImage structures for color graphic and transparency mask from a System.Drawing.Bitmap uses managed byte[] to process all computation in managed code and Marshal.AllocHGlobal as well as Marshal.Copy to transfer the conversion result to unmanaged memory.

// ### Allocate bitmap conversion data.
// The bitmap color data. Use a temporary managed byte array for speed.
byte[]    graphicData            = new byte[_height * _width * colorPixelBytes];
// The bitmap transparency data. Use a temporary managed byte array for speed.
byte[]    maskData            = new byte[_height * maskLineBytes];
// Quick access to current line's color pixel.
int        graphicPixelIndex    = 0;
// Quick access to current line's mask pixel.
int        maskPixelIndex        = 0;
// Reduce slow calls to bmp.GetPixel (x,y).
Color   pixelColor            = Color.Black;
// Determine whether transparency is required.
bool    transparency        = false;
 
// ### Convert bitmap.
for (int y = 0; y < _height; y++)
{
    for (int x = 0; x < _width; x++)
    {
        graphicPixelIndex = (y * _width + x) << 2;
        maskPixelIndex    = y * maskLineBytes + (x >> 3);
        pixelColor = bmp.GetPixel (x,y);
 
        graphicData[graphicPixelIndex + 0] = pixelColor.B; // B
        graphicData[graphicPixelIndex + 1] = pixelColor.G; // G
        graphicData[graphicPixelIndex + 2] = pixelColor.R; // R
        graphicData[graphicPixelIndex + 3] = pixelColor.A; // A
            
        if (pixelColor. B == 255 && pixelColor.G == 255 && pixelColor.R == 255)
        {
            byte summand = (byte)(1<<(x % 8));
            maskData[maskPixelIndex] = (byte)(maskData[maskPixelIndex] + summand);
            transparency               = true;
        }
    }
}
 
// ### Create XImage.
// The bitmap color data.
IntPtr    graphicDataHandle = Marshal.AllocHGlobal(graphicData.Length);
// Allocate not movable memory.
Marshal.Copy (graphicData, 0, graphicDataHandle, graphicData.Length);
// Client side XImage storage.
_graphicXImage = X11lib.XCreateImage (_display, visual, (TUint)_graphicDepth,
                                      X11lib.TImageFormat.ZPixmap, (TInt)0,
                                      graphicDataHandle, (TUint)_width, (TUint)_height,
                                      IMAGE_PADDING, ASSUME_CONTIGUOUS);
if (_graphicXImage == IntPtr.Zero)
    throw new OperationCanceledException ("Image creation for graphic failed.");
            
if (transparency == true)
{
    IntPtr    maskDataHandle = Marshal.AllocHGlobal(maskData.Length);
    // The bitmap bitmap transparency data.
    Marshal.Copy (maskData, 0, maskDataHandle, maskData.Length);
    // Allocate not movable memory.
    // Client side storage.
    _transpXImage = X11lib.XCreateImage (_display, visual, 
       (TUint)_clipDepth, X11lib.TImageFormat.XYBitmap,
       (TInt)0, maskDataHandle, (TUint)_width, (TUint)_height,
       IMAGE_PADDING, ASSUME_CONTIGUOUS);
    if (_transpXImage == IntPtr.Zero)
        throw new OperationCanceledException (
           "Image creation for transparency mask failed.");
}

The managed byte[] for color graphic and transparency mask  are disposed by the garbage collector. The Xlib/X11 resources like XImages, XPixmaps and GCs must be destroyed manually via  X11lib.XDestroyImage(), X11lib.XFreePixmap() and X11lib.XFreeGC().

Widget Set 

To prevent a big code mixup and to "don't repeat myself", generic GUI code is released to several Xrw* classes. The inheritance tree mainly follows the ideas of the "Athena Widget Set" with a little influence of the "Motif Widget Set" and GTK but is neiter complete nor fully functional. The base widgets, that should not be instantiated, are:

On top of these widgets some simple widgets, shells and menu widgets are implemented.  All simple widgets  are used in the sample application. They are:

The shell widget used in the  sample application is XrwApplicationShell. All other shell widgets should not be instantiated.  The shell widgets are:

Based on XrwDialogShell a XrwMessageBox shell is implemented, that is also used in the sample application.

All  menu widgets are used in the sample application too.

Event loop and events

The application's event loop is implemented in the XrwApplicationShell class. I would call it "experimental" but it works fine for the current requirements.  The event loop is divided into the infinite loop RunMessageLoop() and the single event processing DoEvent().

/// <summary> Run the application's message loop. </summary>
protected void RunMessageLoop ()
{
    bool proceed = true;
    while(proceed == true)
    {
        try
        {
            proceed = DoEvent();
        }
        catch (Exception e)
        {
            Console.WriteLine (CLASS_NAME + ":: RunMessageLoop () ERROR: " + e.StackTrace);
        }
    }
    return;
}
 
/// <summary> Process the topmost event and remove it from the event queue. </summary>
/// <returns> True if efent processing must contionue, false otherwise. </returns>
public bool DoEvent()
{
    ...
}

The DoEvent() method currently processes ConfigureNotify, Expose, KeyPress, KeyRelease, ButtonPress, ButtonRelease, FocusIn, FocusOut, EnterNotify, LeaveNotify, MotionNotify and ClientMessage events.

Every windowed widget can receive the X11 events that are registered for the underlying window via X11lib.XSelectInput(). Currently XrwSimple (including its derived simple widgets), XrwOverrideShell (including its derived XrwSimpleMenu), XrwTransientShell (including its derived XrwDialogShell and XrwMessageBox) and XrwApplicationShell register X11 events for their underlying windows. XrwTransientShell and XrwApplicationShell interact with the windows manager and register eleven X11 events. 

X11lib.XSelectInput(_display, _window,
                    EventMask.StructureNotifyMask    | EventMask.ExposureMask    |
                    EventMask.ButtonPressMask        | EventMask.ButtonReleaseMask    |
                    EventMask.KeyPressMask        | EventMask.KeyReleaseMask    |
                    EventMask.FocusChangeMask        | EventMask.EnterWindowMask    |
                    EventMask.LeaveWindowMask        | EventMask.PointerMotionMask    |
                    EventMask.SubstructureNotifyMask);

The XrwSimple and the XrwOverrideShell register the same X11 events except EventMask.StructureNotifyMask. They don't neet to receive ConfigureNotify X11 events because all configuration, mainly the size adaption, is done

  1. starting at the shell widget that interacts with the windows manager receiving the ConfigureNotify event,
  2. goes forward through the complete widget hierarchy - including all XrwSimple or XrwOverrideShell and derived widgets as well as all windowless widgets - to calculate the preferred size of all widgets calling PreferredSize() and
  3. goes back through the complete widget hierarchy of this shell to set the assigned geometry calling SetAssignedGeometry().

The DoEvent() method determines the best receiver of the X11 event and translates the X11 event into a C# event, that is invoked. The ClientMessage event is an easy sample for this proceeding.

else if (xevent.type == XEventName.ClientMessage &&
         xevent.ClientMessageEvent.ptr1 == _wmDeleteMessage)
{
    // Window menager is clowing a window.
    bool childAddressed = false;
    
    // ClientMessageEvent events might go to associated transient shells.
    foreach (XrwTransientShell transientShell in _associatedTransientShells)
    {
        if (xevent.ClientMessageEvent.window == transientShell.Window)
        {    
            transientShell.OnClose (new XrwClientMessageEvent (ref xevent.ClientMessageEvent));
            childAddressed = true;
            break;
        }
    }
    if (childAddressed == true)
        return true;
    // Subsequent ClientMessageEvent events might go to windowed children.
    if (xevent.ClientMessageEvent.window == this.Window)
        OnClose (new XrwClientMessageEvent (ref xevent.ClientMessageEvent));
}

The event processing checks if the event is addressed to any transient shell of the application first. Otherwise it processes the event for the application shell. The transformation from an X11 event to a C# event is done by instantiation of the appropriate wrapper class, e. g. new XrwClientMessageEvent (ref xevent.ClientMessageEvent), and this instance is passed to the invocation of the C# event, e. g. transientShell.OnClose(). 

To make sure, that all transient shells of an application are captured by the event processing, the registration of a transient shell is essential. Currently neither the XrwTransientShell class nor any derived class does this automatically, so the programmer is responsible for it.

// <summary> Handle the ButtonPress event. </summary>
/// <param name="source"> The widget, the ButtonPress event
/// is assigned to. <see cref="XrwRectObj"/> </param>
/// <param name="e"> The event data. <see cref="XawButtonEvent"/> </param>
/// <remarks> Set XawButtonEvent. Set result to nonzero to stop further event processing. </remarks>
void HandleMessageBoxButtonPress (XrwRectObj source, XrwButtonEvent e)
{
    ...
    this.AddTransientShell (messageBox);
    ...
}

Specifics of widgets, that interact with the windows manager 

All shell widgets, that interact with the windows manager, are decorated with a frame and can be closed with the application's icon menu item "Close" on the left or the close button on the right of the windows title bar.

To ensure a controlled and complete shell close, that includes the disposal of unmanaged resources, the shell must be notified about the close event triggered by the frame. To achieve this, the XrwTransientShell and the XrwApplicationShell register the _wmDeleteMessage.

/* Hook the closing event from windows manager. */
_wmDeleteMessage = X11lib.XInternAtom (_display,
                                       X11Utils.StringToSByteArray ("WM_DELETE_WINDOW\0"), false);
if (X11lib.XSetWMProtocols (_display, _window, ref _wmDeleteMessage, (X11.TInt)1) == 0)
{
    Console.WriteLine (CLASS_NAME + "::InitializeApplicationShellResources () WARNING: " +
                       "Failed to register 'WM_DELETE_WINDOW' event.");
}

Actually the windows manager supports three protocols, WM_TAKE_FOCUS, WM_SAVE_YOURSELF, WM_DELETE_WINDOW, and the X11lib.XInternAtom() obtains the protocol to register it with X11lib.XSetWMProtocols() to the shell's underlying window. 

General widget event handling

All widgets, that register X11 events with X11lib.XSelectInput(), are notified about these X11 events, translated to C# events by the DoEvent() method. If the application want to process events, callback methods can be registered to the event handler introduced by the XrwRectObj widget. 

/// <summary> Register expose event handler. </summary>
public event ExposeDelegate Expose;
/// <summary> Register KeyPress event handler. </summary>
public event KeyPressDelegate KeyPress;
/// <summary> Register KeyRelease event handler. </summary>
public event KeyReleaseDelegate KeyRelease;
/// <summary> Register ButtonPress event handler. </summary>
public event ButtonPressDelegate ButtonPress;
/// <summary> Register KeyPress event handler. </summary>
public event ButtonReleaseDelegate ButtonRelease;
/// <summary> Register FocusIn event handler. </summary>
public event FocusInDelegate FocusIn;
/// <summary> Register FocusOut event handler. </summary>
public event FocusOutDelegate FocusOut;
/// <summary> Register Enter event handler. </summary>
public event EnterDelegate Enter;
/// <summary> Register Leave event handler. </summary>
public event LeaveDelegate Leave;
/// <summary> Register Motion event handler. </summary>
public event MotionDelegate Motion;

Now it is straight forward to obtain event notification as usual in C#, for example cbw1.ButtonPress += HandleCloseMenuButtonPress.

Specifics of widgets, that don't interact with the windows manager

Some widgets have predefined/build in event handler. The XrwSimpleMenu widget, for example, uses the FocusOut and ButtonRelease events to hide its override shell, the Motion event to set/unset the mouse-over effect for the menu entries and the ButtonPress event to start a menu action. The Motion, ButtonPress and ButtonRelease events are handled by the XrwSimpleMenu widget instead of the XrwSme widgets, besause the XrwSme widgets have no own window (to safe resources) and therefore they don't receive events. 

Or the XrwCommand widget, as another example, uses the Enter and Leave events to to set/unset the mouse-over effect.

/// <summary> Initialize local ressources for all constructors. </summary>
private void InitializeCommandRessources ()
{
    ...
            
    Enter += HandleEnter;
    Leave += HandleLeave;
}

Triggering X11 events

To achieve the mouse-over effect, XrwSme widgets, XrwCommand widgets and XrwMenuButton widgets change the fill color. To make this change visible, an X11 Expose event has to be sent. The static convenience method SendExposeEvent() of the XrwObject widget makes this very easy to handle.

/// <summary> Send an expose event to the indicated window. </summary>
/// <param name="display">The display pointer, that specifies
/// the connection to the X server. <see cref="IntPtr"/> </param>
/// <param name="receiverWindow"> The window to adress
/// the expose event to. <see cref="IntPtr"/> </param>
/// <param name="dispatcherWindow"> The window to send
/// the expose event to. <see cref="IntPtr"/> </param>
/// <returns> Nonzero on success, or zero otherwise (if the conversion
/// to wire protocol format failed). <see cref="X11.TInt"/> </returns>
public static TInt SendExposeEvent (IntPtr display, IntPtr receiverWindow,
                                    IntPtr dispatcherWindow)
{
    XEvent       eE         = new XEvent();
    eE.ExposeEvent.count    = 0;
    eE.ExposeEvent.display    = display;
    eE.ExposeEvent.window    = receiverWindow;
    eE.ExposeEvent.type        = XEventName.Expose;
    
    return X11lib.XSendEvent (display, dispatcherWindow, (TBoolean)1,
                              (TLong)EventMask.ExposureMask, ref eE);
}

Modal dialog

The division of the event loop into RunMessageLoop() and DoEvent() enables modal shells to take over the event handling by implementing their own infinite loop, e. g., the XrwMessageBox.

/// <summary> Run the message box modal. </summary>
/// <returns> The pressed button. <see cref="XrwDialogShell.Result"/> </returns>
/// <remarks> To use the message box non-modal register at least event handler
/// to WmShellClose and to DialogShellEnd and call Show(). </remarks>
public XrwDialogShell.Result Run ()
{
    this.Show();
    
    // Take over the event loop processing.
    while (_result == XrwDialogShell.Result.None)
        ApplicationShell.DoEvent ();
 
    return _result;
}

Points of Interest

It was challenging, instructive and funny driving the same road as Qt, GTK, or wxWidget developers did years before. It offers a smart migration path from C/C++ to C# where developers can keep achievements they don't want miss and conquer new ground simultaneously.

History

 
You must Sign In to use this message board.
Search 
Per page   
First Prev Next
QuestionDifficulty besides wrapping the C++ class Pin
Shawn-USA		1 May '13 - 17:49 2 
Last Visit: 31 Dec '99 - 18:00     Last Update: 13 May '13 - 18:05Refresh1

Last Updated 8 May 2013 | Advertise | Privacy | Terms of Use | Copyright © CodeProject, 1999-2013