Home AESAES Geneva libraryGeneva library Scrap libraryScrap library

8.13 Graphics library

This library takes on the management of rectangles; so one can draw a rectangle that moves automatically with the mouse pointer, say. In all, the following functions are available:

graf_dragbox Moves a rectangular outline frame
graf_growbox Animates a growing rectangle
graf_handle Obtains ID of the AES workstation
graf_mbox Displays moving rectangle
graf_mkstate Obtains state of mouse pointer and keyboard
graf_mouse Alters appearance of mouse pointer
graf_multirubber Displays two 'rubber band' outline rectangles
graf_rubbox Display 'rubber band' outline rectangle
graf_shrinkbox Animates a shrinking rectangle
graf_slidebox Obtains slider position
graf_watchbox Selects an object and supervises mouse movements referring to this object
graf_wwatchbox Selects an object in a window and supervises mouse movements referring to this object.
graf_xhandle Obtains ID of the AES workstation
x_graf_blit Blit one area of the screen to another location
x_graf_rast2rez Convert a bit image
x_graf_rubberbox Extended rubberband box drawing

Note: Of these, graf_handle has earned special importance because with its aid the ID of the physical screen workstation can be obtained.

See also: Style guidelines

8.13.1 graf_dragbox

Name: »Graphics drag box« - Move a rectangular outline frame with the mouse.
 
Opcode: 71
 
Syntax: int16_t graf_dragbox ( int16_t gr_dwidth, int16_t gr_dheight, int16_t gr_dstartx, int16_t gr_dstarty, int16_t gr_dboundx, int16_t gr_dboundy, int16_t gr_dboundw, int16_t gr_dboundh, int16_t *gr_dfinishx, int16_t *gr_dfinishy );
 
Description: The call graf_dragbox allows the movement a small, rectangular outline frame within a larger bounding rectangle. Its most frequent use is to give the user a visual clue when an object is being dragged on the screen. The following apply:
 
Parameter Meaning
   
gr_dwidth Initial width,
gr_dheight Height,
gr_dstartx X-coordinate, and
gr_dstarty Y-coordinate of the frame to be moved
gr_dboundx X-coordinate,
gr_dboundy Y-coordinate,
gr_dboundw Width, and
gr_dboundh Height of the bounding rectangle
gr_dfinishx X-coordinate, and
gr_dfinishy Y-coordinate of the frame destination when the mouse button is released
Return value: An error has arisen only if the value 0 is returned.
 
Availability: All AES versions.
 
Group: Graphics library
 
See also: Binding
 

8.13.1.1 Bindings for graf_dragbox

C: int16_t graf_dragbox ( int16_t gr_dwidth, int16_t gr_dheight, int16_t gr_dstartx, int16_t gr_dstarty, int16_t gr_dboundx, int16_t gr_dboundy, int16_t gr_dboundw, int16_t gr_dboundh, int16_t *gr_dfinishx, int16_t *gr_dfinishy );
 
Binding:
 
int16_t graf_dragbox (int16_t gr_dwidth, int16_t gr_dheight,
                      int16_t gr_dstartx, int16_t gr_dstarty,
                      int16_t gr_dboundx, int16_t gr_dboundy,
                      int16_t gr_dboundw, int16_t gr_dboundh,
                      int16_t *gr_dfinishx,
                      int16_t *gr_dfinishy)
{
   int_in[0] = gr_dwidth;
   int_in[1] = gr_dheight;
   int_in[2] = gr_dstartx;
   int_in[3] = gr_dstarty;
   int_in[4] = gr_dboundx;
   int_in[5] = gr_dboundy;
   int_in[6] = gr_dboundw;
   int_in[7] = gr_dboundh;

   crys_if (71);

   *gr_dfinishx = int_out[1];
   *gr_dfinishy = int_out[2];

   return ( int_out[0] );
}
GEM-Arrays:
 

Address Element Contents
control control[0] 71 # Function opcode
control+2 control[1] 8 # Entry in int_in
control+4 control[2] 3 # Entry in int_out
control+6 control[3] 0 # Entry in addr_in
control+8 control[4] 0 # Entry in addr_out
int_in int_in[0] gr_dwidth
int_in+2 int_in[1] gr_dheight
int_in+4 int_in[2] gr_dstartx
int_in+6 int_in[3] gr_dstarty
int_in+8 int_in[4] gr_dboundx
int_in+10 int_in[5] gr_dboundy
int_in+12 int_in[6] gr_dboundw
int_in+14 int_in[7] gr_dboundh
int_out int_out[0] Return value
int_out+2 int_out[1] gr_dfinishx
int_out+4 int_out[2] gr_dfinishy

8.13.2 graf_growbox

Name: »Graphics grow box« - Draw an animated, growing rectangle.
 
Opcode: 73
 
Syntax: int16_t graf_growbox ( int16_t gr_gstx, int16_t gr_gsty, int16_t gr_gstwidth, int16_t gr_gstheight, int16_t gr_gfinx, int16_t gr_gfiny, int16_t gr_gfinwidth, int16_t gr_gfinheight );
 
Description: The call graf_growbox draws an animated rectangular outline box growing from one set of coordinates to another (complement to graf_shrinkbox). The following apply:
 

Parameter Meaning
gr_gstx X-coordinate,
gr_gsty Y-coordinate,
gr_gstwidth Width, and
gr_gstheight Height of the outline box at start
gr_gfinx X-coordinate,
gr_gfiny Y-coordinate,
gr_gfinwidth Width, and
gr_gfinheight Height of the outline box at end

Note: As of PC-GEM Version 2.0, this call is ignored. The reason given for this is the legal dispute between Apple and Digital Research.
 
Return value: An error has arisen only if the value 0 is returned.
 
Availability: All AES versions.
 
Group: Graphics library
 
See also: Binding   form_dial   graf_shrinkbox
 

8.13.2.1 Bindings for graf_growbox

C: int16_t graf_growbox ( int16_t gr_gstx, int16_t gr_gsty, int16_t gr_gstwidth, int16_t gr_gstheight, int16_t gr_gfinx, int16_t gr_gfiny, int16_t gr_gfinwidth, int16_t gr_gfinheight );
 
