
.Ls
void active_cursor(int n)

Make the visible cursor be the one with index n in the icon
array.  The number n returned by a previous call to either
make_cursor() or make_color_cursor(). If n is negative, the
default cursor becomes visible. The program will fail if it is
called with a nonnegative value that is not one returned by a
call to the cursor creation functions.  (Section 3.2.3.)
.Le


.Ls
int add_RGB_color(pPixel red, pPixel green, pPixel blue)

Create an entry in the colormap with the color values passed as
arguments and return the index of the colormap entry. If there is
no space for the new color, the function returns -1.  In general,
using add_named_color() instead of this function is better.  Use
add_RGB_color() in such programs as a slider that uses gradual
changes in color to indicate value.  (Not discussed in the text.)
.Le


.Ls
int add_RGB_colors(pPixel red_pix[], pPixel green_pix[],
pPixel blue_pix[], int RGB_length)

Add RGB_length consecutive colorcells to the colormap.
The colors are in three arrays given as arguments.
Upon successful allocation, the function returns the
pixel value of the first entry. Normally, this value should be
stored in the pixel_offset member of the pImage structure. If
there is no space for the colors, the function checks whether
they are already present in the colormap, and if so it returns
the pixel value (this usually happens when two copies of an
application are running). The function returns zero upon failure
and -1 if there is no depth in the display. This function is
useful for adding colors to an existing colormap so the
appearance of other windows is not affected. (The colormap created
by imgwin() may not have that property.)  (Not discussed in the
text.)
.Le


.Ls
void add_colors_by_name(pValue clist[])

Only the labels of the value pair list need be initialized and
each name must be preceded by a ``-'' - for example, -white.
Then, the function add_named_color() is called for each named
color (after skipping the first character), and the returned
value is stored in the corresponding value member of the
structure. If the value returned by add_named_color() is
negative, the value of the previous entry is copied except for
the first element when the value is set to 0.  The function
returns when a 0 label is found in clist[].  (Section 7.5.1.)
.Le


.Ls
int add_named_color(char *cname)

Find the named color in the database of the  and determine
whether its red, green, and blue values are in the colormap used
by the application. If not, make a new entry in the colormap as
long as there is space. In either case return the index of the
colormap entry.  If the name is not in the database or if it is
found but there is no space for the new color, the function
returns -1.  (Section 2.6.2.)
.Le


.Ls
int add_work( int (*f)() )

The function f() will be called when no events are waiting in the
queue. The return of f() is important. If it is nonzero, the
function is removed from the system. See also the functions
grab_draw_area() and release_draw_area().  (Section 3.4.2.)
.Le

.Ls
void arguments( int arc, char **arv)

Pass the command line arguments to the X Toolkit Intrinsics.
This makes the application conform to the ICCCM and allows
the passing of resources through the command line. Otherwise
it has no effect in the program. It should be called before
any other functions of the Starter Toolkit. (Not discussed in the
text.)
.Le

.Ls
int backing_store(Widget w)

If the server has backing store, assign it to the window of the
Widget w with north west gravity. In this case the function returns 1;
otherwise it returns 0. If backing store is assigned, no more
exposure events will be generated. This function must be called
only after a widget has been realized. A good place to call it in
programs written entirely with the Starter Toolkit is from inside
the redraw function. Since exposure events are supressed after that
the redraw function will be called only once. (Not discussed in the
text.)
.Le


.Ls
int back_color(char *cname)

Set the background color to the given name, (e.g., ``red,''
``orange,'' etc.). It returns 0 if the color has been set
successfully; otherwise, it returns -1.  (Section 1.4.3.)
.Le


.Ls
Widget  base_widget()

Return the widget that is to be used as parent of a drawing
widget.  It is either a container widget or a pop-up shell.
(Section 9.3.1.)
.Le


.Ls
void begin_display(int w_width, int w_height,
        char *window_label)

Start the program by connecting to the display (server) and
initialize internal data structures to allow the creation of a
drawing window with width w_width and height w_height.  The
string window_label is used as a label in the frame of the
window.  This function should be called before any other
procedure of the Starter Toolkit. The only exceptions are the two
functions vis_window() and draw_window() that contain equivalent
code to begin_display().  (Section 3.3.1.)
.Le


