libsx-dev 2.05-8 / usr / share / doc / libsx-dev / html / drawing.html

<title> Drawing Functions </title>

<ul>
 <li> <a href="#drawing"> Drawing Overview </a>
 <li> <a href="drawing.html#fCD">   ClearDisplay </a>
 <li> <a href="drawing.html#fDP">   DrawPixel </a>
 <li> <a href="drawing.html#fDL">   DrawLine </a>
 <li> <a href="drawing.html#fDPl">  DrawPolyline </a>
 <li> <a href="drawing.html#fDFP">  DrawFilledPolygon </a>
 <li> <a href="drawing.html#fDB">   DrawBox </a>
 <li> <a href="drawing.html#fDFB">  DrawFilledBox </a>
 <li> <a href="drawing.html#fDT">   DrawText </a>
 <li> <a href="drawing.html#fDA">   DrawArc </a>
 <li> <a href="drawing.html#fDFA">  DrawFilledArc </a>
 <li> <a href="drawing.html#fDI">   DrawImage </a>
 <li> <a href="drawing.html#fGDAS"> GetDrawAreaSize </a>
 <li> <a href="drawing.html#fGI">   GetImage </a>
 <li> <a href="drawing.html#fGP">   GetPixel </a>
 <li> <a href="drawing.html#fSDA">  ScrollDrawArea </a>
 <li> <a href="drawing.html#fSC">   SetColor </a>
 <li> <a href="drawing.html#fSDA2"> SetDrawArea </a>
 <li> <a href="drawing.html#fSDM">  SetDrawMode </a>
 <li> <a href="drawing.html#fSLW">  SetLineWidth </a>
