Graphics Library

special mouse functions More...

Macros
#define	graf_dragbox(a, b, c, d, e, f, g, h, i, j)   mt_graf_dragbox(a,b,c,d,e,f,g,h,i,j,aes_global)
#define	graf_growbox(a, b, c, d, e, f, g, h)   mt_graf_growbox(a,b,c,d,e,f,g,h,aes_global)
#define	graf_growbox_grect(a, b)   mt_graf_growbox_grect(a,b,aes_global)
#define	graf_handle(a, b, c, d)   mt_graf_handle(a,b,c,d,aes_global)
#define	graf_xhandle(a, b, c, d, e)   mt_graf_xhandle(a,b,c,d,e,aes_global)
#define	graf_mbox(a, b, c, d, e, f)   mt_graf_mbox(a,b,c,d,e,f,aes_global)
#define	graf_mkstate(a, b, c, d)   mt_graf_mkstate(a,b,c,d,aes_global)
#define	graf_mouse(a, b)   mt_graf_mouse(a,b,aes_global)
#define	graf_rubberbox(a, b, c, d, e, f)   mt_graf_rubberbox(a,b,c,d,e,f,aes_global)
#define	graf_multirubber(a, b, c, d, e, f, g)   mt_graf_multirubber(a,b,c,d,e,f,g,aes_global)
#define	graf_shrinkbox(a, b, c, d, e, f, g, h)   mt_graf_shrinkbox(a,b,c,d,e,f,g,h,aes_global)
#define	graf_shrinkbox_grect(a, b)   mt_graf_shrinkbox_grect(a,b,aes_global)
#define	graf_slidebox(a, b, c, d)   mt_graf_slidebox(a,b,c,d,aes_global)
#define	graf_watchbox(a, b, c, d)   mt_graf_watchbox(a,b,c,d,aes_global)
#define	graf_wwatchbox(a, b, c, d, e)   mt_graf_wwatchbox(a,b,c,d,e,aes_global)
#define	graf_movebox(a, b, c, d, e, f)   mt_graf_mbox(a,b,c,d,e,f,aes_global)
#define	graf_rubbbox(a, b, c, d, e, f)   mt_graf_rubberbox(a,b,c,d,e,f,aes_global)
#define	graf_rubbox(a, b, c, d, e, f)   mt_graf_rubberbox(a,b,c,d,e,f,aes_global)

Functions
short	mt_graf_dragbox (short Sw, short Sh, short Sx, short Sy, short Bx, short By, short Bw, short Bh, short *Fw, short *Fh, short *global_aes)
short	mt_graf_growbox (short Sx, short Sy, short Sw, short Sh, short Fx, short Fy, short Fw, short Fh, short *global_aes)
short	mt_graf_growbox_grect (const GRECT *in, const GRECT *out, short *global_aes)
short	mt_graf_handle (short *Wchar, short *Hchar, short *Wbox, short *Hbox, short *global_aes)
short	mt_graf_xhandle (short *Wchar, short *Hchar, short *Wbox, short *Hbox, short *device, short *global_aes)
short	mt_graf_mbox (short Sw, short Sh, short Sx, short Sy, short Dx, short Dy, short *global_aes)
short	mt_graf_mkstate (short *Mx, short *My, short *ButtonState, short *KeyState, short *global_aes)
short	mt_graf_mouse (short Form, const MFORM *FormAddress, short *global_aes)
short	mt_graf_rubberbox (short Ix, short Iy, short Iw, short Ih, short *Fw, short *Fh, short *global_aes)
short	mt_graf_multirubber (short bx, short by, short mw, short mh, GRECT *rec, short *rw, short *rh, short *global_aes)
short	mt_graf_shrinkbox (short Fx, short Fy, short Fw, short Fh, short Sx, short Sy, short Sw, short Sh, short *global_aes)
short	mt_graf_shrinkbox_grect (const GRECT *in, const GRECT *out, short *global_aes)
short	mt_graf_slidebox (OBJECT *, short Parent, short Object, short Direction, short *global_aes)
short	mt_graf_watchbox (OBJECT *, short Object, short InState, short OutState, short *global_aes)
short	mt_graf_wwatchbox (OBJECT *, short Object, short InState, short OutState, short whandle, short *global_aes)