.Ls
void clear_screen(int x, int y, int W, int H)

If any argument is negative, the entire drawing window is erased.
Otherwise, only a rectangle with upper left corner coordinates x,
y and dimensions W and H is erased.  (Section 1.4.2.)
.Le


.Ls
void collect_text(pEvent *p)

Event handler for collecting strings of characters typed on the
window.  See also init_text(), set_string_use(), and
get_string().  (Section 2.5.2.)
.Le


.Ls
void color_slider(void (*usage)(double), char *label,
        char *fore, char *back)

Create a slider widget with background color back and foreground
color fore. The slider displays a scale between 0 and 100 and the
user may select any intermediate position.  When a selection is
made, the function usage() is called with the selected value as
an argument. The argument must be declared as double.  The value
is also displayed near the upper left corner of the window. The
argument label is displayed near the right side of the window and
is truncated to 14 characters if it is longer than that.  The
dimensions of the slider cannot be changed.  (Section 7.6.)
.Le


.Ls
void complete_display()

Creates and displays a drawing window and any other windows that
have been requested.  (Section 3.3.1.)
.Le


.Ls
void compose_color(pImage *Ip, int use_htone)

This function converts images with 24 bits per pixel to images
with 8 bits per pixel. If Ip does not point to an image with 24
bits per pixel, the function returns immediately. The function
assumes that the 8 most significant bits are for blue, the next 8
are for green, and the last 8 are for red. If use_htone is not 0,
the conversion uses color halftoning which results in much better
results but requires more time than when use_htone is 0.
(Section 21.4.2.)
.Le


.Ls
Widget create_paper_widget( int (*redraw)(),
        int (*handler)(pEvent *), int width, int height,
        int relationship, char *window_name )

Create a paper widget that provides a drawing window of
dimensions width and height with frame label window_name.  The
function redraw() is called in response to exposure events and
the function handler() is called in response to mouse and
keyboard events.  The argument relationship is a flag that can
have one of the following predefined values: NormalChild,
PopupChild, or IndepedentChild.  When this function is used,
files <X11/StringDefs.h> and <X11/Intrinsic.h> must be included.
(Section 9.2.1.)
.Le


.Ls
void default_destination()

Restore the widget of the main drawing window for destination of
the output of the Starter Toolkit graphics functions.  (Section
9.2.2.)
.Le


.Ls
void draw_area(PaperWidget w)

Copy the display pointer, window, and graphics context associated
with w to the static variables of the module that contains the
drawing functions of the Starter Toolkit, such as put_line() and
fore_color().  (Section 9.2.2.)
.Le


.Ls
void draw_icon(int k, int x, int y)

Display the icon pointed at by k at location x, y.  The integer k
must have been returned by a make_icon() call.  (Section 3.2.3.)
.Le


.Ls
void draw_window(void (*f)(), void (*g)(pEvent *),
        int w, int h, char *s)

The argument f is a pointer to a drawing function, as in
vis_window(); g is the event handler, w and h are the width and
height of the window, and s the window label.  (Section 2.2.3.)
.Le


.Ls
void end_dialog()

Erase the dialogue panel and wait for another panel selection.
(Section 7.5.4.)
.Le


.Ls
void erase()

Set foreground color the same as the background color, so any
future drawing using replacement mode will result in erasures.
The original foreground color can be restored with resume().
(Not discussed in the text.)
.Le


.Ls
void fill_rectangle(int x, int y, int W, int H)

Display a filled rectangle with upper left corner coordinates x,
y and dimensions W and H.  (Section 1.4.2.)
.Le


.Ls
int fontlength(char *text_string)

If a font has been selected, it returns the length (in pixels) of
the text string given as the argument. If there is no selected
font, it returns the number of characters in the string
multiplied by 12.  (Section 1.4.4.)
.Le


.Ls
int fore_color(char *cname)

Set the foreground color to the given name (e.g., ``red,''
``orange,'' etc.). It returns 0 if the color has been set
successfully; otherwise, it returns -1.  (Section 1.4.3.)
.Le


