XSTEP Reference Manual

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.1.
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, BSD and Unix-like systems, with GCC compiler, 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. Most problems in the XSTEP compilation are related to compiler, for example, with standard CC in IRIX, XSTEP 3.5 will not compile. If you change the source code to compile, XSTEP 3.5 will not open any window! but a beta version of XSTEP 4.0 will work with little modifications. If you have problems with colors and XSTEP 3.5 in big-endian machines, you can change your color depth to 8 or less bits.
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.5, 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. If you want to install XSTEP 4.x in the future, you must recompile old applications with XSTEP 3.5.1, or yours XSTEP 3.x applications will crash when you install the new libxstep.so.4 in your system!
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. In XSTEP 3.5.1 this header is optional: if you really have older XSTEP 2.x applications, you must copy the xstep-port.hfile to your /usr/local/include directory.
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:

button: redesigned to support sub window based events and resizable windows. In version 3.5, you can put a pixmap in a button.

box: created to enable any X11 function or independent application work in a subwindow inside a XSTEP resizable window.

check: a new widget, for check boxes lists (the checkbox look was changed in version 3.3 to be more compatible with the NeXTSTEP look).

radio: an old widget, for radio boxes lists, in fact is just a checkbox w/ modified look.

menu: a new widget for menus. if you click with the right button of your mouse, you can open a popup menu.

popup: a new widget for popups, based in menu, for selection lists.

edit: changed to support focusin/focusout of keyboard in a sub window, with checksums for better and faster redraw events. The keyboard work just how in the version 2.x, supporting a subset of the ISO/ECMA KEYSYMs defined in X11R4, in any PC/Workstation US keyboard, to create these international characters:

a e i o u y n c

grave (`) à è ì ò ù ý ç

acute (') á é í ó ú

circumflex(^) â ê î ô û

tilde(~) ã õ ñ

diaeresis(") ä ë ï ö ü ÿ

This support is available too for NeXTaw-0.5.1 in http://xstep.dhs.org. In recent versions, a verification function can be used to change and process the typed data when you change to other widget.
label: changed to just manage label texts in sub windows and support for resizable windows.

window: changed to work better with window managers, now support a more "soft" close window and resizable windows automatically (if a window is resized, all widgets are moved or resized). in version 3.2 and later, the first XSTEP window of any application will generate the correct informations to be docked in the Window Maker's dock.

scroll: fully redesigned to work [very-very-very] better than versions 1.x and 2.x, with many sub windows and support for resizable windows and multiple lists. In version 3.2 all bugs are fixed and now XSTEP can handle lists with multiple columns of text, 'double click' and 'right button click' functions! :)

In version 3.3 many small bugs are corrected and new group and xyscroll widget are introduced:

group: you can separate groups of widgets in the group sub window.

xyscroll: you can scroll a group of widgets in horizontal and/or vertical plane. This widget will replace all other scroll widgets in future versions.

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 )

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':
#include <xstep.h>
void xmain(int i,char **p) {
    window_create(0,0,400,180,"My First Application!");
    defaultfont=helvetica24b;
    label_create(0,0,0,0,"Hello World!",gray,up);
}
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
CPUFLAGS = -Wall -O3 -m486
   INCDIR = -I/usr/X11R6/include -I/usr/local/include
   LIBDIR = -L/usr/X11R6/lib -L/usr/local/lib
     LIBS = -lX11 -lxstep
   CFLAGS = $(CPUFLAGS) $(INCDIR)
LDFLAGS = $(LIBDIR) $(LIBS)
TARGETS = xhelloworld
all: $(TARGETS)
clean:
    -rm -f $(TARGETS) core
with this Makefile, you can just type 'make' to compile :)
If you write others small applications, just add these to TARGETS variable inside your Makefile:
TARGETS = xhelloworld xpagemaker xphotoshop
and then retype 'make' :)
A more complete reference of XSTEP programming can be found in:

window

buttons

check and radio

text edition

label

periodic table of XSTEP labels

popup

scrollable list

scrollable multiple lists

resizable window

drawable box

groups

animations

graphic context with groups

graphic context with windows

x/y scroll box

dialog box

xtree struct

pixmaps

fine tune

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 site.

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

This software contains parts developed and copyrighted by Marcelo Samsoniuk, Gleicon S. Moraes, Paulo Cesar Pereira de Andrade, Joao Carlos Mendes Luis, Claudio Matsuoka, Everton da Silva Marques, Alexandre Nunes, Cassio, Augusto Cesar, Joicimar Aguiar Rocco, Cesar Ricardo Gimenes, Marcello Barisonzi, Tito Ragusa, Lucas Mendes and many others.

FOR MORE INFORMATION

Many versions of XSTEP and related applications can be found in:
http://xstep.sourceforge.net
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'.

	a	e	i	o	u	y	n	c
grave (`)	à	è	ì	ò	ù	ý		ç
acute (')	á	é	í	ó	ú
circumflex(^)	â	ê	î	ô	û
tilde(~)	ã			õ			ñ
diaeresis(")	ä	ë	ï	ö	ü	ÿ