Drawing Area (2024)

A drawing area is a rectangular area that supports drawing into,receiving input from (mouse clicks, mouse motion and keypresses) andredisplay requests from X. You can draw any sort of graphics into adrawing area as well as perform various types of interaction withmouse and keyboard input.

It is also useful to read the drawing.html file for more information onthe actual drawing routines available.

Widget MakeDrawArea(int width, int height, RedisplayCB func, void *data);

The function MakeDrawArea() creates a drawing area which you can lateruse to draw graphics into and receive mouse and keyboard input from.The drawing are will have a width and height as you specify. Thecallback function, func, is called whenever the drawing area should beredisplayed (because it was obscured or resized). The argument "data"is a pointer to any arbitrary data you want, and it is passed directlyto the resize callback (and the other callbacks as well).

The redisplay callback is where you should put all of your drawingcode. It is called for you when the application opens the window forthe first time (by calling MainLoop()). The redisplay callbackfunction should be declared as follows:

 void redisplay(Widget w, int width, int height, void *data) { }

The first argument, w, is the drawing area widget that needs to beredrawn. The second and third arguments are the new width and heightof the drawing area (it may have been resized). The final argumentis the void pointer passed to MakeDrawArea().

If you are interested in receiving other types of input, see thefunctions, SetButtonDownCB() , SetButtonUpCB() , SetKeypressCB() SetMouseMotionCB() ,SetLeaveCB() . These functions will let you set callbacks forthe other types of input.

Each drawing area you create has its own state (foreground andbackground colors, drawing mode, and line width). Only one drawingarea can be active at any given time. When an event happens for adrawing area, that drawing area becomes the active drawing area. Youcan make other drawing areas active with SetDrawArea() .

If something goes wrong in creating the DrawArea, a NULL value isreturned.

void SetButtonDownCB(Widget w, MouseButtonCB func);

This function sets up a callback that will be called everytime theuser presses a mouse button in the specified drawing area widget `w'.

The callback function should be declared as follows:

 void func(Widget w, int which_button, int x, int y, void *data) { }

Then, whenever the user presses a mouse button in the drawing area,your callback is called. The first argument is the drawing areawidget where the event happened. The next argument is an integerspecifying which button was pressed. It is a small positive integer.A value of one is the left mouse button, two is the middle mousebutton and three is the right mouse button. Technically, values offour and five are also possible though I've never seen a mouse withfive buttons. The x and y arguments are the position of the mousewhere the user pressed the mouse button. The final argument is thevoid pointer argument given to MakeDrawArea() .

You can specify a NULL for the function to turn off receiving buttondown events.

void SetButtonUpCB(Widget w, MouseButtonCB button_up);

This function sets up a callback that will be called everytime theuser releases a mouse button in the specified drawing area widget `w'.

The callback function should be declared as follows:

 void func(Widget w, int which_button, int x, int y, void *data) { }

Then, whenever the user releases a mouse button in the drawing area,your callback is called. The first argument is the drawing areawidget where the event happened. The next argument is an integerspecifying which button was released. It is a small positive integer.A value of one is the left mouse button, two is the middle mousebutton and three is the right mouse button. Technically, values offour and five are also possible though I've never seen a mouse withfive buttons. The x and y arguments are the position of the mousewhere the user released the mouse button. The final argument is the void pointer argument given to MakeDrawArea() .

You can specify a NULL for the function to turn off receiving buttonup events.

void SetKeypressCB(Widget w, KeyCB func);

This function lets you set a callback so that you will receivekeyboard input in the drawing area.

The callback function should be declared as follows:

See Also

Types, History of Graphic Art

 void func(Widget w, char *input, int up_or_down, void *data) { }

Then, whenever the user presses keys in the drawing area, yourcallback function is called. The first argument is the drawing areawidget where the event happened. The next argument is a characterpointer to a null-terminated string that contains what was typed bythe user. The up_or_down argument indicates whether the key was pressedreleased (a zero indicates a press, a 1 indicates a key release). The final argument is the void ponter argument given to MakeDrawArea().

It is useful to know that the string returned to your program isnot necessarily a single ASCII character. You will get the usualASCII characters, including control characters (such as ^C or ^H).But, the workstation's function keys will also be returned in astring such as "F11" or "F23". You will also get other longerstrings such as "Control_L", "Alt_R", or "Shift_L". It isimportant to understand that even if you just press the shift key toget a capital letter, you will first receive the string "Shift_L"or "Shift_R", then you will receive a capital letter (say, "H").You should probably ignore the "Shift_L" or "Shift_R" messages (butwho knows, you may find some use for them).

The argument, up_or_down, tells you whether the given key was pressedor released. If the key was pressed down, up_or_down has a zero (0),if the key was released, up_or_down contains a 1. This is useful for doing things like shift-clicking with the mouse or handling control-keycombinations in an editor or other program.

The arrow keys return strings such as "Left", "Up", "Right", or"Down". Other keys on the keyboard may return strings such as "Home","Prior", "Next", "Undo", "Help", etc. Of course not all keyboardsgenerate all of the strings (because they aren't set up to).

NOTE WELL: The string that is returned to you can NOT be modified by your program. If you want to munge with it, make a copy using strdup() or strcpy() into your own buffer space.

You can specify a NULL for the function to turn off receiving keypressevents.

void SetMouseMotionCB(Widget w, MotionCB func);

This function sets a callback so that whenever the mouse moves in yourdrawing area, the specified function will be called. It is importantto keep in mind that the function you specify is called _every_ timethe mouse moves in the drawing area, even if it is just passingthrough. The callback function should be declared as follows:

 void func(Widget w, int x, int y, void *data); { }

The first argument is (as usual) the Widget where the mouse was movedin. The next two arguments are the current X and Y values of themouse. The final argument is the void pointer passed into MakeDrawArea() .

You should be very frugal with what happens in this function so as notto cause the application to lag behind the user too much. Callingfunctions like sleep() are definitely out of the question.

You can specify a NULL for the function to turn off receiving mousemotion events.

void SetEnterCB(Widget w, EnterCB func);

This function sets a callback so that whenever the mouse crosses theboundary of your drawing area from the outside in, the specifiedfunction will be called.

The callback function should be declared as follows:

 void func(Widget w, int x, int y, void *data); { }

The first argument is (as usual) the Widget that the mouse entered.The next two arguments are the X and Y coordinates of the crossingpoint. The final argument is the void pointer passed into MakeDrawArea() .

The coordinates may be inaccurate if the mouse moved rapidly;they may even fall outside the widget's boundaries.

You can specify a NULL for the function to turn off receiving mouseenter events.

void SetLeaveCB(Widget w, EnterCB func);

This function sets a callback so that whenever the mouse crosses theboundary of your drawing area from the inside out, the specifiedfunction will be called.

The callback function should be declared as follows:

 void func(Widget w, int x, int y, void *data); { }

The first argument is (as usual) the Widget that the mouse exited.The next two arguments are the X and Y coordinates of the crossingpoint. The final argument is the void pointer passed into MakeDrawArea() .

The coordinates may be inaccurate if the mouse moved rapidly;they may even fall outside the widget's boundaries.

You can specify a NULL for the function to turn off receiving mouseexit events.