-- Libsx v1.1 -- The Simple X library by Dominic Giamapolo dbg@sgi.com Introduction: --- What is libsx? Libsx (the Simple X library) is a library of code that sits on top of and to the side of the Athena widget set. Its purpose is to make writing X applications *much* easier. To accomplish this, libsx encapsulates a large portion of the uglier details that arise while programming in X and it fills in some gaps that exist with the Athena Widget set (such as a widget for drawing graphics); libsx tries to simplify the common case down to a single function call with only a few arguments. With libsx, writing a simple program that opens a window, has a few buttons and draws some graphics (lines, circles, bitmaps, etc) is a matter of 5-10 lines of code, including the drawing code. Hello World is 2 lines. More complicated programs that respond to mouse clicks, have buttons, scrollbars, etc, can be written in 25-50 lines of code. Some libraries take the approach of completely hiding whatever they are layering on top of. In contrast, libsx doesn't drastically alter the base abstractions of X, it just packages them in the way they get used most of the time, so that with one function call and a few arguments you get the effect of 10-20 lines of pure X code. Access to the underlying X objects (Window id's, Display pointers, etc) is also possible if necessary, but not required. With libsx, the simple things are simple and the complex things are possible (where have I heard that before? :-). --- Building libsx 1. Edit the libsx_defs file in this directory and set the compiler you'd like to use and any necessary compiler flags. It is important that you take a look in this file and edit things as appropriate. By default it builds for an SGI system (gee, I wonder why that is? :-) If you are on a DECstation, their standard compiler will _not_ work as it is not ANSI compliant (gcc works great though). 2. Type make. This builds the libsx library in the src directory and all the demo programs in the other subdirectories. If you're short on disk space, you can go into any particular directory and type make there. For anything else to work, the libsx/src directory must be compiled first. A word of caution. On some suns that have motif installed from a third party, you'll get lots of warnings about symbols being re-defined when compiling libsx. This is because of an incompatibility in the way the X header files get installed for the motif product (not sure who makes the one I encountered problems with). Anyway, the warnings are innocuous but definitely annoying. Unfortunately I can't seem to make them go away. The demo program that shows most of the features of the library is in the src directory (the executable is called `demo'). The other demo programs demonstrate various aspects of the library. Feel free to use them as skeletons for your own programs. The code has been compiled on wide variety of systems and compilers. It should be mostly clean POSIX code, but I would appreciate hearing about any difficulties you have while compiling. I have personally compiled it cleanly on Sun3's and 4's (SunOS 4.1.1 mind you), SGI (Indigo's, PowerSeries, Onyx, etc), and DECstations 3100/5100's. People on the net have told me that they've gotten it to work on HP-UX, Linux, SVR4.2, AIX 3.2, Sequent/ptx, and numerous other systems. A while ago I compiled it cleanly on a DG Aviion running a very strict version of SVR4. I've used gcc to compile it as well as the native compiler on most of the platforms. The code is ANSI C, so if you don't have an ANSI compiler, sorry.... Libsx also requires the Athena widget set, which isn't as omni-present as I once thought. I guess HP doesn't ship it on all of their systems. I can't help you much there. Bitch at your vendor and tell them to ship a version of the Athena widgets if you don't have it. BTW, there's no Imakefile because I don't understand imake (nor have I made much of an attempt to understand it). Imake seems like overkill for libsx. If someone would like to write an Imakefile, I'd gladly include it in future releases, but it's not likely I'll do it myself. --- More details about libsx The reason I wrote libsx was so that I could whip up simple X programs in not much time and not lots of X code. Originally it started because I wanted an easy way to write programs to draw graphics, but libsx also grew to encapsulate most of the other Athena widgets making all sorts of GUI programs possible The essential idea with libsx is that creating the user-interface should be simple and you should spend your time on the code that implements the logic of your program. In libsx, the core functions that control your application are connected to user-interface elements as callback functions. That is, when the user does something interesting with your interface, your callback function gets called. All of the low level management details are handled for you. Each user interface item (buttons, scrollbars, drawing area's, text entry, etc) only requires one function call to create it. One of the arguments to this creation routine is the name of a callback function that will be called each time an interesting event happens to that widget. For example, when a button or menu item is clicked on/chosen, your callback routine gets called. When a drawing area needs to be redrawn, your callback gets called. The intent of libsx was to ease the common case. For example, here is the code to create and manage a single line string entry with libsx: void str_callback(Widget w, char *string, void *data) { printf("You pressed: %s\n", string); } void main() { .... MakeStringEntry("preset text", 200, str_callback, NULL); } The first function is the callback function that gets called when the user presses return in the widget (and it just prints what the user entered). The call to MakeStringEntry() builds the widget and takes care of setting all the necessary resources and translations for everything to work. In comparison, the equivalent code in regular X calls is on the order of 20-25 lines of code (not counting the callback function which would be the same for both). Another example is drawing graphics. The plain Athena widget set does not provide a drawing area widget (like Motif does). Libsx includes David Nedde's Athena drawing area widget and encapsulates it so that a simple program to open a window and draw some graphics is now reduced to only a few lines of code. More complicated programs build upon the simple model and although creating the user interface may involve more lines of code, the basic model is the same. --- What exactly does libsx provide? Libsx encapsulates the following interface components (all based on Athena widgets, except for the DrawingArea widget which belongs to David Nedde): -- labels -- buttons -- radio button groups and toggle buttons -- single line text entry -- multi-line text entry (full text-edit box) -- scrollbars (horizontal or vertical) -- scrolling lists -- menu buttons (buttons with pop-up menus) -- drawing areas (you can draw in these and also receive mouse/keyboard events if you like) -- multiple form widgets (more advanced, not normally used) After creating the interface components you need, you lay-out your display in a logical fashion. The SetWidgetPos() function lets you specify what widgets are next-to or underneath (or both) other widgets. This avoids hard-coding pixel positions and makes setting up a display pretty simple and quick (though to be fair, some more complicated displays involving centering and such can be difficult if not impossible). You can easily change widget attributes and use different fonts. There are some simple dialog box routines (for getting yes/no answers and getting a single string). Libsx can also open multiple windows (even on different screens) and you can build your own dialog boxes (modal windows) if you like. Libsx also supports obtaining, managing and using colors (either individual colors or an entire 8-bit colormap). Getting specific named colors or colors based on RGB values is as simple as calling a single function (no need to worry about colormaps, color cells, or any of the other junk X makes you worry about). Grabbing the entire colormap is also very easy. Effectively, libsx maintains a lot of state for you; it manages all the grungy X details while providing a cleaner set of routines for your program to use. --- Has libsx traded complexity for functionality? I don't think so. While libsx makes it trivial to write simple programs (as mentioned before, hello world is 2 lines of code), it's also been used to write some fairly substantial programs. I've written 3-D object editors and all sorts of wire-frame/shaded graphics previewers. This afternoon I got fed up with XLess and wrote an equivalent replacement with a real file requestor in about an hour. Most of the time was spent working on the logic of how the program should behave, not the user interface. A friend used it to write a complete 3-D modeling/rendering system. I've written tons of small graphics programs with it (reaction-diffusion and iterated function system demos, etc). I've used it for a contract application that required a simulation of a train set on screen (modeled correctly to scale, etc), and I've been kicking around ideas for some sort of word processor/editor. Libsx is not some all-singing all-dancing type of library, but it does make writing common X applications substantially easier. If you do need the extra confusionality, I mean functionality that X offers, all the standard X functions are available and you have access to the Widget id's, Display pointers, etc. The point is that you don't have to worry about that if you don't want to. --- Where did libsx come from? I developed libsx over the course of about 2 years while in graduate school at Worcester Polytech (in good ole Worcester, Mass.) It all started when I took the grad course in Computer Graphics. I wanted a nice library of routines to deal with all the X crap so I could concentrate on my graphics code. Soon the library started evolving into a much more sophisticated thing and when I became the TA for the graphics course, I beefed it up a lot. When you have 65 undergrads beating on a library you've written, it's got to be solid. The next time that I was TA, I polished up some more rough edges in the library (the stuff the students complained about) and it went through the ringer a second time with about 45 more students. Finally, during the summer of 1993 I added a ton of more functionality to the library so a friend of mine could write his 3-D editor the way it should be written and so I could do some stuff I wanted to do. In September of 1993 I was hired at SGI and I've done a little bit more work on libsx since I've been here (mainly little cleanups and the rudimentary OpenGL support). That is effectively what you see today. I've spent a lot of time deciding how to structure libsx so it would be easy to use but still be open ended. Libsx doesn't try to hide all of X, it just tries to make it more digestable. The library has gotten pretty big at this point, but it should be sufficient to write most types of GUI programs without lots of fuss. I've also spent a lot of time deciding what should and shouldn't be in libsx. It's too easy to throw in everything just because it's easy to do so. Unfortunately that's almost never the right reason to include something. I've tried to pare the design down to the essentials needed to write a useful application. Comments and critiques of the design/approach are welcome (I'd like to hear what others have to say about it or how they would have done it). --- Does libsx hurt performance? I've never really noticed any problems and most of this code was developed originally on a Sun3 (so if it ran ok there it's almost guaranteed to run fine on anything else because a Sun3 is a pretty damn slow machine nowadays :-). Seriously though, once you've created the interface and put up the display, there isn't much libsx code that gets in the way of your application. Many calls go direct to your application and a few are routed through libsx code, but nothing fancy happens there. Using libsx I was able to write programs that interactively manipulated three dimensional objects of up to several hundred vertices with the mouse on a Sparc IPC, so I don't consider performance to be a problem. --- What are the drawbacks to using libsx? The single biggest drawback that I can think of is that some layouts of widgets are not possible because of limitations in the Athena Form widget. For example, it's impossible to create a widget that is centered in a window (to the best of my knowledge the Form widget doesn't support this, example code to the contrary would be greatly appreciated). This is a bit of an annoyance, but usually isn't too much of a problem. Libsx also doesn't let you name your widgets individually, so customization through your .Xdefaults file is possible, but not as flexible as it could be. For example, within a single program, all button widgets get called "button", and all label widgets are called "label" which makes it impossible to invdividually identify widgets in your .Xdefaults file. This means you can't use your .Xdefaults to specify that button X has green text with a purple background while button Y has orange text on a chartruse background with blue highlights. Either all your buttons are purple with green text or they are chartruse with orange text, but not both (hopefully none of them are either :-). This could be fixed by adding a name argument to the MakeXXX() functions, but I'd prefer not to add another argument to those routines. It's also possible to add a SetWidgetName() type of function which is a nice way to do it, but then it really starts to make generating an interface a very complicated thing. Maybe I'll add a SetWidgetName(), but for now I don't think so. The customization thing hasn't been too much of a big deal for me (you can still customize, it's just not as infinitely flexible as the underlying X mechanisms). Presently libsx doesn't offer much support for detecting double clicks. This is because of two reasons. First, X doesn't provide any way for a user to get/set their preferred double-click time (at least as far as I know, example code to the contrary is welcomed) Second, getting sub-second timer accuracy in a portable fashion turns out to be rather problematic. I've just learned that the times() function can be used in a roundabout way to get sub-second timing, but POSIX isn't as well and cleanly supported as one might hope. If you'd like to see code that checks for double-clicks, look in the freq directory at freq.c. It uses times() and seems to work well. --- Where do I go from here? If you haven't already done it, compile libsx. This builds the library itself and numerous demo programs. Then take a look at the demo programs and the code behind them. The main demo program is in the libsx/src directory (and is called `demo'). It demonstrates most of the features of libsx. The other directories contain demos of varying complexity and these are your best starting point for building your own applications. The most complicated application would be `bezier' which lets you interactively play with bezier curves. It's a good framework for handling user-interaction and what not, so have a look at the sources. Feel free to use the demo sources as the basis for your own programs (but of course I'd appreciate it if you give credit where credit is due). The directories freq, creq, and multireq contain code written by a friend of mine, Allen Martin (amartin@wpi.wpi.edu). Freq contains a file requestor function based on libsx. Freq provides a single function GetFile() that lets a user select a file while browsing through the directory hierarchy. Creq is a color chooser utility that lets a user select a color using RGB or HSV values (with sliders and all that jazz). Multi-req is a very nice way to do form-fillout dialogs. Take a look at the sample code in these directories and you should be able to figure out how to make use of the functions. The documentation is always a nice thing to read too (especially since I put so much time into it :-). The documentation isn't in man page style format (yet), sorry about that. It was easier to write this way. The documentation tries to cover all the bases, and with the example code, it shouldn't be hard to figure out (heck, if second year college students can do it with little or no help.... :-). If you have comments/criticism on the docs, let me know. If you'd like to convert the docs into a man page format, I'd also like to know :-) The documentation to start reading first is either libsx_intro or general.libsx.doc. Those introduce you to the basics and then you can go look at the more specific doc files for each of the various areas in libsx. Well, that about sums it up. I hope you find libsx handy and that you can make some use of it. Any comments, questions or other communication can be sent to: Dominic Giampaolo dbg@sgi.com Have Fun! p.s. Oh yeah, I need a disclaimer: This code was written by me, Dominic Giampaolo, and should not be taken to represent Silicon Graphics in any way, shape or form. I've written it on my own time, and for my own purposes. SGI has nothing to do with it, so don't bother them about it. (does that sound legal enough? :-)