Binding:
 
int16_t graf_growbox (int16_t gr_gstx, int16_t gr_gsty,
                      int16_t gr_gstwidth,
                      int16_t gr_gstheight, int16_t gr_gfinx,
                      int16_t gr_gfiny, int16_t gr_gfinwidth,
                      int16_t gr_gfinheight)
{
   int_in[0] = gr_gstx;
   int_in[1] = gr_gsty;
   int_in[2] = gr_gstwidth;
   int_in[3] = gr_gstheight;
   int_in[4] = gr_gfinx;
   int_in[5] = gr_gfiny;
   int_in[6] = gr_gfinwidth;
   int_in[7] = gr_gfinheight;

   return ( crys_if(73) );
}
GEM-Arrays:
 

Address Element Contents
control control[0] 73 # Function opcode
control+2 control[1] 8 # Entry in int_in
control+4 control[2] 1 # Entry in int_out
control+6 control[3] 0 # Entry in addr_in
control+8 control[4] 0 # Entry in addr_out
int_in int_in[0] gr_gstx
int_in+2 int_in[1] gr_gsty
int_in+4 int_in[2] gr_gstwidth
int_in+6 int_in[3] gr_gstheight
int_in+8 int_in[4] gr_gfinx
int_in+10 int_in[5] gr_gfiny
int_in+12 int_in[6] gr_gfinwidth
int_in+14 int_in[7] gr_gfinheight
int_out int_out[0] Return value

8.13.3 graf_handle

Name: »Graphics handle« - Obtain the VDI handle of the AES workstation.
 
Opcode: 77
 
Syntax: int16_t graf_handle ( int16_t *gr_hwchar, int16_t *gr_hhchar, int16_t *gr_hwbox, int16_t *gr_hhbox );
 
Description: The call graf_handle obtains the ID of the physical screen workstation on which the AES outputs, as well as some further information which will be filled in the following parameters when the function exits:
 
Parameter Meaning
   
gr_hwchar Width, and
gr_hhchar Height of a character from the system font, in points
gr_hwbox Width, and
gr_hhbox Height of a cell into which any character from the system font will fit completely

Note: The information from the parameters gr_hwbox or gr_hhbox is used be the AES for the width of the individual window components.
 
Return value: The function returns the ID (handle) of the opened AES workstation.
 
Availability: All AES versions.
 
Group: Graphics library
 
See also: Binding   v_opnvwk   graf_xhandle
 

8.13.3.1 Bindings for graf_handle

C: int16_t graf_handle ( int16_t *gr_hwchar, int16_t *gr_hhchar, int16_t *gr_hwbox, int16_t *gr_hhbox );
 
Binding:
 
int16_t graf_handle (int16_t *gr_hwchar, int16_t *gr_hhchar,
                     int16_t *gr_hwbox, int16_t *gr_hhbox)
{
   crys_if (77);

   *gr_hwchar = int_out[1];
   *gr_hhchar = int_out[2];
   *gr_hwbox  = int_out[3];
   *gr_hhbox  = int_out[4];

   return ( int_out[0] );
}
GEM-Arrays:
 

Address Element Contents
control control[0] 77 # Function opcode
control+2 control[1] 0 # Entry in int_in
control+4 control[2] 5 # Entry in int_out
control+6 control[3] 0 # Entry in addr_in
control+8 control[4] 0 # Entry in addr_out
int_out int_out[0] Return value
int_out+2 int_out[1] gr_hwchar
int_out+4 int_out[2] gr_hhchar
int_out+6 int_out[3] gr_hwbox
int_out+8 int_out[4] gr_hhbox

8.13.4 graf_mbox/graf_movebox

Name: »Graphics move box« - Move a rectangle with the mouse.
 
Opcode: 72
 
Syntax: int16_t graf_movebox ( int16_t gr_mwidth, int16_t gr_mheight, int16_t gr_msourcex, int16_t gr_msourcey, int16_t gr_mdestx, int16_t gr_mdesty );
 
or
 
int16_t graf_mbox( ... )
 
Description: The call graf_movebox draws a rectangle of constant size that moves with the mouse pointer, and is used to give the user a visual 'clue' to an action undertaken by an application. The following apply:
 

Parameter Meaning
gr_mwidth Width, and
gr_mheight Height of the rectangle
gr_msourcex X-coordinate, and
gr_msourcey Y-coordinate of top left corner at start
gr_mdestx X-coordinate, and
gr_mdesty Y-coordinate of top left corner at end

Note: The function can be used, for instance, when the movement of an icon is not permitted (e.g. dragging the printer icon onto the wastebasket icon) and so it is to be placed back at its original position.
 
In older GEM documentation this function is also called 'graf_mbox'!
 
Return value: An error has arisen only if the value 0 is returned.
 
Availability: All AES versions.
 
Group: Graphics library
 
See also: Binding
 

8.13.4.1 Bindings for graf_mbox

C: int16_t graf_mbox ( int16_t gr_mwidth, int16_t gr_mheight, int16_t gr_msourcex, int16_t gr_msourcey, int16_t gr_mdestx, int16_t gr_mdesty );
 
oder
 
int16_t graf_movebox ( ... )
 
Binding:
 
int16_t graf_mbox (int16_t gr_mwidth, int16_t gr_mheight,
                   int16_t gr_msourcex, int16_t gr_msourcey,
                   int16_t gr_mdestx, int16_t gr_mdesty)
{
   int_in[0] = gr_mwidth;
   int_in[1] = gr_mheight;
   int_in[2] = gr_msourcex;
   int_in[3] = gr_msourcey;
   int_in[4] = gr_mdestx;
   int_in[5] = gr_medsty;

   return ( crys_if(72) );
}
GEM-Arrays:
 

Address Element Contents
control control[0] 72 # Function opcode
control+2 control[1] 6 # Entry in int_in
control+4 control[2] 1 # Entry in int_out
control+6 control[3] 0 # Entry in addr_in
control+8 control[4] 0 # Entry in addr_out
int_in int_in[0] gr_mwidth
int_in+2 int_in[1] gr_mheight
int_in+4 int_in[2] gr_msourcex
int_in+6 int_in[3] gr_msourcey
int_in+8 int_in[4] gr_mdestx
int_in+10 int_in[5] gr_mdesty
int_out int_out[0] Return value

