XSTEP Reference Manual

Copyright (c) 1996-2000 by Marcelo Samsoniuk and collaborators.

INTRODUCTION

This is the XSTEP Referece Manual, a new and improved documentation for XSTEP, a faster and small toolkit, designed to make easy the creation of C/C++ applications for any UNIX running the X Window System (version 11, release 4 or later), with the look and feel of NeXTSTEP. This documentation was revised to be released with XSTEP version 3.5.

XSTEP is a copyrighted public software and you are welcome to redistribute, modify and use for any purpose, subject to the conditions listed in the Library GNU Public License (LGPL).

INSTALLING XSTEP
To compile the XSTEP library in your machine, you must have the GNU C compiler, the GNU or BSD make and all basic X Window System headers and libraries. In many Linux and BSD systems, running in little-endian 32 bits machines, the compilation will be very easy, just type 'make' to compile. In other system types, a variable work will be required, in many cases just personalize the 'Makefile' in the 'library' directory to your system (if you send these modifications for me, I can add it into the next XSTEP version ;)

The XSTEP version 3.x was designed to work in UNIX-like systems, but with the correct set of tools and many modifications, you can compile by hand static XSTEP applications in UNIX-unlike systems. Of course, the targeted system *must* have the X libraries and headers to compile and run applications and these applications must be conected to a X server.

After compiled, you have a shared library to install in your system. If you're with the root account of your machine, just type 'make install' and the library will be installed in the /usr/local/lib directory (a small set of headers will be installed in the /usr/local/include directory). If you must deinstall all files, just type 'make uninstall' and the library and all headers will be erased from /usr/local/lib and /usr/local/include.

The installed library is compatible with binary applications compiled with XSTEP versions 3.4, 3.3, 3.2 and 3.2.1. Many applications compiled with XSTEP version 3.1 will work, but many of then can require a recompilation to work.

Applications created before XSTEP version 3.1 don't use this shared library, but you can recompile these applications with the last version of XSTEP. To compile, you must edit the source file of the old application and replace

    #include <xstep.h>

to:

    #include <xstep-port.h>

This is a header with macros to convert the old XSTEP syntax to XSTEP 3.5 syntax.

A demonstration of XSTEP 2.0 and XSTEP 3.0 applications running with XSTEP 3.5 library is available in the 'contrib/demos' directory. Other demonstrations will show how work with XSTEP in real applications, with many complete examples. To see these demos, you must have the XSTEP 3.5 compiled and installed, then just type:

    cd contrib
    make

And many demonstrations will be compiled. If you find these demos usefulls, you can type 'make install' to install all applications in your /usr/local/bin directory, to deinstall, just type 'make uninstall'. All specific Linux applications will work only in a Linux system with a compatible /proc filesystem, if your system isn't a Linux system, applications in directory 'contrib/linuxtools' will not be compiled.

If you need a more easy examples, please check the 'examples' directory, you will find many short and clean examples of all XSTEP 3.5 widgets. These examples really don't make anything usefull, but you can see all examples typing:

    cd examples
    make
    make show
 

WHAT'S NEW
There are many good modifications in version 3.x. All widgets are subwindows inside others X subwindows and have a enhanced and more complete set of events managed by your X server, with better performance than old versions of XSTEP. All widgets have serial numbers, for intelligent redraws by demand, and now any widget can be resized on demand. New widgets are created or others are fully redesigned to work better:
 