.Ls
void get_default_args(Display **dpp, Window *wp, GC *gcp)

Return the values of the first three arguments of Xlib functions
that are needed for drawing on the windows created by the Starter
Toolkit.  (Section 18.1.)
.Le


.Ls
int get_font_height()

If a font has been selected, it returns the maximum vertical span
of characters in the font used in the display. If there is no
selected font, it returns 20.  (Section 1.4.4.)
.Le


.Ls
pImage *get_image(pEvent *p)

Return a pointer to the structure of the image displayed in the
window where the event occurred.  (Section 20.4.2.)
.Le


.Ls
void get_selection(void (*f)(char *))

Ask the server for the primary selection of type text and call
f() with the selection string as argument.  (Not discussed in the
text.)
.Le


.Ls
void get_string(pEvent *p)

Event handler that when the user presses a mouse button, places a
prompt at the point where the cursor is and then displays typed
text there. It calls init_text() and collect_text().  (Section
2.5.3.)
.Le


.Ls
void grab_draw_area()

Function that should be called before any graphics operations in
a background procedure (one that is passed as argument to
add_work()). Essential if the application chosen has more than
one window. See also release_draw_area().  (Section 7.6.)
.Le


.Ls
void idle(int n)

Suspend execution (sleep) for (approximately) n microseconds.
(Section 3.4.2.)
.Le


.Ls
void imgwin(char *label, int (*handler)(pEvent *),
        pImage *img)

Create a pop-up window of sufficient size to display the image of
the structure img and also create a colormap for the window from
the information in the same structure. Argument label is the
window label, and handler() is the event handler for that window.
(Section 20.4.2.)
.Le


.Ls
init_text(int x, int y, int k)

Initialize text collection when the event handler is
collect_text().  Characters typed on the keyboard will appear on
the application window starting at location with coordinates x,
y.  If k is nonzero, hitting the RETURN key terminates text
entry. Otherwise, the user must hit the ESC key to terminate text
entry. See also set_string_use().  (Section 2.5.1.)
.Le


.Ls
int make_color_cursor(unsigned char iconbits[],
        int hx, int hy, char *color, char *mask_color)

Create a 16x16 cursor icon using the array iconbits.
Arguments hx and hy are the coordinates of the ``hot spot'' of
the cursor, the point whose coordinates are returned by the event
handler.  The upper left corner of the icon is 0, 0. The last two
arguments should be character strings specifying the color of the
cursor and its mask.  The function returns an integer used to
reference the cursor from the applications program.  The function
returns a negative index when not enough memory is left to create
the structure.  There is no need to supply a mask; it is created
automatically.  (Section 3.2.3.)
.Le


.Ls
int make_cursor(char iconbits[], int hx, int hy)

Function calls make_color_cursor() (see above) with color
arguments ``black'' and ``white.'' (Section 3.2.3.)
.Le


.Ls
void make_dash()

All lines will be drawn dashed.  (Section 1.4.3.)
.Le


.Ls
int make_icon(char iconbits[], int w, int h,
        int cx, int cy)

Argument iconbits is the array that contains the pixel
description, w and h are the width and height of the icon,
respectively, and cx and cy are the coordinates of the center
with respect to the upper left corner. The center is used to
display the icon in a particular location. The function returns
an integer that is used to reference the icon from the
applications program.  The function returns a negative index when
not enough memory is left to create the structure.  (Section
3.2.3.)
.Le

.Ls
void make_image(pImage *img, pPixel *data, int width, int height,
			int colors[])

Create an image from an array of pixel values. Data is a given
pixel array whose dimensions are width and height. The array
colors contains the correspondence between pixel values and the
colormap in use. Normally the (two-dimensional) array data will be
accompanied by a table connecting pixel values with colors. Suppose
that the table has entries:

        5       red
        6       pink
        7       orange
etc. Then the colors array must be filled as
        colors[5] = add_named_color("red");
        colors[6] = add_named_color("pink");
        colors[7] = add_named_color("orange");

After make_image is called the image can be displayed by calling
put_image(img, ... ). The major difference between images create
by this function and those create by setup_image() is that make_image()
uses the existing colormap and does so sparingly. It is appropriate
for images with a few well defined colors.
.Le