8.13.5 graf_mkstate

Name: »Graphics mouse and keyboard status« - Obtain the state of the mouse and keyboard.
 
Opcode: 79
 
Syntax: int16_t graf_mkstate ( int16_t *gr_mkmx, int16_t *gr_mkmy, int16_t *gr_mkmstate, int16_t *gr_mkkstate );
 
Description: The call graf_mkstate obtains the current mouse position as well as the state of the mouse buttons and the so-called 'special' keys ([Shift], [Control], [Alternate]). The following apply:
 
Parameter Meaning
   
gr_mkmx X-position, and
gr_mkmy Y-position of the mouse pointer
gr_mkmstate State of mouse buttons (Bit 0 = left button, etc.)
gr_mkkstate 'Special' keys of keyboard as bit-vector:
0x0001 = Right [Shift] key
0x0002 = Left [Shift] key
0x0004 = [Control] key
0x0008 = [Alternate] key

Note: A bit is set when the corresponding mouse button or key is pressed down.
 
Return value: This is always a 1.
 
Availability: All AES versions.
 
Group: Graphics library
 
See also: Binding   evnt_button
 

8.13.5.1 Bindings for graf_mkstate

C: int16_t graf_mkstate ( int16_t *gr_mkmx, int16_t *gr_mkmy, int16_t *gr_mkmstate, int16_t *gr_mkkstate );
 
Binding:
 
int16_t graf_mkstate (int16_t *gr_mkmx, int16_t *gr_mkmy,
                      int16_t *gr_mkmstate,
                      int16_t *gr_mkkstate)
{
   crys_if (79);

   *gr_mkmx     = int_out[1];
   *gr_mkmy     = int_out[2];
   *gr_mkmstate = int_out[3];
   *gr_mkkstate = int_out[4];

   return ( int_out[0] );
}
GEM-Arrays:
 

Address Element Contents
control control[0] 79 # Function opcode
control+2 control[1] 0 # Entry in int_in
control+4 control[2] 5 # Entry in int_out
control+6 control[3] 0 # Entry in addr_in
control+8 control[4] 0 # Entry in addr_out
int_out int_out[0] Return value
int_out+2 int_out[1] gr_mkmx
int_out+4 int_out[2] gr_mkmy
int_out+6 int_out[3] gr_mkmstate
int_out+8 int_out[4] gr_mkkstate

8.13.6 graf_mouse

Name: »Graphics mouse« - Change the appearance of the mouse pointer.
 
Opcode: 78
 
Syntax: int16_t graf_mouse ( int16_t gr_monumber, MFORM *gr_mofaddr );
 
Description: The call graf_mouse permits changing the appearance of the mouse pointer. The following apply for the parameter gr_monumber:
 

  gr_monumber Meaning
ARROW 0 Arrow
TEXT_CRSR 1 Text cursor
HOURGLASS 2 Hourglass, bee
BUSY_BEE 2 See HOURGLASS
BUSYBEE 2 See HOURGLASS
POINT_HAND 3 Pointing hand
FLAT_HAND 4 Flat hand
THIN_CROSS 5 Thin crosshairs
THICK_CROSS 6 Thick crosshairs
OUTLN_CROSS 7 Outlined crosshairs
  8 Sizer (N.AES)
X_LFTRT 8 Left-right arrow (Geneva)
  9 Horizontal arrows (N.AES)
X_UPDOWN 9 Up-down arrow (Geneva)
  10 Vertical arrows (N.AES)
USER_DEF 255 User-defined mouse form
M_OFF 256 Switch off mouse pointer
M_ON 257 Switch on mouse pointer
M_SAVE 258 Save current mouse form
M_RESTORE 259 Restore last shape
M_LAST 260 Restore most recently saved form
M_PREVIOUS 260 See M_LAST
XACRS_BUBBLE_DISC 270 The Data Uncertain logo (XaAES)
XACRS_RESIZER 271 The 'resize window' cursors (XaAES)
XACRS_NE_SIZER 272 (XaAES)
XACRS_MOVER 273 The 'move window' cursor (XaAES)
XACRS_VERTSIZER 274 The 'resize vertically' cursor (XaAES)
XACRS_HORSIZER 275 The 'resize horizontally' cursor (XaAES)
XACRS_POINTSLIDE 276 The 'two-arrows pointing inwards'
    cursor to pinpoint slider position(XaAES)
X_MRESET 1000 (Geneva)
X_MGET 1001 (Geneva)
X_SET_SHAPE 1100 (Geneva)

If gr_monumber = USER_DEF, then gr_mofaddr is a pointer to the MFORM structure that sets the appearance of the mouse pointer.
 
Note: One should ensure that outside of the working area of one's own window, the mouse pointer takes the form of an arrow or hourglass.
 
In the event that the application must change the mouse form, set the highest bit (bit 15) of gr_monumber to 1 and OR it with the desired mouse form index. After finishing the work, call graf_mouse with the value 0 to set the mouse back to an arrow.
 
M_FORCE   0x8000
 
Whether modes 258-260 are available, or whether the mouse form is managed locally for each application can be inquired with appl_getinfo (opcode 8).
 
X_MRESET (1000)


 
graf_mouse( X_MRESET, 0L );
 
Resets the mouse so that it is 'on' just once, and also updates graf_mouse's idea of the hide count.
 

X_MGET (1001)


 
hidecount = graf_mouse( X_MGET, MFORM *mouse );
 
In this mode, if mouse is non-zero, then the MFORM it points to is filled-in with the shape of the last mouse set with graf_mouse. 'hidecount' gets the number of times the mouse was hidden using graf_mouse(M_OFF...). If this number is greater than zero, the mouse is hidden that number of times. If it is zero, the mouse is shown once. If it is less than zero, the mouse is 'shown' more than once.
 

X_SET_SHAPE (1100)


 
graf_mouse( X_SET_SHAPE+index, ANI_MOUSE *mouse_form );
 
