Drawing Functions

Drawing Overview

This file contains documentation about the routines that let you draw in a drawing area.

The documentation for these functions is quite brief because they are not all that complicated (how much can one really say about DrawLine() ).

Keep in mind that for all the drawing functions, the top-left corner of a drawing area is considered to be 0,0.

Also, all primitives are drawn in the current foreground color (set either by SetColor() or SetFgColor() . 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 SetLineWidth() ), and all primitives are drawn in the current draw mode (set by SetDrawMode() ).

void SetDrawArea(Widget w);

This sets the current drawing area to be that named by the Widget w. If `w' is not a drawing area widget, nothing happens.

You need to call this function when you want to switch between multiple drawing areas.

If you only have one drawing area you do not need to worry about this function at all.

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

void SetColor(int color);

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

To some extent this function duplicates the SetFgColor() function, but exists because it is faster than SetFgColor().

void SetLineWidth(int width);

This functions sets the width of lines drawn in the current drawing area. Each drawing area has its own line width.

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.

void SetDrawMode(int mode);

This function sets the drawing mode for the current drawing area. A drawing mode is one of:

GXcopy, GXxor, GXinvert, GXor, GXclear, GXand, GXandReverse, GXnoop, GXnor, GXequiv, GXinvert, GXorReverse, GXcopyInverted, GXorInverted, GXnand, and GXset

Most of these are stupid/useless modes defined by X (so ignore them).

The primary mode is GXcopy (the default mode). This causes all primitives to draw in the foreground color, overwriting any pixels already drawn.

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.

When you are done using SANE_XOR, you would normally call SetDrawMode() with an argument of GXcopy to restore normal drawing.

void GetDrawAreaSize(int *w, int *h);

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.

void ClearDrawArea(void);

This function completely clears the current drawing area and sets it to the current background color (which may not be white).

Generally, when your redisplay callback is called, this is the first thing want to do.

SEE ALSO : SetDrawArea() , GetBgColor() , SetBgColor()

void DrawPixel(int x1, int y1);

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.

int GetPixel(int x1, int y1);

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.

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

NOTE: This function is NOT very high performance. It has to call GetImage() to do the bulk of the work. This is unfortunate, but unavoidable because X does not provide an easy way to read individual pixels.

void DrawLine(int x1, int y1, int x2, int y2);

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.

void DrawPolyline(XPoint *points, int n);

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.

The `points' argument is an array of XPoint structures which are as follows:

   typedef struct XPoint
   {
      short x,y;
   }XPoint;

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.

You should have an array of these structures with each entry holding a vertex of the polyline.

void DrawFilledPolygon (XPoint *points, int n);

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.

The `points' argument is an array of XPoint structures which are as follows:

   typedef struct XPoint
   {
      short x,y;
   }XPoint;

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.

You should have an array of these structures with each entry holding a vertex of the polygon to be filled.

void DrawBox(int x, int y, int width, int height);

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.

If the width and height are negative, the box is still drawn properly.

void DrawFilledBox(int x, int y, int width, int height);

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.

If the width and height are negative, the box is still drawn properly.

void DrawText(char *string, int x, int y);

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.

void DrawArc(int x, int y, int width, int height, int angle1, int angle2);

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.

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.

If you want a circle, you would specify angle1 as 0, and angle2 as 360.

If the width and height are negative, the arc is still drawn properly.

void DrawFilledArc(int x, int y, int width, int height, int angle1, int angle2);

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.

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.

If you want a circle, you would specify angle1 as 0, and angle2 as 360.

If the width and height are negative, the arc is still drawn properly.

void DrawImage(char *data, int x, int y, int width, int height);

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.

Each byte of the data is interpreted as a color value to draw the corresponding pixel with.

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 ( GetNamedColor() , GetRGBColor() or GetPrivateColor() ).

The top left corner of the drawing area is considered 0,0.

void DrawBitmap(char *data, int x, int y, int width, int height);

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.

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

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.

Normally you would use this function on a monochrome display (though it will still work on a color screen).

The top left corner of the drawing area is considered 0,0.

SEE ALSO : DrawImage() , GetImage() , SetColor() , SetDrawArea()

void GetImage(char *data, int x, int y, int width, int height);

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.

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.

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.

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.

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.

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

void ScrollDrawArea(int dx, int dy, int x1,int y1, int x2, int y2);

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.

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.

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.

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

The new area exposed by the scroll is filled with the current background color of the drawing area.