3.9 Structures for Canvas Functions

The structure introduced in the following chapters serves as parameter for all canvas functions. This structure as well as the relevant functions are window-system independent.

3.9.1 Structure DM_CanvasUserArgs for Microsoft Windows

For the window system Microsoft Windows the definition of the canvas structure is as follows:

typedef struct

{

  DM_ID    object;

  int      reason;

  HWND     hwnd;

  UINT     message;

  WPARAM   wParam;

  LPARAM   lParam;

  LRESULT  mresult;

 

  int      x;

  int      y;

  int      width;

  int      height;

  HANDLE   hdc;

 

  FPTR     userdata;

  } DM_CanvasUserArgs;

Meaning of the Elements

DM_ID object

This element defines the DM ID of the canvas object.

int reason

This element indicates the reason for calling the canvas function. Currently there are the following possibilities:

HWND hwnd

HandleID of the Microsoft Windows window.

UINT message

WPARAM wParam

LPARAM lParam

LRESULT mresult

These are the original message parameters of Microsoft Windows. If no message is available, the element will have the value "message" 0. The elements wParam, lParam and mresult are only valid, if the element "message" does not equal 0.

int x

This element defines the x-coordinate of the used space with regard to the canvas window.

int y

This element defines the y-coordinate of the used space with regard to the canvas window.

int width

This element defines the width of the used space with regard to the canvas window.

int height

This element defines the height of the used space with regard to the canvas window.

HANDLE hdc

This element is the device-context-handle, which is needed to draw in the canvas.

FPTR userdata

In this element the callback function can save any data referring to the user. The save values are also passed on to the canvas function on each call. For further information please refer to the “Attribute Reference”, attribute "AT_CanvasData".

Note

The allocation of this structure always depends on the current task. The elements "object", "reason" and "hwnd" are always allocated; the allocation of the other structure elements can be taken from the following table:

Task	Allocated Element	Meaning
CCR_expose	x, y, width, height	dimension of the update rectangular
	hdc	device-context handle to draw in the canvas
CCR_input	x, y	these fields are allocated, if the original event has been a "ButtonPress" event
CCR_reschange	x, y	coordinate of the upper left corner of the used space with regard to the actual canvas window
	width, height	dimension of the canvas' useable area
CCR_resize	x, y	coordinate of the upper left corner of the used space with regard to the actual canvas window
	width, height	dimension of the canvas' useable area
CCR_start	x, y	coordinate of the upper left corner of the used space with regard to the actual canvas window
	width, height	dimension of the canvas' useable area
CCR_winmsg	message, wParam, lParam, mresult	These elements pass on the original windows messages. The possible values and the meaning of these elements can be taken from the Microsoft Windows manual.

3.9.2 Structure DM_CanvasUserArgs for Motif

For the window system Motif the definition of the canvas structure is as follows:

typedef struct {

  DM_ID    object;

  int      reason;

 

#ifdef _XLIB_H_

  Xevent   *xevent;

  Window   window;

#else

  FPTR     xevent;

  long     window;

#endif

  

#ifdef _XtIntrinsic_h

  Widget   widget;

#else

  FPTR      widget;

#endif

 

  DM_Int2   x;

  DM_Int2   y;

  DM_UInt2  width;

  DM_UInt2  height;

  

  FPTR      userdata;

} DM_CanvasUserArgs;

Meaning of Elements

DM_ID object

This element defines the DM ID of the object which has triggered the function process, i.e. the canvas to which the called function belongs.

int reason

In this element the DM informs the application about the reason why the canvas function has been called.

Currently there are the following possibilities:

Xevent *xevent

In this parameter the original X event is passed on to the application. If no X event is available, this parameter is a NULL pointer. These events are explained in the corresponding X manuals.

Window window

In this element the affiliated X-Windows window is passed on to the application. For further information please refer to the relevant X-Windows manuals.

Widget widget

In this element the Xt-Widget information is passed on to the object.

DM_Int2 x

In this element the x coordinate of the used space with regard to the canvas window is passed on.

DM_Int2 y

In this element the y coordinate of the used space with regard to the canvas window is passed on.

DM_UInt2 width

In this element the width of the used space with regard to the canvas window is passed on.

DM_UInt2 height

In this element the height of the used space with regard to the canvas window is passed on.

FPTR userdata

In this element the callback function can save any data referring to the user. The save values are also passed on to the canvas function on each call. For further information please refer to the “Attribute Reference”, attribute "AT_CanvasData".

Note

The allocation of this structure always depends on the current task. The elements "object" and "reason" are always allocated, the elements "window", "widget" and "xevent" are, if available, always allocated; the allocation of the other structure elements can be taken from the following table:

Task	Allocated Element	Meaning
CCR_expose	x, y, width, height	dimension of the update rectangular
CCR_input	x, y	these fields are allocated, if the original event was a "ButtonPress" event
CCR_reschange	x, y	coordinate of the upper left corner of the used space with regard to the actual canvas window
	width, height	dimension of the canvas' useable area
CCR_resize	x, y	coordinate of the upper left corner of the used space with regard to the canvas window, if the values are already available, otherwise 0
	width, height	dimension of the used space in the canvas, if the values are already available, otherwise 0
CCR_start	x, y	coordinate of the upper left corner of the used space with regard to the actual canvas window
	width, height	dimension of the canvas' useable area