Change the shape of the mouse form whose number is index. The ANI_MOUSE structure contains up to 32 mouse shapes to be animated in a continuous loop while that particular mouse shape is being displayed.
If the frames portion of the ANI_MOUSE structure is one, then no animation is performed. Otherwise, it should be the number of frames contained in the mouse animation sequence. The delay value is the number of 50 Hz timer ticks to pause between each frame in the animation. The form portion of the structure only needs to be initialized for the number of frames, so if there are only two frames, this means that only form[0] and form[1] are used. If a NULL pointer is passed instead of a pointer to an ANI_MOUSE structure, then the mouse shape is restored to its default.
It does not matter if the application which sets a new shape terminates without resetting the mouse shape, as this call allocates memory internally to hold the new shape data.
 

Return value: An error has arisen only if the value 0 is returned.
 
Availability: All AES versions.
 
Group: Graphics library
 
See also: Binding   Mouse clicks and shapes
 

8.13.6.1 Bindings for graf_mouse

C: int16_t graf_mouse ( int16_t gr_monumber, MFORM *gr_mofaddr );
 
Binding:
 
int16_t graf_mouse (int16_t gr_monumber, MFORM *gr_mofaddr)
{
   int_in[0]  = gr_monumber;
   addr_in[0] = gr_mofaddr;

   return ( crys_if(78) );
}
GEM-Arrays:
 

Address Element Contents
control control[0] 78 # Function opcode
control+2 control[1] 1 # Entry in int_in
control+4 control[2] 1 # Entry in int_out
control+6 control[3] 1 # Entry in addr_in
control+8 control[4] 0 # Entry in addr_out
int_in int_in[0] gr_monumber
addr_in addr_in[0] gr_mofaddr
int_out int_out[0] Return value

8.13.7 graf_multirubber

Name: »Graphics rubberbox« - Draw two 'rubber band' outline rectangles on the screen.
 
Opcode: 69
 
Syntax: int16_t graf_multirubber(int16_t x, int16_t y, int16_t minw, int16_t minh, GRECT *rec, int16_t *outw, int16_t *outh)
 
Description: The call graf_multirubber displays a pair of 'rubber bands' in the form of rectangles on the screen, whose top left corner remains fixed and bottom right corner can be moved while the left mouse button is held down. Similar to graf_rubberbox, but with two rectangles. The following apply:
 
Parameter Meaning
   
x X-coordinate, and
y Y-coordinate of initial corner
minw Minimum width of rubber band box
minh Minimum height of rubber band box
rec  
outw Width of rubber band box when releasing the mouse button
outh Height of rubber band box when releasing the mouse button

Note: For the reasons mentioned above, the function should only be called with an already pressed mouse button, since it returns when the button is released. It's interesting that the minimum width and height parameters may also take negative values; the rubber band may then be stretched from bottom right to top left.
 
Return value: An error has arisen only if the value 0 is returned.
 
Availability: The function is only available under N.AES.
 
Group: Graphics library
 
See also: Binding   graf_rubberbox   x_graf_rubberbox
 

8.13.7.1 Bindings for graf_multirubber

C: int16_t graf_multirubber(int16_t x, int16_t y, int16_t minw, int16_t minh, GRECT *rec, int16_t *outw, int16_t *outh)
 
Binding:
 
int16_t graf_multirubber (int16_t x, int16_t y, int16_t minw,
                          int16_t minh, GRECT *rec,
                          int16_t *outw, int16_t *outh)
{
   int_in[0] = x;
   int_in[1] = y;
   int_in[2] = minw;
   int_in[3] = minh;

   addr_in[0] = rec;

   crys_if (69);

   *outw = int_out[1];
   *outh = int_out[2];

   return ( int_out[0] );
}
GEM-Arrays:
 

Address Element Contents
control control[0] 69 # Function opcode
control+2 control[1] 4 # Entry in int_in
control+4 control[2] 3 # Entry in int_out
control+6 control[3] 1 # Entry in addr_in
control+8 control[4] 0 # Entry in addr_out
int_in int_in[0] x
int_in+2 int_in[1] y
int_in+4 int_in[2] minw
int_in+6 int_in[3] minh
addr_in addr_in[0] rec
int_out int_out[0] Return value
int_out+2 int_out[1] outw
int_out+4 int_out[2] outh

8.13.8 graf_rubberbox/graf_rubbox

Name: »Graphics rubberbox« - Draw 'rubber band' outline rectangle on the screen.
 
Opcode: 70
 
Syntax: int16_t graf_rubberbox ( int16_t gr_rx, int16_t gr_ry, int16_t gr_minwidth, int16_t gr_minheight, int16_t *gr_rlastwidth, int16_t *gr_rlastheight );
 
or
 
int16_t graf_rubbox ( ... );
 
Description: The call graf_rubberbox displays a 'rubber band' in the form of a rectangle on the screen, whose top left corner remains fixed and its bottom right corner can be moved while the left mouse button is held down. The following apply:
 
Parameter Meaning
   
gr_rx X-coordinate, and
gr_ry Y-coordinate of initial corner
gr_minwidth Minimum width of rubber band box
gr_minheight Minimum height of rubber band box
gr_rlastwidth Width, and
gr_rlastheight Height of rubber band box when releasing the mouse button

Note: For the reasons mentioned above, the function should only be called with an already pressed mouse button, since it returns when the button is released. It's interesting that the minimum width and height parameters may also take negative values; the rubber band may then be stretched from bottom right to top left.
 
In older GEM documentation this function is also called 'graf_rubbox'!
 
Return value: An error has arisen only if the value 0 is returned.
 
Availability: All AES versions.
 
Group: Graphics library
 
See also: Binding   graf_multirubber   x_graf_rubberbox
 

8.13.8.1 Bindings for graf_rubberbox

C: int16_t graf_rubberbox ( int16_t gr_rx, int16_t gr_ry, int16_t gr_minwidth, int16_t gr_minheight, int16_t *gr_rlastwidth, int16_t *gr_rlastheight );
 
or
 
int16_t graf_rubbox ( ... )
 
Binding:
 