Detailed Description

special mouse functions

The Graphics Library provides applications with a variety of utility functions which serve to provide common screen effects, mouse control, and the obtaining of basic screen attributes.

Macro Definition Documentation

#define graf_dragbox	(		a,
			b,
			c,
			d,
			e,
			f,
			g,
			h,
			i,
			j
	)		mt_graf_dragbox(a,b,c,d,e,f,g,h,i,j,aes_global)

single-thread version of mt_graf_dragbox()

#define graf_growbox	(		a,
			b,
			c,
			d,
			e,
			f,
			g,
			h
	)		mt_graf_growbox(a,b,c,d,e,f,g,h,aes_global)

single-thread version of mt_graf_growbox()

#define graf_growbox_grect	(		a,
			b
	)		mt_graf_growbox_grect(a,b,aes_global)

single-thread version of mt_graf_growbox_grect()

#define graf_handle	(		a,
			b,
			c,
			d
	)		mt_graf_handle(a,b,c,d,aes_global)

single-thread version of mt_graf_handle()

#define graf_mbox	(		a,
			b,
			c,
			d,
			e,
			f
	)		mt_graf_mbox(a,b,c,d,e,f,aes_global)

single-thread version of mt_graf_mbox()

#define graf_mkstate	(		a,
			b,
			c,
			d
	)		mt_graf_mkstate(a,b,c,d,aes_global)

single-thread version of mt_graf_mkstate()

#define graf_mouse	(		a,
			b
	)		mt_graf_mouse(a,b,aes_global)

single-thread version of mt_graf_mouse()

#define graf_movebox	(		a,
			b,
			c,
			d,
			e,
			f
	)		mt_graf_mbox(a,b,c,d,e,f,aes_global)

single-thread version of mt_graf_mbox()

#define graf_multirubber	(		a,
			b,
			c,
			d,
			e,
			f,
			g
	)		mt_graf_multirubber(a,b,c,d,e,f,g,aes_global)

single-thread version of mt_graf_multirubber()

#define graf_rubbbox	(		a,
			b,
			c,
			d,
			e,
			f
	)		mt_graf_rubberbox(a,b,c,d,e,f,aes_global)

single-thread version of mt_graf_rubberbox()

#define graf_rubberbox	(		a,
			b,
			c,
			d,
			e,
			f
	)		mt_graf_rubberbox(a,b,c,d,e,f,aes_global)

single-thread version of mt_graf_rubberbox()

#define graf_rubbox	(		a,
			b,
			c,
			d,
			e,
			f
	)		mt_graf_rubberbox(a,b,c,d,e,f,aes_global)

single-thread version of mt_graf_rubberbox()

#define graf_shrinkbox	(		a,
			b,
			c,
			d,
			e,
			f,
			g,
			h
	)		mt_graf_shrinkbox(a,b,c,d,e,f,g,h,aes_global)

single-thread version of mt_graf_shrinkbox()

#define graf_shrinkbox_grect	(		a,
			b
	)		mt_graf_shrinkbox_grect(a,b,aes_global)

single-thread version of mt_graf_shrinkbox_grect()

#define graf_slidebox	(		a,
			b,
			c,
			d
	)		mt_graf_slidebox(a,b,c,d,aes_global)

single-thread version of mt_graf_slidebox()

#define graf_watchbox	(		a,
			b,
			c,
			d
	)		mt_graf_watchbox(a,b,c,d,aes_global)

single-thread version of mt_graf_watchbox()

#define graf_wwatchbox	(		a,
			b,
			c,
			d,
			e
	)		mt_graf_wwatchbox(a,b,c,d,e,aes_global)