</ul>
<hr>
<p>
<h2> <a name="drawing"> Drawing Overview </a> </h2>
<p>
This file contains documentation about the routines that let you draw
in a drawing area.
<p>
The documentation for these functions is quite brief because they are
not all that complicated (how much can one really say about
<a href="drawing.html#fDL">       DrawLine() </a>
). 
<p>
Keep in mind that for all the drawing functions, the top-left corner
of a drawing area is considered to be 0,0.
<p>
Also, all primitives are drawn in the current foreground color (set
either by 
<a href="drawing.html#fSC">       SetColor() </a>
or 
<a href="misc.html#fSFC">         SetFgColor() </a>.
Text is drawn with the current
foreground color and the background color.  Line, arc, and box
primitives are drawn with the current line width (as set by
<a href="drawing.html#fSLW">      SetLineWidth() </a>
), and all primitives are drawn in the current draw mode
(set by 
<a href="drawing.html#fSDM">      SetDrawMode() </a>
).  
<hr>
<p>
<a name="fSDA2"> <b>
void   SetDrawArea(Widget w);
</b> </a>
<p>
This sets the current drawing area to be that named by the Widget w.
If `w' is not a drawing area widget, nothing happens.
<p>
You need to call this function when you want to switch between
multiple drawing areas.
<p>
If you only have one drawing area you do not need to worry about this
function at all.
<p>
Any callbacks for a drawing area already have the current drawing area
set to be the one where the event happened (so it is not necessary to
call this function in a callback for a drawing area).
<hr>
<p>
<a name="fSC"> <b>
void   SetColor(int color);
</b> </a>
<p>
This sets the foreground color to draw with in the current drawing
area (each drawing area has its own foreground color).  The argument
"color" should be a valid color obtained with one of the color
functions (such as GetNamedColor() or GetRGBColor(), etc).
<p>
To some extent this function duplicates the SetFgColor() function, but
exists because it is faster than SetFgColor().
<p>
SEE ALSO : 
<a href="misc.html#fSBC">         SetBgColor() </a>, 
<a href="misc.html#fGFC">         GetFgColor() </a>, 
<a href="misc.html#fSFC">         SetFgColor() </a>, 
<a href="color.html#fGSC">        GetStandardColors() </a>
<hr>
<p>
<a name="fSLW"> <b>
void   SetLineWidth(int width);
</b> </a>
<p>
This functions sets the width of lines drawn in the current drawing
area.  Each drawing area has its own line width.
<p>
A width of zero is valid and tells the X server to draw lines as fast
as it possibly can, possibly being a little inaccurate.  Larger
numbers of course draw wider lines.
<p>
SEE ALSO : 
<a href="drawing.html#fSDM">      SetDrawMode() </a>, 
<a href="font.html#fSWF">         SetWidgetFont() </a>, 
<a href="misc.html#fSFC">         SetFgColor() </a>, 
<a href="misc.html#fSBC">         SetBgColor() </a>
<hr>
<p>
<a name="fSDM"> <b>
void   SetDrawMode(int mode);
</b> </a>
<p>
This function sets the drawing mode for the current drawing area.  A
drawing mode is one of:
<p>
    GXcopy, GXxor, GXinvert, GXor, GXclear, GXand, GXandReverse,
    GXnoop, GXnor, GXequiv, GXinvert, GXorReverse, GXcopyInverted,
    GXorInverted, GXnand, and GXset
<p>
Most of these are stupid/useless modes defined by X (so ignore them).
<p>
The primary mode is GXcopy (the default mode).  This causes all
primitives to draw in the foreground color, overwriting any pixels
already drawn.  
<p>
Libsx also defines a special mode: SANE_XOR.  The SANE_XOR mode will
actually draw primitives in a true XOR mode so that you can draw
things like rubber-band boxes that the user stretches with the mouse.
You must use SANE_XOR if you want true XOR'ed primitives, GXxor will
definitely NOT work as you expect.
<p>
When you are done using SANE_XOR, you would normally call
<a href="drawing.html#fSDM">      SetDrawMode() </a> 
with an argument of GXcopy to restore normal drawing. 
<p>
SEE ALSO : 
<a href="drawing.html#fSLW">      SetLineWidth() </a>, 
<a href="font.html#fSWF">         SetWidgetFont() </a>, 
<a href="misc.html#fSFC">         SetFgColor() </a>, 
<a href="misc.html#fSBC">         SetBgColor() </a>
<hr>
<p>
<a name="fGDAS"> <b>
void   GetDrawAreaSize(int *w, int *h);
</b> </a>
<p>
This is a convience function that returns the size of the current
drawing area.  The window dimension are returned in the two variables.
It is important to note that "w" and "h" are POINTERS to integers, not
just regular integers.
<hr>
<p>
<a name="fCD"> <b>
void   ClearDrawArea(void);
</b> </a>
<p>
This function completely clears the current drawing area and sets it
to the current background color (which may not be white).
<p>
Generally, when your redisplay callback is called, this is the first
thing want to do.
<p>
SEE ALSO : 
<a href="drawing.html#fSDA2">     SetDrawArea() </a>, 
<a href="misc.html#fGBC">         GetBgColor() </a>, 
<a href="misc.html#fSBC">         SetBgColor() </a>
<hr>
<p>
<a name="fDP"> <b>
void DrawPixel(int x1, int y1);
</b> </a>
<p>
This function draws a point in the current foreground color at the
location x1, y1 in your current drawing area.  The top left corner of
the drawing area is considered 0,0. 
<p>
SEE ALSO : 
<a href="drawing.html#fGP">       GetPixel() </a>, 
<a href="drawing.html#fSC">       SetColor() </a>, 
<a href="drawing.html#fSDA2">     SetDrawArea() </a>, 
<a href="misc.html#fSBC">         SetBgColor() </a>, 
<a href="misc.html#fSFC">         SetFgColor() </a>
<hr>
<p>
<a name="fGP"> <b>
int GetPixel(int x1, int y1);
</b> </a>
<p>
This function retrieves the pixel value at the location x1, y1 in the 
current drawing area.  The top left corner of the drawing area is
considered 0,0.
<p>
The pixel value returned to you will be between 0 and 255 (inclusive).
The value you get back should be treated as an index to a colormap.
To find out what actual color is displayed at that location, you
need to look up the color in the colormap (which you should be
maintaining as there is no way to get it after you've set it). 
<p>
NOTE: This function is <b>NOT</b> very high performance. It has to call
<a href="drawing.html#fGI">       GetImage() </a> 
to do the bulk of the work.  This is unfortunate,
but unavoidable because X does not provide an easy way to read
individual pixels.
<p>
SEE ALSO : 
<a href="drawing.html#fGI">       GetImage() </a>, 
<a href="drawing.html#fSC">       SetColor() </a>, 
<a href="drawing.html#fSDA2">     SetDrawArea() </a>, 
<a href="misc.html#fSBC">         SetBgColor() </a>, 
<a href="misc.html#fSFC">         SetFgColor() </a>
<hr>
<p>
<a name="fDL"> <b>
void DrawLine(int x1, int y1, int x2, int y2);
</b> </a>
<p>
This function draws a line from x1,y1 to x2,y2 in the current
foreground color in the current drawing area.  The top left corner of
the drawing area is considered 0,0.  
<p>
SEE ALSO : 
<a href="drawing.html#fDPl">      DrawPolyline() </a>, 
<a href="drawing.html#fDP">       DrawPixel() </a>, 
<a href="drawing.html#fSC">       SetColor() </a>, 
<a href="misc.html#fSBC">         SetBgColor() </a>,
<a href="misc.html#fSFC">         SetFgColor() </a>, 
<a href="drawing.html#fSDA2">     SetDrawArea() </a>, 
<hr>
<p>
<a name="fDPl"> <b>
void DrawPolyline(XPoint *points, int n);
</b> </a>
<p>
This function accepts an array of points and draws them as a connected
polyline on the display.  The line is drawn in the current foreground
color in the current drawing area. The top left corner of the drawing
area is considered 0,0.  
<p>
The `points' argument is an array of XPoint structures which are as
follows: 
<p>
<pre>
   typedef struct XPoint
   {
      short x,y;
   }XPoint;
</pre>
<p>
You do not need to define this structure yourself.  It is defined for
you already, it is just reprinted here so you can see what it is.
<p>
You should have an array of these structures with each entry holding a
vertex of the polyline.
<p>
SEE ALSO : 
<a href="drawing.html#fDL">       DrawLine() </a>, 
<a href="drawing.html#fDFP">      DrawFilledPolygon() </a>, 
<a href="drawing.html#fSC">       SetColor() </a>,
<a href="drawing.html#fSDA2">     SetDrawArea() </a>, 
<a href="misc.html#fSBC">         SetBgColor() </a>, 
<a href="misc.html#fSFC">         SetFgColor() </a>
<hr>
<p>
<a name="fDFP"> <b>
void DrawFilledPolygon (XPoint *points, int n);
</b> </a>
<p>
This function takes an array of points and draws them as a filled
polygon on the display.  The polygon is filled with the current
foreground color and is drawn in the current drawing area. The top
left corner of the drawing area is considered 0,0.  
<p>
The `points' argument is an array of XPoint structures which are as
follows: 
<p>
<pre>
   typedef struct XPoint
   {
      short x,y;
   }XPoint;
</pre>
<p>
You do not need to define this structure yourself.  It is defined for
you already, it is just reprinted here so you can see what it is.
<p>
You should have an array of these structures with each entry holding a
vertex of the polygon to be filled.
<p>
SEE ALSO : 
<a href="drawing.html#fDPl">      DrawPolyline() </a>, 
<a href="drawing.html#fDB">       DrawBox() </a>, 
<a href="drawing.html#fSC">       SetColor() </a>, 
<a href="drawing.html#fSDA2">     SetDrawArea() </a>,
<a href="misc.html#fSBC">         SetBgColor() </a>, 
<a href="misc.html#fSFC">         SetFgColor() </a>
<hr>
<p>
<a name="fDB"> <b>
void DrawBox(int x, int y, int width, int height);
</b> </a>
<p>
This function draws a rectangular box starting at x,y with a width and
height as specified.  If you make the call: DrawBox(50,50, 75,75), you
will get a box that starts at position 50,50 and goes for 75 pixels in
the X and Y directions (i.e the other extreme of the box would be at
125,125). The box is drawn in the current foreground color in the
current drawing area. The top left corner of the drawing area is
considered 0,0.  
<p>
If the width and height are negative, the box is still drawn properly.
<p>
SEE ALSO : 
<a href="drawing.html#fDFB">      DrawFilledBox() </a>, 
<a href="drawing.html#fDPl">      DrawPolyline() </a>, 
<a href="drawing.html#fSC">       SetColor() </a>, 
<a href="drawing.html#fSDA2">     SetDrawArea() </a>,
<a href="misc.html#fSBC">         SetBgColor() </a>, 
<a href="misc.html#fSFC">         SetFgColor() </a>
<hr>
<p>
<a name="fDFB"> <b>
void DrawFilledBox(int x, int y, int width, int height);
</b> </a>
<p>
This function draws a filled rectangular box starting at x,y with a
width and height as specified.  If you make the call:
DrawFilledBox(50,50, 75,75), you will get a filled box that starts at
position 50,50 and goes for 75 pixels in the X and Y directions (i.e
the other extreme of the box would be at 125,125). The box is filled
with the current foreground color in the current drawing area. The top
left corner of the drawing area is considered 0,0.
<p>
If the width and height are negative, the box is still drawn properly.
<p>
SEE ALSO : 
<a href="drawing.html#fDB">       DrawBox() </a>, 
<a href="drawing.html#fDFP">      DrawFilledPolygon() </a>, 
<a href="drawing.html#fSC">       SetColor() </a>, 
<a href="drawing.html#fSDA2">     SetDrawArea() </a>,
<a href="misc.html#fSBC">         SetBgColor() </a>, 
<a href="misc.html#fSFC">         SetFgColor() </a>
<hr>
<p>
<a name="fDT"> <b>
void DrawText(char *string, int x, int y);
</b> </a>
<p>
This function prints the text string "string" starting at x,y.  The
text is drawn in the current foreground color.  The background of the
text is filled with current background color of the drawing area
widget.  The top left of the drawing area is 0,0.  The X,Y position
you specify is the bottom left corner of where the text is drawn. 
<p>
SEE ALSO : 
<a href="font.html#fGF">          GetFont() </a>, 
<a href="font.html#fFH">          FontHeight() </a>, 
<a href="font.html#fTW">          TextWidth() </a>, 
<a href="drawing.html#fSC">       SetColor() </a>,
<a href="drawing.html#fSDA2">     SetDrawArea() </a>, 
<a href="font.html#fSWF">         SetWidgetFont() </a>, 
<a href="misc.html#fGBC">         GetBgColor() </a>,
<a href="misc.html#fSFC">         SetFgColor() </a>, 
<a href="misc.html#fSBC">         SetBgColor() </a>
<hr>
<p>
<a name="fDA"> <b>
void DrawArc(int x, int y, int width, int height, int angle1, int angle2);
</b> </a>
<p>
This function draws an arc/ellipse from the location x,y that is
bounded by the box defined by the x,y, width and height.  That is, the
arc/ellipse will always be contained in the box defined by the x,y
position and the width and height arguments.  The X,Y arguments are
not the center of the arc/circle.
<p>
The arc begines at angle1 degrees and continues for angle2 degrees
around the circle.  The arc is drawn in the current foreground color
in the current drawing area. The top left corner of the drawing area
is considered 0,0.
<p>
If you want a circle, you would specify angle1 as 0, and angle2 as
360. 
<p>
If the width and height are negative, the arc is still drawn properly.
<p>
SEE ALSO : 
<a href="drawing.html#fDPl">      DrawPolyline() </a>, 
<a href="drawing.html#fSC">       SetColor() </a>, 
<a href="drawing.html#fSDA2">     SetDrawArea() </a>, 
<a href="misc.html#fSBC">         SetBgColor() </a>,
<a href="misc.html#fSFC">         SetFgColor() </a>
<hr>
<p>
<a name="fDFA"> <b>
void DrawFilledArc(int x, int y, int width, int height,	
                   int angle1, int angle2);
</b> </a>
<p>
This function draws a filled arc/ellipse from the location x,y that is
bounded by the box defined by the x,y, width and height.  That is, the
arc/ellipse will always be contained in the box defined by the x,y
position and the width and height arguments.  The X,Y arguments are
not the center of the arc/circle. 
<p>
The arc begines at angle1 degrees and continues for angle2 degrees
around the circle.  The arc is filled with the current foreground
color in the current drawing area. The top left corner of the drawing
area is considered 0,0.
<p>
If you want a circle, you would specify angle1 as 0, and angle2 as
360. 
<p>
If the width and height are negative, the arc is still drawn properly.
<p>
SEE ALSO : 
<a href="drawing.html#fDA">       DrawArc() </a>, 
<a href="drawing.html#fSC">       SetColor() </a>, 
<a href="drawing.html#fSDA2">     SetDrawArea() </a>, 
<a href="misc.html#fSBC">         SetBgColor() </a>, 
<a href="misc.html#fSFC">         SetFgColor() </a>
<hr>
<p>
<a name="fDI"> <b>
void DrawImage(char *data, int x, int y, int width, int height);
</b> </a>
<p>
This function draws a bitmap image that has a width and height as
specified by the arguments.  The image is drawn at location x,y in the
current drawing area.  The "data" argument should point to at least
width*height bytes of data.  
<p>
Each byte of the data is interpreted as a color value to draw the
corresponding pixel with.
<p>
Normally you would use this function when you have taken over the
colormap with GetAllColors() (so that you can be guaranteed certain
colors are in a given range).  If you have not taken over the
colormap, you need to make sure that the bytes in the image data
contain valid values that you've allocated with the color allocation
functions (
<a href="color.html#fGNC">        GetNamedColor() </a>, 
<a href="color.html#fGRGBC">      GetRGBColor() </a> or 
<a href="color.html#fGPC">        GetPrivateColor() </a>
).
<p>
The top left corner of the drawing area is considered 0,0.
<p>
SEE ALSO : 
<a href="drawing.html#fGI">       GetImage() </a>, 
<a href="drawing.html#fSC">       SetColor() </a>, 
<a href="drawing.html#fSDA2">     SetDrawArea() </a>,
<a href="color.html#fGAC">        GetAllColors() </a>
<hr>
<p>
<a name="fDB"><b>
void DrawBitmap(char *data, int x, int y, int width, int height);
</b></a>
<p>
This function draws a bitmap that has a width and height as specified
by the arguments.  The bitmap is drawn at location x,y in the current
drawing area.  The "data" argument should point to at least
width*height/8 bytes of data.
<p>
The difference between this function and DrawImage() is that the data
is an actual bitmap with 1 bit per pixel (versus 1 byte per pixel for
an Image).
<p>
Each byte of the data is interpreted as 8 pixels.  If a bit in the
byte is on, the corresponding pixel is drawn in the foreground color.
If the bit is off, the corresponding color is drawn in the background
color.
<p>
Normally you would use this function on a monochrome display (though
it will still work on a color screen).
<p>
The top left corner of the drawing area is considered 0,0.
<p>
SEE ALSO : 
<a href="drawing.html#fDI">       DrawImage() </a>, 
<a href="drawing.html#fGI">       GetImage() </a>, 
<a href="drawing.html#fSC">       SetColor() </a>, 
<a href="drawing.html#fSDA2">     SetDrawArea() </a>
<hr>
<p>
<a name="fGI"> <b>
void GetImage(char *data, int x, int y, int width, int height);
</b> </a>
<p>
This function retrieves a bitmap image from your drawing area that 
has a width and height as specified by the arguments.  The image is
taken from the starting location x,y in the current drawing area.  The
"data" argument should point to at least width*height bytes of data.  
<p>
The area of memory pointed to by data will be filled with the 8-bit
pixel values of the current drawing area.  Note that the pixel values
are not the actual color values.  If you want the actual color values,
you'll need to know what the current colormap is (which you would know
if you've set the colormap) and then use the pixel values to index the
colormap. 
<p>
The memory pointed to by data is packed with width*height bytes, with
no extra padding or filling.  That is, the first width bytes
correspond to line 0, the next width bytes correspond to line 1 of the
image, etc.
<p>
It is important to keep in mind that if you plan to save the pixel
data in an image file, you need to also keep track of the colormap so
that you can save that as well.  By themselves, the pixel values don't
correspond to any particular color.
<p>
A serious drawback of this function arises from the way X operates.
If the drawing area from which you are "getting" the image is obscured
by another window, that part of the bitmap will be empty.  The only
way around this is to make sure that your window is in front of all
the others before you call GetImage().  This is a serious limitation,
but it's the way X operates. 
<p>
The top left corner of the drawing area is considered 0,0.  If you specify
a starting x,y and width,height dimensions that are larger than your 
drawing area, you will get a BadMatch error and X will terminate your
program (so be careful).
<p>
SEE ALSO : 
<a href="drawing.html#fDI">       DrawImage() </a>, 
<a href="drawing.html#fSC">       SetColor() </a>, 
<a href="drawing.html#fSDA2">     SetDrawArea() </a>, 
<a href="color.html#fGAC">        GetAllColors() </a>
<hr>
<p>
<a name="fSDA"> <b>
void   ScrollDrawArea(int dx, int dy, int x1,int y1, int x2, int y2);
</b> </a>
<p>
This function scrolls the box defined by (x1,y1) (x2,y2) by the
amounts dx and dy in the X and Y directions respectively.  This means
that the box whose upper left corner is (x1,y1) and whose lower right
corner is (x2,y2) are scrolled by dx and dy pixels in X and Y.
<p>
A positive value for dx causes the drawing area to scroll its contents
to the left.  That is, whatever is at the left edge gets pushed off
and the dx columns of pixels on the right hand side are cleared to the
background color.  A negative value has the opposite effect.
<p>
A positive value for dy corresponds to scrolling upwards.  That is,
whatever is at the top of the drawing area is pushed up by dy pixels
and the bottom dy rows of pixels are cleared to the background color.
A negative value has the opposite effect.
<p>
This function is useful for scrolling the drawing area to draw new
information (such as a text editor might do to scroll text up or
down).
<p>
The new area exposed by the scroll is filled with the current
background color of the drawing area.
<p>
SEE ALSO : 
<a href="font.html#fSWF">         SetWidgetFont() </a>, 
<a href="drawing.html#fSC">       SetColor() </a>