A Beginner's Guide to Amiga E - Intuition support functions

Go to the Next or Previous section, the Detailed Contents, or the Amiga E Encyclopedia.

11.3.2 Intuition support functions

The functions in this section are simplified versions of Amiga system functions (in the Intuition library, as the title suggests). To make best use of them you are probably going to need something like the Rom Kernel Reference Manual (Libraries), especially if you want to understand the Amiga specific things like IDCMP and raster ports.

The descriptions given here vary slightly in style from the previous descriptions. All function parameters can be expressions which represent numbers or addresses, as appropriate. Because many of the functions take several parameters they have been named (fairly descriptively) so they can be more easily referenced.

OpenW(x,y,wid,hgt,idcmp,wflgs,title,scrn,sflgs,gads,tags=NIL)

Opens and returns a pointer to a window with the supplied properties. If for some reason the window could not be opened NIL is returned.

x, y: The position on the screen where the window will appear.
wid, hgt: The width and height of the window.
idcmp, wflgs: The IDCMP and window specific flags.
title: The window title (a string) which appears on the title bar of the window.
scrn, sflgs: The screen on which the window should open. If sflgs is 1 the window will be opened on Workbench, and scrn is ignored (so it can be NIL). If sflgs is $F (i.e., 15) the window will open on the custom screen pointed to by scrn (which must then be valid). See OpenS to see how to open a custom screen and get a screen pointer.
gads: A pointer to a gadget list, or NIL if you don't want any gadgets. These are not the standard window gadgets, since they are specified using the window flags. A gadget list can be created using the Gadget function.
tags: A tag-list of other options available under Kickstart version 37 or greater. This can normally be omitted since it defaults to NIL. See the Rom Kernel Reference Manual (Libraries) for details about the available tags and their meanings.

There's not enough space to describe all the fine details about windows and IDCMP (see the Rom Kernel Reference Manual (Libraries) for complete details), but a brief description in terms of flags might be useful. Here's a small table of common IDCMP flags:

IDCMP Flag           Value
--------------------------
IDCMP_NEWSIZE           $2
IDCMP_REFRESHWINDOW     $4
IDCMP_MOUSEBUTTONS      $8
IDCMP_MOUSEMOVE        $10
IDCMP_GADGETDOWN       $20
IDCMP_GADGETUP         $40
IDCMP_MENUPICK        $100
IDCMP_CLOSEWINDOW     $200
IDCMP_RAWKEY          $400
IDCMP_DISKINSERTED   $8000
IDCMP_DISKREMOVED   $10000

Here's a table of useful window flags:

Window Flag          Value
--------------------------
WFLG_SIZEGADGET         $1
WFLG_DRAGBAR            $2
WFLG_DEPTHGADGET        $4
WFLG_CLOSEGADGET        $8
WFLG_SIZEBRIGHT        $10
WFLG_SIZEBBOTTOM       $20
WFLG_SMART_REFRESH       0
WFLG_SIMPLE_REFRESH    $40
WFLG_SUPER_BITMAP      $80
WFLG_BACKDROP         $100
WFLG_REPORTMOUSE      $200
WFLG_GIMMEZEROZERO    $400
WFLG_BORDERLESS       $800
WFLG_ACTIVATE        $1000

All these flags are defined in the module `intuition/intuition', so if you use that module you can use the constants rather than having to write the less descriptive value (see 12 Modules). Of course, you can always define your own constants for the values that you use.

You use the flags by OR-ing the ones you want together, in a similar way to using sets (see 8.5 Sets). However, you should supply only IDCMP flags as part of the idcmp parameter, and you should supply only window flags as part of the wflgs parameter. So, to get IDCMP messages when a disk is inserted and when the close gadget is clicked you specify both of the flags IDCMP_DISKINSERTED and IDCMP_CLOSEWINDOW for the idcmp parameter, either by OR-ing the constants or (less readably) by using the calculated value $8200.

Some of the window flags require some of IDCMP flags to be used as well, if an effect is to be complete. For example, if you want your window to have a close gadget (a standard window gadget) you need to use WFLG_CLOSEGADGET as one of the window flags. If you want that gadget to be useful then you need to get an IDCMP message when the gadget is clicked. You therefore need to use IDCMP_CLOSEWINDOW as one of the IDCMP flags. So the full effect requires both a window and an IDCMP flag (a gadget is pretty useless if you can't tell when it's been clicked). The worked example in Part Three illustrates how to use these flags in this way (see 22.1 Gadgets).

If you only want to output text to a window (and maybe do some input from a window), it may be better to use a console window. These provide a text based input and output window, and are opened using the Dos library function Open with the appropriate `CON:' file name. See the AmigaDOS Manual for more details about console windows.

CloseW(winptr)

Closes the window which is pointed to by winptr. It's safe to give NIL for winptr, but in this case, of course, no window will be closed! The window pointer is usually a pointer returned by a matching call to OpenW. You must remember to close any windows you may have opened before terminating your program.

OpenS(wid,hgt,depth,scrnres,title,tags=NIL)

Opens and returns a pointer to a custom screen with the supplied properties. If for some reason the screen could not be opened NIL is returned.

wid, hgt: The width and height of the screen.
depth: The depth of the screen, i.e., the number of bit-planes. This can be a number in the range 1-8 for AGA machines, or 1-6 for pre-AGA machines. A screen with depth 3 will be able to show 2 to the power 3 (i.e., 8) different colours, since it will have 2 to the power 3 different pens (or colour registers) available. You can set the colours of pens using the SetColour function.
scrnres: The screen resolution flags.
title: The screen title (a string) which appears on the title bar of the screen.
tags: A tag-list of other options available under Kickstart version 37 or greater. See the Rom Kernel Reference Manual (Libraries) for more details.