.Ls
void make_solid()

All lines will be drawn solid.  (Section 1.4.3.)
.Le


.Ls
void mk_label(char **target, char *source)

Copy the string pointed at by source to the memory location
pointed at by *target after allocating sufficient memory to the
latter location. Note the asymmetric use of the two arguments. If
we have the declaration char *a, *b; we should call this function
as mk_label(&a, b).  (Section 7.4.2.)
.Le


.Ls
void own_error(int serious, char *msg)

Print the message msg in the window that originated the
application. If serious is nonzero, terminate execution;
otherwise, continue.  (Not discussed in the text.)
.Le


.Ls
int own_selection(int x, int y, char *s)

Tell the server to make s the text selection.  Arguments x and y
are the coordinates of the start of the baseline where the text
is displayed. Return TRUE or FALSE, depending on whether the
server granted the request.  (Not discussed in the text.)
.Le


.Ls
XtPointer * paper_hanger(PaperWidget w)

Return a pointer to a pointer associated with the widget w.  This
function is used to associate a structure with the widget w.
(Section 9.2.2.)
.Le


.Ls
void poly_fill(pPoint v[], int n, char rule)

Fill the interior of the polygon with n vertices stored in v[]
with the color of the foreground. If the argument rule has any
value other than 'w', use the ordinary parity rule; otherwise,
use the directional parity or winding rule.  Bugs: This routine
invokes an Xlib function that does not handle polygons with holes
or the proper drawing of the original sides of the polygon.
(Section 12.4.)
.Le


.Ls
void popdown(Widget w)

Cause the window of the widget w to disappear. The widget must
have been created as the child of a pop-up shell. (See popup()
for more on this point.) (Section 9.2.2.)
.Le


.Ls
void popup(Widget w, int easy)

Cause the window of the widget w to appear. The widget must have
been created as the child of a pop-up shell - for example, by
calling create_paper_widget() with PopupChild as its fifth
argument.  If the flag easy is 0, all keyboard and mouse input is
ignored unless directed to that widget. This setting is
appropriate for dialogue widgets.  (Section 9.2.2.)
.Le


.Ls
int put_NL_text(char *s, int x, int y, int compdim,
        int *wp, int *hp)

Display a text string that contains new lines. The first three
arguments are as in put_text(); the rest have the following
meaning. If compdim is nonzero, the function computes the
dimensions of the displayed block of text and stores the width
and height (in pixels) in the locations pointed at by wp and hp,
respectively. The function returns the length of the last line in
pixels.  (Not discussed in the text.)
.Le


.Ls
void put_arc(int cx, int cy, int rx, int  ry,
        int start_a, int length_a)

Plot a circular or elliptical arc with center coordinates cx and
cy, starting
at angle start_a (expressed in degrees) and spanning an angle of
length_a degrees.  If rx and ry are equal, the arc is circular
with radius rx.  Otherwise, it is elliptical with a horizontal
axis of rx and a vertical axis of ry.  To plot a complete circle
with radius r, the appropriate call is put_arc(cx, cy, r, r, 0,
360). The arc is drawn counterclockwise if length_a is positive
and clockwise if it is negative. Starting angles are measured
from the horizontal and can be either positive or negative.
(Section 10.6.)
.Le


.Ls
void put_image(pImage *img, int x, int y)

Displays the image pointed to by img with its upper left corner
at the point having coordinates x, y.  It uses the ID member to
find a pointer to the appropriate data.  (Section 20.4.2.)
.Le


.Ls
void put_line(int x1, int y1, int x2, int y2)

Display a straight line segment joining a pair of points with
coordinates x1, y1, and x2, y2, respectively.  (Section 1.4.2.)
.Le


.Ls
void put_poly(pPoint v[], int n)

Plot a polygon with n vertices whose coordinates are stored in
the array v[]. The value of n must be at least 1.  (Section
10.6.)
.Le


.Ls
void put_rectangle(int x, int y, int w, int h)

Display an unfilled rectangle with upper left corner at x, y,
width w, and height h.  (Section 1.4.2.)
.Le


.Ls
int put_text(char *text, int x, int y)