int16_t graf_rubbox (int16_t gr_rx, int16_t gr_ry,
                     int16_t gr_minwidth,
                     int16_t gr_minheight,
                     int16_t *gr_rlastwidth,
                     int16_t *gr_rlastheight)
{
   int_in[0] = gr_rx;
   int_in[1] = gr_ry;
   int_in[2] = gr_minwidth;
   int_in[3] = gr_minheight;

   crys_if (70);

   *gr_rlastwidth = int_out[1];
   *gr_lastheight = int_out[2];

   return ( int_out[0] );
}
GEM-Arrays:
 

Address Element Contents
control control[0] 70 # Function opcode
control+2 control[1] 4 # Entry in int_in
control+4 control[2] 3 # Entry in int_out
control+6 control[3] 0 # Entry in addr_in
control+8 control[4] 0 # Entry in addr_out
int_in int_in[0] gr_rx
int_in+2 int_in[1] gr_ry
int_in+4 int_in[2] gr_minwidth
int_in+6 int_in[3] gr_minheight
int_out int_out[0] Return value
int_out+2 int_out[1] gr_rlastwidth
int_out+4 int_out[2] gr_rlastheight

8.13.9 graf_shrinkbox

Name: »Graphics shrink box« - Draw an animated shrinking rectangle on the screen.
 
Opcode: 74
 
Syntax: int16_t graf_shrinkbox ( int16_t gr_sfinx, int16_t gr_sfiny, int16_t gr_sfinwidth, int16_t gr_sfinheight, int16_t gr_sstx, int16_t gr_ssty, int16_t gr_sstwidth, int16_t gr_sstheight );
 
Description: The call graf_shrinkbox draws an animated rectangular outline box shinking from one set of coordinates to another (complement to graf_growbox). The following apply:
 

Parameter Meaning
gr_sfinx X-coordinate,
gr_sfiny Y-coordinate,
gr_sfinwidth Width, and
gr_sfinheight Height of outline box at end
gr_sstx X-coordinate,
gr_ssty Y-coordinate,
gr_sstwidth Width, and
gr_sstheight Height of outline box at start

Note: As of PC-GEM Version 2.0, this call is ignored. The reason given for this is the legal dispute between Apple and Digital Research.
 
Return value: An error has arisen only if the value 0 is returned.
 
Availability: All AES versions.
 
Group: Graphics library
 
See also: Binding   form_dial   graf_growbox
 

8.13.9.1 Bindings for graf_shrinkbox

C: int16_t graf_shrinkbox ( int16_t gr_sfinx, int16_t gr_sfiny, int16_t gr_sfinwidth, int16_t gr_sfinheight, int16_t gr_sstx, int16_t gr_ssty, int16_t gr_sstwidth, int16_t gr_sstheight );
 
Binding:
 
int16_t graf_shrinkbox (int16_t gr_sfinx, int16_t gr_sfiny,
                        int16_t gr_sfinwidth,
                        int16_t gr_sfinheight,
                        int16_t gr_sstx, int16_t gr_ssty,
                        int16_t gr_sstwidth,
                        int16_t gr_sstheight)
{
   int_in[0] = gr_sfinx;
   int_in[1] = gr_sfiny;
   int_in[2] = gr_sfinwidth;
   int_in[3] = gr_sfinheight;
   int_in[4] = gr_sstx;
   int_in[5] = gr_ssty;
   int_in[6] = gr_sstwidth;
   int_in[7] = gr_sstheight;

   return ( crys_if(74) );
}
GEM-Arrays:
 

Address Element Contents
control control[0] 74 # Function opcode
control+2 control[1] 8 # Entry in int_in
control+4 control[2] 1 # Entry in int_out
control+6 control[3] 0 # Entry in addr_in
control+8 control[4] 0 # Entry in addr_out
int_in int_in[0] gr_sfinx
int_in+2 int_in[1] gr_sfiny
int_in+4 int_in[2] gr_sfinwidth
int_in+6 int_in[3] gr_sfinheight
int_in+8 int_in[4] gr_sstx
int_in+10 int_in[5] gr_ssty
int_in+12 int_in[6] gr_sstwidth
int_in+14 int_in[7] gr_sstheight
int_out int_out[0] Return value

8.13.10 graf_slidebox

Name: »Graphics slide box« - Obtain slider position etc.
 
Opcode: 76
 
Syntax: int16_t graf_slidebox ( OBJECT *gr_slptree, int16_t gr_slparent, int16_t gr_slobject, int16_t gr_slvh );
 
Description: The call graf_slidebox serves to inquire the position of sliders within the bounds of its parent object. The following apply:
 
Parameter Meaning
   
gr_slptree Address of object tree holding parent and child objects
gr_slparent Index of the parent rectangle
gr_slobject Index of the child rectangle to be moved (slider)
gr_slvh Direction of movement:
0 = Move horizontally
1 = Move vertically

Note: The function may only be called with an already pressed mouse button, since it returns immediately when the button is released.
 
It can be used also with sliders built into dialogs: Make the slider a TOUCHEXIT object and call this function when it is clicked on.
 
In Geneva the parameter gr_slvh has changed slightly.
 
Return value: The function returns the relative position of the slider, between 0 (far left or very top) and 1000 (far right or very bottom).
 
Availability: All AES versions.
 
Group: Graphics library
 
See also: Binding   OBJECT
 

8.13.10.1 graf_slidebox from Geneva

The meaning of the gr_slvh parameter has changed slightly, to provide for real-time updating of sliders:

LSB 0 for horizontal slider, 1 for vertical
MSB 0 for old-style, dotted outline drag box
  1 to describe the area to be scrolled in real-time
  2 to initialize real-time scrolling
  3 to process the scroll bar in real time

To use real-time scroll bars, a program does the following:

  1. Call graf_slidebox with gr_slvh mode 0x1XX (where "XX" is 00 for a horizontal slider, and 01 for vertical). In this mode, the gr_slparent parameter describes the size of the entire area to be scrolled, and gr_slobject describes the size of the area which is visible at one time. Both of these values can be in any units the programmer chooses.
     

  2. Call graf_slidebox with gr_slvh mode 0x2XX. In this mode, gr_slparent and gr_slobject have the same meaning they normally do. The return value will either be -1, if the user has released the slider, or it will be a number >= 0 which represents the new position of the slider. This number is based on the numbers passed in Step 1. The call does not return until the slider has either moved enough to change the position within the list, or the mouse button has been released.
     

  3. If the result of the last graf_slidebox call was -1, then continue on with the rest of the program. Otherwise, perform whatever action is necessary to redraw the list of items, starting at the returned index. The slider position is updated automatically by Geneva; the program must not alter it.
     

  4. Call graf_slidebox with gr_slvh mode 0x3XX. In this mode, gr_slparent and gr_slobject have the same meaning they normally do. Go to Step 3.
     