The screen resolution flags control the screen mode. The following (common) values are taken from the module `graphics/view' (see 12 Modules). You can, if you want, define your own constants for the values that you use. Either way it's best to use descriptive constants rather than directly using the values.

Mode Flag          Value
------------------------
V_LACE                $4
V_SUPERHIRES         $20
V_PFBA               $40
V_EXTRA_HALFBRITE    $80
V_DUALPF            $400
V_HAM               $800
V_HIRES            $8000

So, to get a hires, interlaced screen you specify both of the flags V_HIRES and V_LACE, either by OR-ing the constants or (less readably) by using calculated value $8004. There is a worked example using this function in Part Three (see 22.4 Screens).

CloseS(scrnptr)

Closes the screen which is pointed to by scrnptr. It's safe to give NIL for scrnptr, but in this case, of course, no screen will be closed! The screen pointer is usually a pointer returned by a matching call to OpenS. You must remember to close any screens you may have opened before terminating your program. Also, you must close all windows that you opened on your screen before you can close the screen.

Gadget(buf,glist,id,flags,x,y,width,text)

Creates a new gadget with the supplied properties and returns a pointer to the next position in the (memory) buffer that can be used for a gadget.

buf: This is the memory buffer, i.e., a chunk of allocated memory. The best way of allocating this memory is to declare an array of size n*GADGETSIZE, where n is the number of gadgets which are going to be created. The first call to Gadget will use the array as the buffer, and subsequent calls use the result of the previous call as the buffer (since this function returns the next free position in the buffer).
glist: This is a pointer to the gadget list that is being created, i.e., the array used as the buffer. When you create the first gadget in the list using an array a, this parameter should be NIL. For all other gadgets in the list this parameter should be the array a.
id: A number which identifies the gadget. It is best to give a unique number for each gadget; that way you can easily identify them. This number is the only way you can identify which gadget has been clicked.
flags: The type of gadget to be created. Zero represents a normal gadget, one a boolean gadget (a toggle) and three a boolean that starts selected.
x, y: The position of the gadget, relative to the top, left-hand corner of the window.
width: The width of the gadget (in pixels, not characters).
text: The text (a string) which will centred in the gadget, so the width must be big enough to hold this text.

Once a gadget list has been created by possibly several calls to this function the list can be passed as the gads parameter to OpenW. There is a worked example using this function in Part Three (see 22.1 Gadgets).

Mouse()

Returns the state of the mouse buttons (including the middle mouse button if you have a three-button mouse). This is a set of flags, and the individual flag values are:

Button Pressed   Value
----------------------
Left              %001
Right             %010
Middle            %100

So, if this function returns %001 you know the left button is being pressed, and if it returns %110 you know the middle and right buttons are both being pressed.

This mouse function is not strictly the proper way to do things. It is suggested you use this function only for small tests or demo-like programs. LeftMouse and WaitLeftMouse can be used to do things in a friendly way, but are restricted to seeing when the left mouse button is pressed. More generally, the proper way of getting mouse details is to use the appropriate IDCMP flags for your window, wait for events (using WaitIMessage, for example) and decode the received information.

MouseX(winptr)

Returns the x coordinate of the mouse pointer, relative to the window pointed to by winptr.

As above, this mouse function is not strictly the proper way to do things.

MouseY(winptr)

Returns the y coordinate of the mouse pointer, relative to the window pointed to by winptr.

As above, this mouse function is not strictly the proper way to do things.

LeftMouse(winptr)

Returns TRUE if left mouse button has been clicked in the window pointed to by winptr, and FALSE otherwise. In order for this to work sensibly the window must have the IDCMP flag IDCMP_MOUSEBUTTONS set (see above).

This function does things in a proper, Intuition-friendly manner and so is a good alternative to the Mouse function.

WaitIMessage(winptr)

This function waits for a message from Intuition for the window pointed to by winptr and returns the class of the message (which is an IDCMP flag). If you did not specify any IDCMP flags when the window was opened, or the specified messages could never happen (e.g., you asked only for gadget messages and you have no gadgets), then this function may wait forever. When you've got a message you can use the MsgXXX functions to get some more information about the message. See the Rom Kernel Reference Manual (Libraries) for more details on Intuition and IDCMP. There is a worked example using this function in Part Three (see 22.2 IDCMP Messages).

This function is basically equivalent to the following function, except that the MsgXXX functions can also access the message data held in the variables code, qual and iaddr.

PROC waitimessage(win:PTR TO window)
  DEF port,msg:PTR TO intuimessage,class,code,qual,iaddr
  port:=win.userport
  IF (msg:=GetMsg(port))=NIL
    REPEAT
      WaitPort(port)
    UNTIL (msg:=GetMsg(port))<>NIL
  ENDIF
  class:=msg.class
  code:=msg.code
  qual:=msg.qualifier
  iaddr:=msg.iaddress
  ReplyMsg(msg)
ENDPROC class

MsgCode()

Returns the code part of the message returned by WaitIMessage.

MsgIaddr()

Returns the iaddr part of the message returned by WaitIMessage. There is a worked example using this function in Part Three (see 22.2 IDCMP Messages).

MsgQualifier()

Returns the qual part of the message returned by WaitIMessage.

WaitLeftMouse(winptr)

This function waits for the left mouse button to be clicked in the window pointed to by winptr. It is advisable to have the IDCMP flag IDCMP_MOUSEBUTTONS set for the window (see above).

This function does things in a proper, Intuition-friendly manner and so is a good alternative to the Mouse function.

Go to the Next or Previous section, the Detailed Contents, or the Amiga E Encyclopedia.