single-thread version of mt_graf_wwatchbox()

#define graf_xhandle	(		a,
			b,
			c,
			d,
			e
	)		mt_graf_xhandle(a,b,c,d,e,aes_global)

single-thread version of mt_graf_xhandle()

Function Documentation

short mt_graf_dragbox	(	short	w,
		short	h,
		short	sx,
		short	sy,
		short	bx,
		short	by,
		short	bw,
		short	bh,
		short *	rx,
		short *	ry,
		short *	global_aes
	)

allows the user to move a box frame within the constraints of a bounding rectangle.

Parameters

w	initial width of the box to draw.
h	initial height of the box to draw.
sx	starting x screen coordinate
sy	starting y screen coordinate
bx	x-coordinate of the bounding rectangle.
by	y-coordinate of the bounding rectangle.
bw	width of the bounding rectangle.
bh	height of the bounding rectangle.
rx	will be filled in (on function exit) with the ending x position of the box. [option CHECK_NULLPTR] rx may be NULL
ry	will be filled in (on function exit) with the ending y position of the box. [option CHECK_NULLPTR] ry may be NULL
global_aes	global AES array

Returns

0 if an error occurred during execution or greater than zero otherwise.

Since

All AES versions.

See also

mt_graf_slidebox()

This call should be made only when the mouse button is depressed. The call returns when the mouse button is released.

It is most often used to give the user a visual 'clue' when an object is being moved on screen.

short mt_graf_growbox	(	short	sx,
		short	sy,
		short	sw,
		short	sh,
		short	fx,
		short	fy,
		short	fw,
		short	fh,
		short *	global_aes
	)

shows animation an outline of a box from one set of coordinates to another. It is the complement function to mt_graf_shrinkbox().

Parameters

sx	x-coordinate of the starting rectangle
sy	y-coordinate of the starting rectangle
sw	width of the starting rectangle
sh	height of the starting rectangle (where the outline will grow from).
fx	x-coordinate of the ending rectangle
fy	y-coordinate of the ending rectangle
fw	width of the ending rectangle
fh	height of the ending rectangle (where the outline will grow to).
global_aes	global AES array

Returns

0 if an error occured or non-zero otherwise.

Since

All AES versions.

See also

mt_form_dial(), mt_graf_shrinkbox()

It is used to provide a visual 'clue' to a user.

Note

This function is what is called by GEM's mt_form_dial() with FMD_GROW mode.

There is currently no defined method of handling an error generated by this function.

short mt_graf_growbox_grect	(	const GRECT *	in,
		const GRECT *	out,
		short *	global_aes
	)

see mt_graf_growbox()

Parameters

in	starting rectangle (where the outline will grow from).
out	ending rectangle (where the outline will grow to).
global_aes	global AES array

Returns

see mt_graf_growbox()

Since

see mt_graf_growbox()

short mt_graf_handle	(	short *	wcell,
		short *	hcell,
		short *	wbox,
		short *	hbox,
		short *	global_aes
	)

returns important information regarding the physical workstation currently in use by the AES.

Parameters

wcell	pointer to a short int which will contain (on function exit) the width of the current system character set. [option CHECK_NULLPTR] wcell may be NULL
hcell	pointer to a short int which will contain (on function exit) the height of the current system character set. [option CHECK_NULLPTR] hcell may be NULL
wbox	pointer to a short int which will contain (on function exit) the width of the minimum bounding box of a BOXCHAR character. [option CHECK_NULLPTR] wbox may be NULL
hbox	pointer to a short int which will contain (on function exit) the height of the minimum bounding box of a BOXCHAR character. [option CHECK_NULLPTR] hbox may be NULL
global_aes	global AES array

Returns

the VDI handle for the current physical workstation used by the AES which is required to open a virtual screen workstation.

Since

All AES versions.

See also

v_opnvwk()

Note