Display the string text so that it starts at x and its baseline
is at y.  It returns the width of the displayed text in pixels.
Warning: The function does not work correctly if the string
contains new line characters. Use put_NL_text() for such strings.
(Section 1.4.2.)
.Le


.Ls
void restore_destination()

Restore the previous widget for destination of the output of the
Starter Toolkit graphics functions.  (Section 9.2.2.)
.Le


.Ls
int read_image(char *fname, pImage *result)

Read a raster image from file fname and store the pixel values,
dimensions, and colormap information in the pImage structure
pointed at by result. Return 0 on success, nonzero on failure.
Current implementation is for SUN raster files.  (Section
20.4.1.)
.Le


.Ls
void release_draw_area()

This function should be called after all graphics operations in a
background procedure and before calling idle(). See also
grab_draw_area().  (Section 7.6.)
.Le


.Ls
void resume()

Restore the original foreground color after an erase() call.
(Not discussed in the text.)
.Le


.Ls
int select_font(char *font_name)

Select the named font to be used for displaying text. The
function returns 1 upon success and 0 otherwise. Note that a font
corresponds to both a specific style and a specific size.
(Section 1.4.4.)
.Le


.Ls
void set_backgr(long c)

Set the background color to the value c.  (Section 1.4.3.)
.Le


.Ls
void set_default_args(Display *dp, Window w, GC gc)

Set the default values of the first three arguments of Xlib
functions that are used by the  drawing functions. Function
should be used cautiously to avoid unwanted interference with the
operation of the .  (Section 18.1.)
.Le


.Ls
void set_foregr(long c)

Set the foreground color to the value c.  (Section 1.4.3.)
.Le


.Ls
void set_handler(void (*f)(pEvent *))

Argument f is the name of a procedure that takes exactly one
argument, a pointer to a pen structure. When an event occurs, the
event handler of the
 calls f with a pointer to a pEvent structure as an argument.
(Section 2.4.2.)
.Le


.Ls
void set_line_width(int n)

All lines (dashed or solid) will be drawn with thickness n.
(Section 1.4.3.)
.Le


.Ls
void set_redraw( void (*f)() )

Argument f is the name of a function that normally takes no
arguments which should be called whenever there is a need to
redraw a window.  oAdvanced Use: In reality, the Intrinsics call
f with the widget where an expose event occurred as its argument.
Applications that deal with multiple windows may find this
feature to be useful.  (Section 3.3.1.)
.Le


.Ls
void set_string_use(void (*f)(char *))

To be used when the event handler is collect_text().  After the
user terminates text entry, the function f is called with the
entered text as its argument.  (Section 2.5.1.)
.Le


.Ls
int setup_a_panel(char *name, pAction a[],
        void (*rfun)(), char *icdata[])

Set up a panel with button labels and callbacks as specified by
the array a[].  The last element of the array must be a structure
with a null label.  If a[].fun() returns a nonzero value for some
entry, the panel button pops back up after that entry has been
selected; otherwise, it remains depressed.  The argument name is
used to identify the class of actions of the panel. The function
rfun, if provided, is called before each callback.  Its purpose
is to take care of any general operations that must be carried
out before the callback - for example, cleaning up the results of
an earlier selection. The array of character strings icdata[] is
used for setting panels with icons rather than text labels.  Each
element of the array should be the name of an icon byte array.
The argument icdata can be omitted for panels having text labels
only. Only one selection can be made at one time, so the panel
behaves like a ``radio box.'' If a label starts with ``-,'' the
rest of the label is interpreted as a color and the button is
filled with the color.  If a label starts with ``@,'' the rest of
the label is interpreted as the dimension of a square icon. An
icon is then formed from the corresponding entry of icdata[] and
is used to label the button.  (Section 7.3.2.)
.Le


.Ls
int setup_v_panel(char *name, pValue v[],
        int (*cfun)(int), char *icdata[])