Example: Process a list of 100 items, 10 of which are visible at once

if( graf_slidebox( 0L, 100, 10, 0x101 ) >= 0 )
{
  i = graf_slidebox( object_tree, parent_obj, slider_obj, 0x201 );
  while( i>=0 )
  {
     redraw_list_starting_at(i);
     i = graf_slidebox( object_tree, parent_obj, slider_obj, 0x301 );
  }
}

8.13.10.2 Bindings for graf_slidebox

C: int16_t graf_slidebox ( OBJECT *gr_slptree, int16_t gr_slparent, int16_t gr_slobject, int16_t gr_slvh );
 
Binding:
 
int16_t graf_slidebox (OBJECT *gr_slptree,
                       int16_t gr_slparent,
                       int16_t gr_slobject,
                       int16_t gr_slvh)
{
   int_in[0]  = gr_slparent;
   int_in[1]  = gr_slobject;
   int_in[2]  = gr_slvh;
   addr_in[0] = gr_slptree;

   return ( crys_if(76) );
}
GEM-Arrays:
 

Address Element Contents
control control[0] 76 # Function opcode
control+2 control[1] 3 # Entry in int_in
control+4 control[2] 1 # Entry in int_out
control+6 control[3] 1 # Entry in addr_in
control+8 control[4] 0 # Entry in addr_out
int_in int_in[0] gr_slparent
int_in+2 int_in[1] gr_slobject
int_in+4 int_in[2] gr_slvh
addr_in addr_in[0] gr_slptree
int_out int_out[0] Return value

8.13.11 graf_watchbox

Name: »Graphics watch box« - Select an object and supervise mouse movements referring to this object.
 
Opcode: 75
 
Syntax: int16_t graf_watchbox ( OBJECT *gr_wptree, int16_t gr_wobject, int16_t gr_winstate, int16_t gr_woutstate );
 
Description: The call graf_watchbox sets the status of an object, depending on the position of the mouse pointer (whether it is within or outside the bounds of the object) while the left mouse button is held down. The following apply:
 
Parameter Meaning
   
gr_wptree Address of root object of object tree
gr_wpobject Index of the object to watch
gr_winstate Object status when the mouse pointer is within the boundary:
NORMAL (0x0000)
SELECTED (0x0001)
CROSSED (0x0002)
CHECKED (0x0004)
DISABLED (0x0008)
OUTLINED (0x0010)
SHADOWED (0x0020)
gr_woutstate Object status when the mouse pointer is outside the boundary:

Note: The function returns when the mouse button is released, so it should only be made while the button is depressed.
 
Return value: The function returns the position of the mouse pointer at the release of the button (0 = outside the object boundary, 1 = inside the boundary).
 
Availability: All AES versions.
 
Group: Graphics library
 
See also: Binding   graf_wwatchbox   OBJECT
 

8.13.11.1 Bindings for graf_watchbox

C: int16_t graf_watchbox ( OBJECT *gr_wptree, int16_t gr_wobject, int16_t gr_winstate, int16_t gr_woutstate );
 
Binding:
 
int16_t graf_watchbox (OBJECT *gr_wptree, int16_t gr_wobject,
                       int16_t gr_winstate,
                       int16_t gr_woutstate)
{
   int_in[0]  = 0;
   int_in[1]  = gr_wobject;
   int_in[2]  = gr_winstate;
   int_in[3]  = gr_woutstate;

   addr_in[0] = gr_wptree;

   return ( crys_if(75) );
}
GEM-Arrays:
 

Address Element Contents
control control[0] 75 # Function opcode
control+2 control[1] 4 # Entry in int_in
control+4 control[2] 1 # Entry in int_out
control+6 control[3] 1 # Entry in addr_in
control+8 control[4] 0 # Entry in addr_out
int_in int_in[0] 0
int_in+2 int_in[1] gr_wobject
int_in+4 int_in[2] gr_winstate
int_in+6 int_in[3] gr_woutstate
addr_in addr_in[0] gr_wptree
int_out int_out[0] Return value

8.13.12 graf_wwatchbox

Name: »Graphics window watch box« - Select an object in a window and supervise mouse movements referring to this object.
 
Opcode: 62
 
Syntax: int16_t graf_wwatchbox ( OBJECT *gr_wptree, int16_t gr_wobject, int16_t gr_winstate, int16_t gr_woutstate, int16_t whandle );
 
Description: The call graf_wwatchbox sets the object status of an object in a window, depending on the position of the mouse pointer (whether it is within or outside the bounds of the object) while the left mouse button is held down. The following apply:
 
Parameter Meaning
   
gr_wptree Address of root object of object tree
gr_wpobject Index of the object to watch
gr_winstate Object status when the mouse pointer is within the boundary:
NORMAL (0x0000)
SELECTED (0x0001)
CROSSED (0x0002)
CHECKED (0x0004)
DISABLED (0x0008)
OUTLINED (0x0010)
SHADOWED (0x0020)
gr_woutstate Object status when the mouse pointer is outside the boundary:
whandle Window identifier

Note: The function returns when the mouse button is released, so it should only be made while the button is depressed. It basically corresponds to graf_watchbox with the difference that here the rectangle-list of the window is taken into account.
 
Return value: The function returns the position of the mouse pointer at the release of the button (0 = outside the object boundary, 1 = inside the boundary).
 
Availability: The function is available in MagiC as of Version 5.10.
 
Group: Graphics library
 
See also: Binding   graf_watchbox   OBJECT
 

8.13.12.1 Bindings for graf_wwatchbox

C: int16_t graf_wwatchbox ( OBJECT *gr_wptree, int16_t gr_wobject, int16_t gr_winstate, int16_t gr_woutstate, int16_t whandle );
 