There is currently no defined method of handling an error generated by this function.

short mt_graf_mbox	(	short	w,
		short	h,
		short	sx,
		short	sy,
		short	dx,
		short	dy,
		short *	global_aes
	)

animates a moving box between two points on the screen.

Parameters

w	initial width of the box to draw
h	initial height of the box to draw.
sx	starting x-coordinates of the box
sy	starting y-coordinates of the box.
dx	ending x-coordinates of the box
dy	ending y-coordinates of the box
global_aes	global AES array

Returns

0 if an error occured or non-zero otherwise.

Since

All AES versions.

See also

mt_graf_slidebox()

It is used to give the user a visual 'clue' to an action undertaken by the application.

Note

There is currently no defined method of handling an error generated by this function.

short mt_graf_mkstate	(	short *	mx,
		short *	my,
		short *	mbutton,
		short *	kmeta,
		short *	global_aes
	)

returns information about the current state of the mouse pointer, buttons, and keyboard meta keys state.

Parameters

mx	pointer to a short integer, which on function exit will be filled in with the current x-coordinate of the mouse pointer. [option CHECK_NULLPTR] mx may be NULL
my	pointer to a short integer, which on function exit will be filled in with the current y-coordinate of the mouse pointer. [option CHECK_NULLPTR] my may be NULL
mbutton	pointer to a short integer, which on function exit will be filled in with the current button state of the mouse as defined in mt_evnt_button(). [option CHECK_NULLPTR] mbutton may be NULL
kmeta	pointer to a short integer which upon return will contain the current status of the keyboard shift keys as defined in mt_evnt_button(). [option CHECK_NULLPTR] kmeta may be NULL
global_aes	global AES array

Returns

is currently reserved and currently equals 1.

Since

All AES versions.

See also

mt_evnt_button(), vq_mouse()

short mt_graf_mouse	(	short	shape,
		const MFORM *	shape_addr,
		short *	global_aes
	)

alters the appearance of the mouse form and can be used to hide and display the mouse pointer from the screen.

Parameters

shape	specifies the new form of the mouse pointer, or specifies an action regarding this form (save, restore, hide...). See the table hereafter for details.
shape_addr	a pointer to a MFORM structure. If shape is different than USER_DEF, shape_addr should be NULL
global_aes	global AES array

Returns

0 if an error occurred or non-zero otherwise.

Since

All AES versions. mt_appl_getinfo() with AES_FORM gives the availability of M_SAVE, M_RESTORE and M_PREVIOUS modes

See also

vsc_form()

The table hereafter summaries the values that shape can take.

shape	value	meaning
ARROW	0	Change the current mouse cursor shape
TEXT_CRSR	1	Change the current mouse cursor shape
BUSY_BEE	2	Change the current mouse cursor shape
POINT_HAND	3	Change the current mouse cursor shape
FLAT_HAND	4	Change the current mouse cursor shape
THIN_CROSS	5	Change the current mouse cursor shape
THICK_CROSS	6	Change the current mouse cursor shape
OUTLN_CROSS	7	Change the current mouse cursor shape
USER_DEF	255	Change the current mouse cursor shape
M_OFF	256	Remove the mouse cursor from the screen
M_ON	257	Display the cursor
M_SAVE	258	Save the current mouse form in an AES provided buffer.
M_RESTORE	259	Restore the most recently saved mouse form
M_PREVIOUS	260	Restore the mouse form to its last shape

Note

As of AES 4.0 and beyond, the AES may not allow a mouse form to change to benefit another application. If it is absolutely necessary for the application to display its mouse form, logically OR the shape parameter with M_FORCE (0x8000) and make the call. This will force the AES to change to your mouse form. It should, however, be done within the scope of a mt_wind_update() sequence.

There is currently no defined method of handling an error generated by this function.

short mt_graf_multirubber	(	short	bx,
		short	by,
		short	mw,
		short	mh,
		GRECT *	rec,
		short *	rw,
		short *	rh,
		short *	global_aes
	)