Set up a panel with button labels and values as specified by the
array v[].  The last element of the array must be a structure
with a null label.  The function pointer cfun is the common
callback function and always must be provided.  It is called with
the selected value as an argument.  If it returns a nonzero
value, the panel button pops back up after each selection;
otherwise, it remains depressed.  The argument name is a label
for the panel.  The array of character strings icdata[] is used
for setting panels with icons rather than text labels.  Each
element of the array should be the name of an icon byte. The
argument icdata can be omitted for panels with text labels only.
Only one selection can be made at one time, so the panel behaves
like a ``radio box.'' See setup_a_panel() for the interpretation
of labels.  (Section 7.3.2.)
.Le


.Ls
void setup_canvas(int width, int height)

Create a drawing window of the given dimensions.  (Section
7.4.1.)
.Le


.Ls
int setup_image(pImage *img)

If the display is monochrome, this function creates a halftone of
the image and copies it into a bitmap. If the display has enough
bits, then it creates another pixmap and copies the image there.
The XID of the bitmap or the pixmap is copied onto the img->ID
and is used later for all displays of the picture.  (Section
20.4.2.)
.Le


.Ls
void slider(void (*usage)(double), char *label)

Create a slider widget with a white background and black
foreground.  See the entry for color_slider() for the rest of the
documentation.  (Section 7.6.)
.Le


.Ls
void start_dialog(pAction messages[])

Cause a dialogue panel to appear, displaying messages[0].label
and an underscore. The user is expected to type a string ending
with Return or Escape.  (Errors are corrected by backspacing.)
Then the function messages[0].fun() is called with the typed
string as argument.  If messages[0].fun() contains any
to_dialog() calls, their strings are displayed before
messages[1].label is displayed. The process continues in this
manner until a 0 label is found.  (Section 7.5.4.)
.Le


.Ls
void take_from_file(int fid, int (*fun)(long, int *))

Argument fid is a file descriptor, and fun is the function called
to read data from the file descriptor when such data become
available.  (Section 7.7.1.)
.Le


.Ls
void to_dialog(char *s)

Display the string s in the dialogue panel.  (Section 7.5.4.)
.Le

.Ls
Cursor true_cursor(int n)

Find the true cursor XID from the index returned
by make_cursor() or make_color_cursor(). (Not discussed in the text.)
.Le

.Ls
void two_way_pipe(char *cmd, int *to_child_p,
        int *from_child_p)

Start execution of the Unix command cmd and return pointers to
two file descriptors: to_child_p for providing input to the
command and from_child_p for taking output from the command.
(Section 7.7.2.)
.Le


.Ls
void use_replace_mode()

Set the drawing mode to replacement. (The old value is replaced
by the new.) (Section 1.4.3.)
.Le


.Ls
void use_xor_mode()

Set the drawing mode to exclusive OR. (The value in the refresh
memory is formed by the bitwise exclusive OR of the old and the
new value.) (Section 1.4.3.)
.Le


.Ls
void version()

Print the version number of the Starter Toolkit.  (Not discussed in the text.)
.Le


.Ls
void vis_window(void (*f)(), int w, int h)

Create a window with width w and height h or the default values
if the arguments are unreasonable.  When the window is ready,
call f() to create the contents of the display.  The function f()
is also called anytime the window has to be redrawn in response
to changes in the display - for example, if the window was
obscured by another and then becomes visible again.  (Section
1.5.1.)
.Le


.Ls
void wait_for_event()

Go into an infinite loop, but at each iteration check on whether
an event has occurred (e.g., the mouse moved) and call the
appropriate event handler.  (Section 3.3.1.)
.Le


.Ls
int write_image(char *fname, pImage *given)

Create a raster image in file fname from the pixel values,
dimensions, and colormap information in the pImage structure
pointed at by given. Return 0 on success, nonzero on failure.
Current implementation produces SUN raster files.  (Not discussed
in the text.)
.Le


.Ls
void xflush()

Flush the graphics instructions to the server. Normally, any
drawing instructions are buffered until there are events in the
server queue. Calling this function causes immediate execution.
(Section 1.4.2.)
.Le


.Ls
void xor_fore()

Function is useful for drawing with exclusive OR on nonzero
background. The applications programmer can select the desired
colors for foreground and background and, by calling this
function, can be sure that the correct colors will appear.
Function should be called immediately after a change in
foreground of background color.  (Section 1.4.3.)
.Le