Binding:
 
int16_t graf_wwatchbox (OBJECT *gr_wptree, int16_t gr_wobject,
                        int16_t gr_winstate,
                        int16_t gr_woutstate,
                        int16_t whandle)
{
   int_in[0]  = gr_wobject;
   int_in[1]  = gr_winstate;
   int_in[2]  = gr_woutstate;
   int_in[3]  = whandle;

   addr_in[0] = gr_wptree;

   return ( crys_if(62) );
}
GEM-Arrays:
 

Address Element Contents
control control[0] 62 # Function opcode
control+2 control[1] 4 # Entry in int_in
control+4 control[2] 1 # Entry in int_out
control+6 control[3] 1 # Entry in addr_in
control+8 control[4] 0 # Entry in addr_out
int_in int_in[0] gr_wobject
int_in+2 int_in[1] gr_winstate
int_in+4 int_in[2] gr_woutstate
int_in+6 int_in[3] whandle
addr_in addr_in[0] gr_wptree
int_out int_out[0] Return value

8.13.13 graf_xhandle

Name: »Graphics handle« - Obtain ID of the VDI workstation.
 
Opcode: 77
 
Syntax: int16_t graf_xhandle ( int16_t *gr_hwchar, int16_t *gr_hhchar, int16_t *gr_hwbox, int16_t *gr_hhbox, int16_t *device );
 
Description: The call graf_xhandle obtains the ID of the screen workstation to which the AES outputs. The following apply:
 
Parameter Meaning
   
gr_hwchar Width, and
gr_hhchar Height of a character from the system font, in points
gr_hwbox Width, and
gr_hhbox Height of a cell into which any character from the system font fits completely
device Workstation handle of the AES (vdi_device)

Note: The information from the parameters gr_hwbox or gr_hhbox is used be the AES for the width of the individual window components.
 
Return value: The function returns the ID (handle) of the opened VDI workstation.
 
Availability: Since KAOS 1.4
 
Group: Graphics library
 
See also: Binding   v_opnvwk   graf_handle
 

8.13.13.1 Bindings for graf_xhandle

C: int16_t graf_xhandle ( int16_t *gr_hwchar, int16_t *gr_hhchar, int16_t *gr_hwbox, int16_t *gr_hhbox, int16_t *device );
 
Binding:
 
int16_t graf_xhandle (int16_t *gr_hwchar, int16_t *gr_hhchar,
                      int16_t *gr_hwbox, int16_t *gr_hhbox,
                      int16_t *device )
{
   crys_if (77);

   *gr_hwchar = int_out[1];
   *gr_hhchar = int_out[2];
   *gr_hwbox  = int_out[3];
   *gr_hhbox  = int_out[4];
   *device    = int_out[5];

   return ( int_out[0] );
}
GEM-Arrays:
 

Address Element Contents
control control[0] 77 # Function opcode
control+2 control[1] 0 # Entry in int_in
control+4 control[2] 6 # Entry in int_out
control+6 control[3] 0 # Entry in addr_in
control+8 control[4] 0 # Entry in addr_out
int_out int_out[0] Return value
int_out+2 int_out[1] gr_hwchar
int_out+4 int_out[2] gr_hhchar
int_out+6 int_out[3] gr_hwbox
int_out+8 int_out[4] gr_hhbox
int_out+10 int_out[5] device

8.13.14 x_graf_blit

Name: »Blit area«
 
Opcode: 28976
 
Syntax: int16_t x_graf_blit( GRECT *source, GRECT *dest );
 
Description:
 
Parameter Meaning
   
source Address of source rectangle or NULL
dest Address of destination rectangle or NULL

If source and dest are both non-zero, then the function simply blits the screen data from one rectangle to the other.
 
If dest is NULL, then the operation saves the area of the screen specified by source in its internal buffer. When the function ise=ater called with source NULL and dest properly set, it will restore the area in the (new) location.
 
The internal buffer is large enough to hold 1/2 of the current screen. Exceeding this will cause Geneva to try to allocate enough memory to hold the screen data. If this fails, a zero will be returned. Since this buffer is also used by Geneva to hold the screen data for alerts and menus, and also by the item selector, you should always surround code which uses x_graf_blit with wind_update calls.
 
This example displays a dialog and uses a blit to restore what was underneath it:
 
OBJECT *tree;
GRECT r;

rsrc_gaddr( 0, 0, &tree );                    /* get dialog        */
form_center( tree, &r.x, &r.y, &r.w, &r.h );  /* center it         */
wind_update( BEG_UPDATE );                    /* lock menu bar     */
x_graf_blit( &r, 0L );                        /* save what's there */
objc_draw( tree, 0, 8, r.x, r.y, r.w, r.h );  /* draw dialog       */
form_do( tree, 0 );                           /* get user response */
x_graf_blit( 0L, &r );                        /* now restore       */
wind_update( END_UPDATE );                    /* re-enable menus   */
Return value: 0 = Not enough memory for data to be stored
1 = No error
 
Availability: The function is only available under Geneva.
 
Group: Graphics library
 
See also: Binding
 

8.13.14.1 Bindings for x_graf_blit

C: int16_t x_graf_blit( GRECT *source, GRECT *dest );
 
Binding:
 
int16_t x_graf_blit( GRECT *source, GRECT *dest )
{
   addr_in[0] = source;
   addr_in[1] = dest;

   crys_if(28976);

   return ( int_out[0] );
}
GEM-Arrays:
 

Address Element Contents
control control[0] 28976 # Function opcode
control+2 control[1] 0 # Entry in int_in
control+4 control[2] 1 # Entry in int_out
control+6 control[3] 2 # Entry in addr_in
control+8 control[4] 0 # Entry in addr_out
addr_in addr_in[0] source
addr_in+4 addr_in[1] dest
int_out int_out[0] Return value

8.13.15 x_graf_rast2rez

Name: »« -
 
Opcode: 28978
 
Syntax: void x_graf_rast2rez( uint16_t *src_data, int32_t plane_len, int16_t old_planes, MFDB *mfdb, int16_t devspef );
 
Description:
 
Parameter Meaning
   
