The following function allows you to specify how the display should be layed out. It lets you logically position the components you created with the MakeXXX() functions. You will use this function to layout the arrangement of your buttons, labels and drawing area(s).
void SetWidgetPos(Widget w, int where1, Widget from1, int where2,Widget from2);
This function lets you position a Widget in your window. The idea is that you specify logical placement of the Widget (i.e. place it to the right of this widget, and under that widget). Many layouts are possible, and you can even specify that you don't care where a specific widget is placed.
There are three types of placement. You can place a widget to the right of another widget with PLACE_RIGHT. If the argument "where1" is PLACE_RIGHT, then the Widget "w" will be placed to the right of the Widget "from1". If "where1" is equal to PLACE_UNDER, "w" will be placed under the widget "from1". The same holds true for the argument "where2" and Widget "from2". Having two arguments is necessary to be able to unambiguously specify where you want components placed in the display. If you don't care about where a widget is placed, you can use NO_CARE for the `where' argument and a NULL value for the `from' argument.
Generally, the first widget created need not be specified, it will always be in the top left corner. Other widgets can the be placed relative to that widget. For example, if you created 4 widgets (w[0] through w[3]) and wanted to arrange them in a column, you would do the following :
SetWidgetPos(w[1], PLACE_UNDER, w[0], NO_CARE, NULL);
SetWidgetPos(w[2], PLACE_UNDER, w[1], NO_CARE, NULL);
SetWidgetPos(w[3], PLACE_UNDER, w[2], NO_CARE, NULL);
Notice how the third argument changes; we are placing the next widget underneath the previous widget. The zero'th widget (w[0]) doesn't have to be placed because it is always in the top left corner (this can not be changed).
If you wanted to arrange things in a row, you would use PLACE_RIGHT instead of PLACE_UNDER.
As a more complicated example, supposed you want to create two rows of widgets, and a drawing area. You would do the following :
/* first three across the top */
SetWidgetPos(w[1], PLACE_RIGHT, w[0], NO_CARE, NULL);
SetWidgetPos(w[2], PLACE_RIGHT, w[1], NO_CARE, NULL);
SetWidgetPos(w[3], PLACE_RIGHT, w[2], NO_CARE, NULL);
/* next three underneath the top row */
SetWidgetPos(w[4], PLACE_UNDER, w[0], NO_CARE, NULL);
SetWidgetPos(w[5], PLACE_UNDER, w[0], PLACE_RIGHT, w[4]);
SetWidgetPos(w[6], PLACE_UNDER, w[0], PLACE_RIGHT, w[5]);
/* put the drawing area under the second row */
SetWidgetPos(w[7], PLACE_UNDER, w[4], NO_CARE, NULL);
It is useful to think of the window as a kind of grid in which you can put various pieces. Just draw a picture of what you want and then use SetWidgetPos() to indicate to the system what is next to/underneath of what.
Also, all imaginable layouts are not possible with SetWidgetPos() . For example, you cannot specify specific pixel offsets for a widget, or that it be centered in the display, or right justified. This limitaton is for the sake of simplicity. Generally this should not be a problem (if it is, you are probably getting beyond the scope of what libsx was intended to provide, i.e. you're becoming an X hacker :).
You can simulate more complicated layouts by cheating and creating label widgets whose label is just spaces and then placing other widget the left or underneath the label. This works but is kind of hackish.
void SetFgColor(Widget w, int color);
This function sets the foreground color of a widget. If the widget is a drawing area, all future primitives are drawn with the specified color. If the widget is some other type of widget, it sets the foreground color of the widget (such as its text) to be the specified color.
The argument "color" should be an integer that was returned from the colormap functions ( GetNamedColor() , GetRGBColor() , GetPrivateColor() or GetStandardColors() ).
SEE ALSO : SetColor() , SetBgColor() , SetBorderColor() , GetStandardColors() , GetNamedColor() , GetRGBColor()
void SetBgColor(Widget w, int color);
This function sets the background color of a widget. If the specified widget is a drawing area, the next call to ClearDrawArea() will clear the drawing area to the specified background color.
The argument "color" should be an integer that was returned from the colormap functions ( GetNamedColor() , GetRGBColor() , GetPrivateColor() or GetStandardColors() ).
SEE ALSO : SetBgColor() , SetBorderColor() , GetStandardColors() , GetNamedColor() , GetRGBColor()
void SetBorderColor(Widget w, int color);
This argument will set the border color that is drawn around a widget. The same effect happens for all of the different widgets -- the border is redrawn with the new color. This can be very useful for giving a nice visual offset to an important or dangerous button. Of course you should avoid garish combinations of colors that are hard to look at.
SEE ALSO : SetBgColor() , SetBorderColor() , GetStandardColors() , GetNamedColor() , GetRGBColor()
This routine is a convience function that will return the current foreground color of any kind of widget. This is mainly useful for drawing widgets to make sure that you draw things in the proper foreground color. This can arise as a problem if you assume that black is going to be the default foreground color (which it normally is). However, the user can change this default by using the -fg "color" option on the command line. This is an X command line option, and can not be overriden by your program. A real application would use this function to check the value and use it to draw in the user's preferred foreground color. Other programs can just ignore the problem and still work ok as long as the user doesn't change the program's colors.
This function returns the integer value of the foreground color that you can use in later calls to SetFgColor() or SetColor() . It returns -1 if you passed an invalid Widget to it.
SEE ALSO : GetBgColor() , SetColor() , SetFgColor()
This routine is a convience function that will return the current background color of any kind of widget. This is mainly useful for drawing widgets to make sure that you draw things in the proper background color. This can be a problem if you assume that white is going to be the default background color (which it normally is). However, the user can change this default by using the -bg "color" option on the command line. This is an X command line option, and can not be overriden by your program. A real application would use this function to check the value and use it to draw in the user's preferred background color. Other programs can just ignore the problem and still work ok as long as the user doesn't change the program's colors.
The other problem that crops up if you ignore the background color is that if you go to erase something by just drawing in white and white doesn't happen to be the actual background color, your program will look funny.
This function returns the integer value of the background color that you can use in later calls to SetBgColor() or SetColor() . It returns -1 if you passed an invalid Widget to it.
SEE ALSO : GetFgColor() , SetColor() , SetFgColor()
void AddTimeOut(unsigned long interval, void (*func)(), void *data);
If you would like to animate a display or do some periodic processing (such as an auto-save feature for an editor), you can use time-outs.
A time-out is a callback function that gets called when the specified amount of time has expired (or I should say more precisely, when at _least_ that much time has passed, Unix a'int no real time system).
The argument `interval' is an unsigned long and is specified in milliseconds. That is, a time out of 1 second would be an argument of 1000.
The function, func, declared as follows:
void func(void *data, XtIntervalId *id)
{
}
The second argument should be ignored by function's code, but it should appear in the function prototype.
The function is only called once, if you would like the function to be called repeatedly (to update an animation for example), the last thing the function should do is to call AddTimeOut() again.
void SetWidgetState(Widget w, int state);
This function lets you enable or disable particular widgets in an interface. If, for example, choosing one item from a menu should disable various other widgets, you can call this function.
The Widget argument is the widget in question. The state argument is a boolean, which indicates whether the widget should be active or not. A value of TRUE indicates that the widget should accept input, and a value of FALSE indicates that the widget should not accept input (it becomes greyed out).
When you disable a widget, the user can no longer interact with that widget in _any_ way (it becomes grey'ed out and just ignores all input).
This function returns a boolean value indicating whether or not the specified widget is currently active.
If the widget is active and accepting input, the return is TRUE, if the widget is inactive, the return value is FALSE.
This function is real complicated. It beeps the workstation speaker.
void SetWidgetBitmap(Widget w, char *data, int width, int height);
This function lets you attach a bitmap to a widget instead of its default text. This function only works correctly on Button, Toggle and Label widgets. Using it on another type of widget yields undefined results.
The Widget, w, will display the bitmap data given by the argument, data, whose width and height are given as the last two arguments.
The bitmap data is only one bitplane deep, and is usually produced by a somewhat brain-dead X program called `bitmap'. The output of the bitmap program is a file you can directly #include in your source code. The contents of the file are a static array of characters and two #defines that give the width and height of the bitmap.
Thus, making a widget with a bitmap is a two step process. First you would edit a bitmap using the `bitmap' program, then you would do the following:
#include "file_bmap.h"
Widget w;
w = MakeButton(NULL, func, some_data_ptr);
SetWidgetBitmap(w, file_bmap_bits,file_bmap_width,file_bmap_height);
Bits which are a one in the bitmap are drawn in the widget's current foreground color and zero bits are drawn in the current background color.