a
e
i
o
u
y
n
c
grave (`)
à
è
ì
ò
ù
ý
 
ç
acute (')
á
é
í
ó
ú
 
 
 
circumflex(^)
â
ê
î
ô
û
 
 
 
tilde(~)
ã
 
 
õ
 
 
ñ
 
diaeresis(")
ä
ë
ï
ö
ü
ÿ
 
 
In version 3.3 many small bugs are corrected and new group and xyscroll widget are introduced: In version 3.3 all widgets are created with a default GC (X graphic context) and the creator function return a pointer to a xtree object, to avoid references to 'treestk'.

In the version 3.4, XPM pixmaps are supported and the license was changed from GPL to LGPL. Many bugs corrected, many documentation and examples are now part of XSTEP 3.5 package. This package is available in the standard site ( http://xstep.dhs.org ), in any sunsite mirror ( ftp://sunsite.unc.edu/pub/Linux/libs/X/clibs ) or in the new XSTEP CVS server:

    export CVSROOT=":pserver:anonymous@darkstar.dhs.org:/cvsroot"
    cvs login
    cvs co xstep-3.5
 

RESIZABLE WIDGETS
Many widgets can be automatically moved or resized. To enable automatic motion, just use negative coordinates for (x,y) positions relative to bottom right corner of window. For automatic resize, use negative coordinates for (w,h) sizes, relative to bottom right corner of window. Please check: motion and resize are exclusive options: if your widget is moved, it can't be resized; if your widget is resized, it can't be moved :)

examples of moveable widgets:

button_create( 4, 4,200,21,"upper/left",0);
button_create(-4, 4,200,21,"upper/right",0);
button_create( 4,-4,200,21,"bottom/left",0);
button_create(-4,-4,200,21,"bottom/right",0);
examples of resizable widgets:
button_create(4,4, -4,-4,"unfixed width/height",0);
button_create(4,4,200,-4,"unfixed height",0);
button_create(4,4, -4,21,"unfixed width",0);
button_create(4,4,200,21,"fixed and unmovable",0);
You can create many combinations, please see more sample codes in XSTEP examples.
CHECKSUMS
Many widgets have checksums of these structures and can be automatically redrawed, if you modify any data, without intervention of your program. For many widgets, checksums are automatically created, if you modify any data structure, you can force a checksum verify with:
broadcast++;
or a continuous checksum verification (for animation) with:
animate=1;
you can see samples of animation and checksums of data in XSTEP examples.
CREATING APPLICATIONS
To create XSTEP applications you must compile and install the XSTEP library, then you can create a C file, like 'xhelloworld.c': Warning! XSTEP 3.x applications start with xmain(), not main()!

The compilation if X applications by hand is a hard task and is high recommendable to you use a Makefile file, like this:

    CC  = gcc
CFLAGS  = -Wall -O3 -pipe
CFLAGS += -I/usr/X11R6/include -I/usr/local/include
CFLAGS += -L/usr/X11R6/lib -lX11
CFLAGS += -L/usr/local/lib -lxstep
APPLICATIONS = xhelloworld

all: $(APPLICATIONS)

clean:
    rm $(APPLICATIONS)

with this Makefile, you can just type 'make' to compile :)

If you write others small applications, just add these to APPLICATIONS variable inside your Makefile:

APPLICATIONS = xhelloworld xpagemaker xphotoshop
and then retype 'make' :)

A more complete reference of XSTEP programming can be found in:

BUGS
XSTEP is designed to run in any UNIX machine with X11R4 or later. For now, XSTEP was tested in many Linux and BSD systems (all little-endian, 32 bit machines), running with X11R6.x, without problems, but you can have problems in other UNIX machines and *many* problems in non-UNIX machines.

Well, all bugs will be corrected in the future XSTEP version 4.0, now in development. If you're interested in work with XSTEP 4.0, please check the XSTEP CVS server:

    export CVSROOT=":pserver:anonymous@darkstar.dhs.org:/cvsroot"
    cvs login
    cvs co xstep-4.0

TODO
Nothing to do, XSTEP 3.x development is really stopped! If you want do create new widgets, please get the version 4.0, available in the XSTEP CVS server (see http://xstep.dhs.org for more informations about XSTEP 4.0). A object oriented version of XSTEP 4.0 in C++ is planned by CRG, you can subscribe the XSTEP Development List to get more informations.
CREDITS
The source code of XSTEP library, applications and examples in this package are developed by Marcelo Samsoniuk, with the help of many people in the internet:

Paulo Cesar Pereira de Andrade make many important suggestions to all versions of XSTEP:

  • check events without stop main loop (w/XCheckMaskEvent)
  • the fast compilation in separated objects
  • modifications in the Makefile to compile in FreeBSD
  • group multiple expose events (w/XSetClipRectangles)
  • the creation of widgets inside subwindows (this is the most important enhancement in the XSTEP 3.0! :)
  • the implementation of WM_DELETE_WINDOW
  • others suggestions very complex for me in the early versions, many of then implemented in XSTEP 3.x :)
  • Joao Carlos Mendes Luis make the suggestion to call xwininfo in xdemo (XSTEP 3.0), to get the window-id of the target window.

    Claudio Matsuoka make the suggestion of replace atol() by strtol() to get the window-id of the target window in hexadecimal and find a problem in the scroll widget of XSTEP 3.0. He find an error in the scrollbox of this version too.

    Everton da Silva Marques find a problem with XSTEP 3.1 and the ld.so.conf in Linux Red Hat (this linux don't have an entry for /usr/local/lib :) and a small error in the demonstration application in this XSTEP version.

    Alexandre Nunes make many suggestions for the creation of XSTEP based applications for Linux Slackware, like xstepuser, xsteptask, xsteppack and many others. He is the administrator of XSTEP CVS server and is now working in the development of XSTEP 4.0.

    Cassio make suggestions to change the look and feel of checkbox widget to be more like NeXTSTEP and find many problems in the button, edit and scroll widgets in the XSTEP version 3.2 (the problem with scroll widget is really uncorrectable and the good way is replace scroll widget code by the xyscroll widget in future versions). He created all the source code for xstepfiles, available in the directory 'contrib/files' (other X applications based in WINGa are available in http://members.linuxstart.com/~cassio).

    Augusto Cesar  compiled XSTEP in your OpenBSD and make a suggestion to remove the main() function from XSTEP library (this suggestion can be implemented in XSTEP 4) and translate the documentation of XSTEP 3.2.1 to portuguese.

    Joicimar Aguiar Rocco make the suggestion of verification function in the edit widget (XSTEP 2.0) and worked in the academia application, based in a similar application developed in Delphi language for Windows.

    Cesar Ricardo Gimenes (CRG) for many years make many suggestions for XSTEP 3.x and now is the maintainer of XSTEP++ (the OO version of XSTEP 4.0).

    Marcello Barisonzi is a recent collaborator to XSTEP 3.5: fix a bug in the menu code and create a new widget, the finetune_create(), available in this version.

    Gleicon S. Morae make many suggestions, find many bugs in XSTEP and is the creator of the network code in xstepbox and xstepnet, available in the directory 'contrib/linuxtools'. In the XSTEP 4.0, he created the base code for XSIE, a high-end image support for XSTEP applications.

    Well, I don't remember of all names and details, but many thanks for all other colaborators worldwide and for all XSTEP users! :)

    FOR MORE INFORMATION
    Many versions of XSTEP and related applications can be found in:
    http://xstep.dhs.org
    Suggestions, comments and problem reports related to XSTEP are welcome and can be send
    to XSTEP development list (you must be a subscriber to post, look at XSTEP page how be a subscriber).

    A good reference in portuguese is the paper 'Programacao XSTEP'.