allows the user to change the size of a box outline with a fixed starting point.

Parameters

bx	x-coordinate of the fixed upper-left corner of the box to stretch or shrink.
by	y-coordinate of the fixed upper-left corner of the box to stretch or shrink.
mw	minimum width that the rectangle can be shrunk to.
mh	minimum height that the rectangle can be shrunk to.
rec	specify the "inside" box (??? TO BE CONFIRMED)
rw	pointer to a short integer which will be filled in with the ending width of the box when the mouse button is released. [option CHECK_NULLPTR] rw may be NULL
rh	pointer to a short integer which will be filled in with the ending height of the box when the mouse button is released. [option CHECK_NULLPTR] rh may be NULL
global_aes	global AES array

Returns

0 if an error occurred or non-zero otherwise.

Since

NAES (???).

See also

mt_graf_rubberbox()

This function should only be entered when the user has depressed the mouse button as it returns when the mouse button is released.

Note

This call is similar to mt_graf_rubberbox(). It's usefull when resizing a window using the SIZER widget. The bx, by, mw and mh parameters define the whole window, and rect defines the work area of the window.

short mt_graf_rubberbox	(	short	bx,
		short	by,
		short	mw,
		short	mh,
		short *	rw,
		short *	rh,
		short *	global_aes
	)

allows the user to change the size of a box outline with a fixed starting point.

Parameters

bx	x-coordinate of the fixed upper-left corner of the box to stretch or shrink.
by	y-coordinate of the fixed upper-left corner of the box to stretch or shrink.
mw	minimum width that the rectangle can be shrunk to.
mh	minimum height that the rectangle can be shrunk to.
rw	pointer to a short integer which will be filled in with the ending width of the box when the mouse button is released. [option CHECK_NULLPTR] rw may be NULL
rh	pointer to a short integer which will be filled in with the ending height of the box when the mouse button is released. [option CHECK_NULLPTR] rh may be NULL
global_aes	global AES array

Returns

0 if an error occurred or non-zero otherwise.

Since

All AES versions.

See also

mt_graf_dragbox(), mt_graf_slidebox()

This function should only be entered when the user has depressed the mouse button as it returns when the mouse button is released.

Note

There is currently no defined method of handling an error generated by this function.

short mt_graf_shrinkbox	(	short	fx,
		short	fy,
		short	fw,
		short	fh,
		short	sx,
		short	sy,
		short	sw,
		short	sh,
		short *	global_aes
	)

displays an animated box shrinking from one rectangle to another.

Parameters

fx	x-coordinate of the rectangle to shrink to.
fy	y-coordinate of the rectangle to shrink to.
fw	width of the rectangle to shrink to.
fh	height of the rectangle to shrink to.
sx	x-coordinate of the rectangle to shrink from
sy	y-coordinate of the rectangle to shrink from
sw	width of the rectangle to shrink from
sh	height of the rectangle to shrink from
global_aes	global AES array

Returns

0 if an error occured or non-zero otherwise.

Since

All AES versions.

See also

mt_form_dial(), mt_graf_growbox()

It should be used to provide the user with a visual 'clue' to an action. It is the complement function to mt_graf_growbox().

Note

There is currently no defined method of handling an error generated by this function.

short mt_graf_shrinkbox_grect	(	const GRECT *	in,
		const GRECT *	out,
		short *	global_aes
	)

see mt_graf_shrinkbox()

Parameters

in	rectangle to shrink to
out	rectangle to shrink from
global_aes	global AES array

Returns

see mt_graf_shrinkbox()

Since

see mt_graf_shrinkbox()

short mt_graf_slidebox	(	OBJECT *	tree,
		short	parent,
		short	object,
		short	direction,
		short *	global_aes
	)

allows the user to slide a child object within the bounds of its parent. It is often used to implement slider controls.

Parameters