plane_len Size of one bitplane of data, in the dest. image, in bytes
old_planes Number of bitplanes in the source data
devspef If non-zero, the dest. image is in device-specific format. Otherwise, it is in VDI format.
src_data Pointer to the location of the source image's data.
mfdb Pointer to the MFDB describing the dest. image. All values must be correct, including the fd_addr.

This function will convert an image (in either VDI or device-specific format) to a format which can be displayed in the current video mode. This includes things like transforming a color image of fewer bitplanes than the current video mode into an image that can be displayed using vro_cpyfm. If the source is a monochrome image, it is much faster to simply use vrt_cpyfm to display it and avoid x_graf_rast2rez completely.
 
All values in mfdb describe the destination image, except for fd_stand, which describes the source image.
 
Example: Take the image described by source, convert it to the current video mode, and display it.
 
MFDB source,                           /* assume this is already filled-in */
     dest,
     screen;
     int32_t dest_size;

     dest = source;                    /* most values are the same to start */
     dest.fd_nplanes = current_video_planes;
     dest_size = (long)dest.fd_nplanes * dest.fd_wdwidth*2 * dest.fd_h;
     dest.fd_addr = Malloc(dest_size);
     x_graf_rast2rez( source.fd_addr, (long)source.fd_wdwidth*2 * source.fd_h,
                      source.fd_nplanes, &dest, 1 );
     screen.fd_addr = 0L;
     vro_cpyfm( vdi_handle, MD_REPLACE, array, &dest, &screen );
Return value: The function does not return a value.
 
Availability: The function is only available under Geneva since Release 004.
 
Group: Graphics library
 
See also: Binding
 

8.13.15.1 Bindings for x_graf_rast2rez

C: void x_graf_rast2rez( uint16_t *src_data, int32_t plane_len, int16_t old_planes, MFDB *mfdb, int16_t devspef );
 
Binding:
 
void x_graf_rast2rez( uint16_t *src_data, int32_t plane_len, int16_t old_planes,
                      MFDB *mfdb, int16_t devspef )
{
   int_in[0-1] = plane_len;
   int_in[2]   = old_planes;
   int_in[3]   = devspef;

   addr_in[0] = src_data;
   addr_in[1] = mfdb;

   crys_if(28978);

   return;
}
GEM-Arrays:
 

Address Element Contents
control control[0] 28978 # Function opcode
control+2 control[1] 4 # Entry in int_in
control+4 control[2] 0 # Entry in int_out
control+6 control[3] 2 # Entry in addr_in
control+8 control[4] 0 # Entry in addr_out
int_in int_in[0] plane_len
int_in+2 int_in[1] plane_len
addr_in addr_in[0] src_data
addr_in+4 addr_in[1] mfdb

8.13.16 x_graf_rubberbox

Name: »Extended rubberband box drawing«
 
Opcode: 28977
 
Syntax: int16_t x_graf_rubberbox(GRECT *area, GRECT *outer, int16_t minwidth, int16_t minheight, int16_t maxwidth, int16_t maxheight, int16_t snap, int16_t lag );
 
Description:
 
Parameter Meaning
   
area Initial size of the rubberband box
outer Outer limit of the rubberband box
minwidth Minimum width of the rubberband box
minheight Minimum height of the box
maxwidth Maximum width of the box
maxheight Maximum height of the box
snap Width/height increment
lag
0 = Follow mouse exactly
1 = Move relative to initial width and height

This function is similar to the AES function graf_rubberbox, but it offers several extensions.
 
  • The area parameter points to a GRECT structure which describes the dimensions of the initial rubberband box. If the lag parameter is zero, then the g_w and g_h elements of area are ignored.
  • outer describes the size of the outside bounding rectangle. The rubberband box will never go outside this box. If this is a NULL pointer, the outside boundaries will be the whole desktop.
  • minwidth and minheight describe the minimum height of the rubberband box; maxwidth and maxheight are the maximums. If either of the minimums are greater than zero, then extended resizing is possible. In this mode, the mouse can be dragged to the left or top edge of the minimum area, and resizing happens in a manner similar to Geneva's extended window resizing.
  • snap is the number of pixels to jump by. If this value is greater than 1, the rubberband box will only move when its width or height is an even increment of this value.
  • The lag parameter says whether the rubberband box should exactly follow the mouse, or if it should stay a constant distance from the mouse pointer. When resizing a window, Geneva uses the lag mode so that if the resize gadget is released before the mouse is moved, the window will not be resized.
Return value: 0 = The mouse was released prematurely
1 = No error
 
Availability: The function is only available under Geneva.
 
Group: Graphics library
 
See also: Binding   graf_rubberbox   graf_multirubber
 

8.13.16.1 Bindings for x_graf_rubberbox

C: int16_t x_graf_rubberbox(GRECT *area, GRECT *outer, int16_t minwidth, int16_t minheight, int16_t maxwidth, int16_t maxheight, int16_t snap, int16_t lag );
 
Binding:
 
int16_t x_graf_rubberbox(GRECT *area, GRECT *outer, int16_t
minwidth, int16_t minheight, int16_t maxwidth, int16_t
maxheight, int16_t snap, int16_t lag )
{
   int_in[0] = minwidth;
   int_in[1] = minheight;
   int_in[2] = maxwidth;
   int_in[3] = maxheight;
   int_in[4] = snap;
   int_in[5] = lag;

   addr_in[0] = area;
   addr_in[1] = outer;

   crys_if(28977);

   return ( int_out[0] );
}
GEM-Arrays:
 

Address Element Contents
control control[0] 28977 # Function opcode
control+2 control[1] 6 # Entry in int_in
control+4 control[2] 1 # Entry in int_out
control+6 control[3] 2 # Entry in addr_in
control+8 control[4] 0 # Entry in addr_out
int_in int_in[0] minwidth
int_in+2 int_in[1] minheight
int_in+4 int_in[2] maxwidth
int_in+6 int_in[3] maxheight
int_in+8 int_in[4] snap
int_in+10 int_in[5] lag
addr_in addr_in[0] area
addr_in+4 addr_in[1] outer
int_out int_out[0] Return value

Home AESAES Geneva libraryGeneva library Scrap libraryScrap library