tree	is pointer to the object tree containing the child and parent objects.
parent	is the object index of an object which bounds the movement of the object.
object	is the object index of the object which can be moved within the bounds of parent.
direction	specifies the orientation of the allowed movement: 0 is horizontal (left-right), 1 is vertical (up-down).
global_aes	global AES array

Returns

a value specifying the relative offset of the child within the parent as a number between 0 and 1000.

Since

All AES versions.

See also

mt_graf_mbox()

This call can be used easily with sliders built into dialogs by making the slider bar a OF_TOUCHEXIT and calling this function when it is clicked.

This call should only be made when the mouse button is depressed as it returns when it is released.

short mt_graf_watchbox	(	OBJECT *	tree,
		short	object,
		short	in_state,
		short	out_state,
		short *	global_aes
	)

modifies the given state of a specified object depending on whether the pointer is within the bounds of the object or outside the bounds of the object as long as the left mouse button is held down.

Parameters

tree	is a pointer to the ROOT object of the tree which contains the object you wish to watch.
object	is the object index of the object to watch.
in_state	is the ob_state (see mt_objc_change()) to apply while the mouse is inside of the bounds of the object.
out_state	is the ob_state to apply while the mouse is outside of the bounds of the object.
global_aes	global AES array

Returns

0 if the mouse button was released outside of the object or a 1 if the button was released inside of the object.

Since

All AES versions.

See also

mt_form_button()

This call is used internally by mt_form_button() and mt_form_do() and is usually only necessary if you are replacing one of these handlers.

As this call returns when the mouse button is released, it should only be made when the mouse button is depressed.

short mt_graf_wwatchbox	(	OBJECT *	tree,
		short	object,
		short	in_state,
		short	out_state,
		short	whandle,
		short *	global_aes
	)

modifies the given state of a specified object depending on whether the pointer is within the bounds of the object or outside the bounds of the object as long as the left mouse button is held down.

Parameters

tree	is a pointer to the ROOT object of the tree which contains the object you wish to watch.
object	is the object index of the object to watch.
in_state	is the ob_state (see mt_objc_change()) to apply while the mouse is inside of the bounds of the object.
out_state	is the ob_state to apply while the mouse is outside of the bounds of the object.
whandle	window handle
global_aes	global AES array

Returns

0 if the mouse button was released outside of the object or a 1 if the button was released inside of the object.

Since

MagiC 5.10.

See also

mt_graf_watchbox()

The function returns when the mouse button is released. The function is analog mt_graf_watchbox() with the difference, that here the window and the list of visible rectangles is used.

short mt_graf_xhandle	(	short *	wcell,
		short *	hcell,
		short *	wbox,
		short *	hbox,
		short *	device,
		short *	global_aes
	)

returns important information regarding the physical workstation currently in use by the AES.

Parameters

wcell	pointer to a short int which will contain (on function exit) the width of the current system character set. [option CHECK_NULLPTR] wcell may be NULL
hcell	pointer to a short int which will contain (on function exit) the height of the current system character set. [option CHECK_NULLPTR] hcell may be NULL
wbox	pointer to a short int which will contain (on function exit) the width of the minimum bounding box of a BOXCHAR character. [option CHECK_NULLPTR] wbox may be NULL
hbox	pointer to a short int which will contain (on function exit) the height of the minimum bounding box of a BOXCHAR character. [option CHECK_NULLPTR] hbox may be NULL
device	pointer to a short integer which will contain (on function exit) the device ID of the physical workstation used by the AES. This is the value to put in work_in[0] when invoking v_opnvwk(). If the AES doesn't support this feature, then device will contain 0. [option CHECK_NULLPTR] device may be NULL
global_aes	global AES array

Returns

the VDI handle for the current physical workstation used by the AES which is required to open a virtual screen workstation.

Since

KAOS 1.4

See also

v_opnvwk(), mt_graf_handle().

Note

There is currently no defined method of handling an error generated by this function.