@database intuition.guide
@$VER: Intuition.guide 41.22 (1 May 1998)

----------------------------------------------------------------------
Wait a minute!  You're not using AmigaGuide!

This is an AmigaGuide document.  In order to read it correctly, you'll
need a program that can display such documents.  Workbench 3.0 users
can use MultiView to read this.  Other users should find a copy of
AmigaGuide; disc 870 of the Fred Fish library has it.
----------------------------------------------------------------------

@node main "The AMOS Intuition Extension - Version 1.3b"

                          Intuition Extension
                          ===================

                              Version 1.3b


	@{" About            " link About} - So what is this thing, anyway?
	@{" History          " link History} - History of the Intuition Extension
	@{" Requirements     " link Requirements} - What it needs in order to run
	@{" Installation     " link Installation} - How to tell AMOS you've got it
	@{" Notes            " link Notes} - Important things to know. Read them first!
	@{" Bug reporting    " link BugReporting} - What?  A bug in the Intuition Extension?
	@{" Misc. stuff      " link Misc} - Copyrights and acknowledgements
	@{" The future       " link Future} - What to look for in future versions
	@{" Author           " link Me} - How to reach me, the author

        Commands in the Intuition Extension:

	@{" Display Info     " link DispInfo} - Information about the hardware and display
	@{" Screens          " link Screens} - Opening, closing, and manipulating screens
	@{" Windows          " link Windows} - Playing around with windows
	@{" Input/Output     " link IO} - Listening to the user and talking back
	@{" Fonts            " link Fonts} - Making your responses look nice
	@{" Requesters       " link Requesters} - For special kinds of input
	@{" Menus            " link Menus} - How to give the user control
	@{" Gadgets          " link Gadgets} - How to give the user more control
	@{" Other functions  " link Other} - Functions not in the above categories

	@{" Command Index    " link Index} - Alphabetical list of commands
	@{" Errors           " link Errors} - Error messages and what they mean


	@{" IntuiViewer      " link IntuiViewer.guide/main} - an Intuition-compatible picture viewer

@endnode

@node About "What is the Intuition Extension?"
@next History

Although AMOS is an excellent language, with hundreds of commands for
graphics, sound, I/O, and much more, it has had, until now, one
serious lack: support for Intuition, the Amiga's native graphics
system.  The Intuition Extension fills this gap.

The Intuition Extension was designed as an interface between AMOS and
Intuition.  Most of the commands included, therefore, function almost
identically to AMOS commands.  For most instructions, you can simply
add an "I" in front of the instruction to make it work with Intuition
rather than the AMOS graphics system.  However, additional Intuition-
specific instructions have been included, so that AMOS programmers can
take full advantage of the Intuition graphical interface.

@endnode

@node History "Intuition Extension - Version History"
@next Requirements
@prev About

----------------------------------------------------------------------
Version 1.3b (revision 41.95, documentation 41.22) - 1 May 1998

Source code released into the public domain.

----------------------------------------------------------------------
Version 1.3b (revision 41.95, documentation 41.21) - 22 February 1996

Added screen and window title manipulation commands.
Added Workbench window variants for most window commands.
Added Iscreen Open Front/Back to allow "hiding" of new screens.
Implemented I Flush command to deal with several potential temporary
    memory leaks.
Fixed problems with gadget and window border colors.
Fixed some stupid errors in the docs.  For those who wondered what
    "Kickstart 1.3a" was, it was "Kickstart 1.3" mutilated by a
    global search-and-replace.  Oops.
Added Iscreen Amos Copy, companion command to Amos Iscreen Copy.
Fixed a bug which corrupted the current window pointer when switching
    from a Workbench window to a non-workbench window and caused
    crashes.
Various other bug fixes.


----------------------------------------------------------------------
Version 1.3a (revision 41.65) - 8 April 1995

Added Ipoint function.
Extension will now print error messages if it fails to start up
    properly.
Minor (but important) bug fixes.


----------------------------------------------------------------------
Version 1.3 (revision 41.55) - 23 March 1995

Added two sorely needed sets of functions: flags for controlling the
    opening of windows (Iwindow Open and Iwindow Open Wb), and OS-
    compliant event-waiting (Iwait Event and associated functions).
    No more busy-waiting loops!
Fixed bug resulting from using Igadget On on a gadget that was already
    displayed, or Igadget Off on a gadget that was not displayed.
Fixed screen handling under Kickstart 2.0 and above.  Windows will now
    look "right" on 4-or-more-color screens.
Rearranged the extension code to avoid a bug in AMOS's extension
    handling.
Fixed various minor bugs.


----------------------------------------------------------------------
Version 1.2b (revision 40.312) - 25 September 1994

Added hit-select gadget (Set Igadget Hit).
Gadget border pens can now be selected within a program.
"Down" status of gadget (whether gadget is currently selected) can be
    accessed through the Igadget Down function.
Added Iwindow Activate Wb (Workbench counterpart to Iwindow Activate).
Created a branch table allowing other extensions to access Intuition
    Extension data.
Added Iget Icon command.
Fixed some stupid bugs in the Iwindow Width/Height routines.
Added Iwindow Actual Width/Height to return usable area of a window.
Fixed problem with reading vertical sliders (Igadget Read always
    returned zero).
Added Set Igadget Value to allow a gadget's value to be changed
    without having to redefine and redraw the gadget.


----------------------------------------------------------------------
Version 1.2a (revision 40.259) - 29 August 1994

Fixed MAJOR bug caused by an assembler upgrade.
HAM8 screens can now be opened correctly.
Auto-height for string and integer gadgets fixed.


----------------------------------------------------------------------
Version 1.2 (revision 40.253) - 14 August 1994

Added gadget support.
Added Icentre command.
Added Amos Iscreen Copy command.


----------------------------------------------------------------------
Version 1.1b (revision 40.225) - 23 July 1994

ReqTools.library is now optional, not required.  (Requester functions
    still require it, though.)
Added a missing memory deallocation bit.
Added function "=Reqtools Here" to check for presence of ReqTools.


----------------------------------------------------------------------
Version 1.1a (revision 40.222) - 3 July 1994

Added subcode field to "Internal error" error string.
Fixed Iscreen Display bug which did not set the display width and
    height correctly.


----------------------------------------------------------------------
Version 1.1 (revision 40.217) - 23 June 1994

Basic menu support added.
Extension number changed to 14 (from 20).
New instructions:
    Ipaste Icon
    Iget Sprite Palette
    Iget Icon Palette
Fixed a nasty bug in Iscreen Close which resulted in system crashes.
Fixed bugs in the input routines that would sometimes crash on input
    buffer overflow.


----------------------------------------------------------------------
Version 1.0a (revision 40.152) - 18 May 1994

Argh.  Just after releasing the first version, I discovered left-out
    version numbers and text.
Message requesters (Irequest Message/Warning/Error) now recognise a
    title when it is given to them.


----------------------------------------------------------------------
Version 1.0 (revision 40.151) - 15 May 1994

First public release.

@endnode

@node Requirements "What does the Intuition Extension need to run?"
@next Installation
@prev History

To use the Intuition Extension, you need:

- An Amiga (of course!)
- AMOS Creator version 1.3 or higher, or AMOS Professional.  However,
    the Intuition Extension will NOT work under AMOS Pro version 1.12.
- Kickstart/Workbench version 1.3 or higher.  Lower versions may work,
    but have not been tested.  Under Kickstart 1.3, some features of
    the extension will be unusable.

Also strongly recommended:

- ReqTools.library version 2 (revision 38.xxx) or higher.

@endnode

@node Installation "How to install the Intuition Extension"
@next Notes
@prev Requirements

Included in this distribution are two versions of the Intuition
Extension, one for AMOS Creator and the other for AMOS Professional.
They are in the directories "AMOS_System" and "APSystem", respectively.

To install the extension, copy the appropriate "Intuition.Lib" file
into your AMOS_System or APSystem folder.  Then run AMOS, run the
configuration program, and enter "Intuition.Lib" in extension slot
number 14.  Exit and reload AMOS to access the new Intuition Extension
commands.

@endnode

@node Notes "Notes on the Intuition Extension"
@prev Installation
@next BugReporting

The Intuition Extension does not function when installed in AMOS Pro
version 1.12.  The cause of this is currently unknown, but is believed
to be a bug in that version of AMOS.  If you do have that version, I
strongly urge you to upgrade to version 2.0, which includes a compiler,
more commands, and bug fixes - and the Intuition Extension will work
with it. :-)


A note for those who are upgrading from earlier versions:

If you are upgrading from version 1.0a (revision 40.152) or earlier,
you will need to convert any programs that use Intuition Extension
instructions so that they will work correctly with the new version.
With the old version of the extension still installed, do this for
each program:

	- Open/Unfold all procedures.
	- Select the entire text as a block.
	- (AMOS Pro only) Store the block in memory.
	- Save the block as an ASCII file.

Then change to the new version of the extension, and do a "Merge ASCII"
for each ASCII file.

If you are upgrading from version 1.2b (revision 40.312) or earlier,
you may notice an underscore ("_") in a few command names.  That
indicates that a program was written using an old version of the
extension.  The commands will function exactly as expected, but unless
you remove the underscore, you will not be able to use any new features
of the command.

As of version 1.3b, the changed commands include Iscreen Open and many
of the window commands.

Although virtually all of the instructions in the Intuition Extension
will function identically in both AMOS Creator and AMOS Pro, there are
a couple of exceptions:

	- In Creator, the @{" X Hard Min " link C_XHardMin} and @{" Y Hard Min " link C_YHardMin} functions are
	  called "Xhard Min" and "Yhard Min", since Creator tokenises
	  X Hard before X Hard Min.  However, this does not affect the
	  program itself; a program written in either environment
	  using these functions will work in the other environment as
	  well.

	- For a similar reason, the functions @{" Ifont$ " link C_IfontName}, @{" Ifont Base " link C_IfontBase},
	  and @{" Ifont Height " link C_IfontHeight} had to be renamed in the Creator version
	  to Fonti$, Fonti Base, and Fonti Height to avoid problems
	  with the If statement.  This also does not affect the
	  program itself, but is merely a cosmetic difference.

I know this may (and probably will) cause a bit of confusion for
Creator users, but I'm developing this mainly as a Pro extension,
since that's what I use almost exclusively.  I knew from the start
that many people owned Creator and would want to use the extension, so
I decided to make a Creator port of it as well.

Other things to note:

	- Several commands can accept a coordinate range (X1,Y1 To
	  X2,Y2).  In AMOS, some instructions will interpret this to
	  mean that the bottom right corner is (X2,Y2), while others
	  will think that the corner is (X2-1,Y2-1).  In the Intuition
	  Extension, the first interpretation is always used; in other
	  words, when you give X2 and Y2, those are the actual
	  coordinates of the bottom right corner.  (I've often
	  wondered why some AMOS instructions use the other behaviour;
	  it doesn't make much sense.)

	- On a related note, ranges must ALWAYS be specified with the
	  upper left corner first, followed by the lower right corner.
	  Failure to follow this standard will result in a "Backward
	  coordinates" error.

	- The Default instruction closes all screens and windows that
	  are open at the time.  However, it does not reset any
	  requester buffers, so loaded directories and fonts remain
	  in memory (see @{" Requesters " link Requesters}).

	- Any input from ANY window opened by an AMOS program gets to
	  AMOS.  If your program uses multiple windows (remember that
	  the screens are windows too!) then it is the program's job
	  to determine which window is the active one and act
	  accordingly.

	- If an error occurs while using an Intuition instruction,
	  and you began your program with an Amos To Back instruction
	  (which you probably should have), the program will appear to
	  freeze in its tracks.  When this happens, press LeftAmiga+"A"
	  to see if there's an AMOS error message.  This is,
	  unfortunately, another limitation of AMOS extensions.

	- Screens and windows must be closed before they can be
	  reopened.

	- The Pro Compiler will not compile any Ipalette statements
	  that have more than nine parameters, due to an apparent bug
	  in the compiler.  Use For/Next, Read/Data and Set Icolour
	  instead.

	- The Close Editor instruction seems to interact badly with the
	  extension, sometimes causing the computer to crash.  Don't
	  use it if at all possible.

@endnode

@node BugReporting "Reporting bugs in the Intuition Extension"
@next Misc
@prev Notes

Although I have done my best to eliminate all the bugs I can from the
Intuition Extension, an error or two may have slipped past my notice.
If you happen to find one, please tell me as soon as possible.

However, in order to fix the problem, I'll probably have to have a
program that demonstrates it.  So, before you tell me about it, write
a simple program that causes the bug to happen.  Then, send it to me,
along with a description of the bug, one of the following ways:

- Through Internet e-mail - I prefer this method, since I can receive
  and act on the report much more quickly.  If you have Internet
  access, send me a uuencoded LhA'd copy of the program and bug
  description.

- Through normal mail - If you don't have Internet access, then type
  (or write) a description of the problem and the sample program that
  causes it, and send it to me.

If your problem involves AMOS being unable to start up, run it from a
shell window and include in your description the output produced.

There may be some cases where you encounter a bug only occasionally,
and you can't always reproduce it.  If that's the case, send me a
description anyway, and I'll try to solve it, but there's no guarantee
I'll be able to.  Also, try running without a Startup-Sequence or from
an unmodified Workbench startup disc, and see if that eliminates the
problem; if it does, then the problem is most likely in your Amiga's
setup.

@endnode

@node Misc "Copyrights and acknowledgements"
@next Future
@prev BugReporting

The Intuition Extension was originally created by Andrew Church.  It is
public domain software, and may be redistributed freely, provided that
no charge is assessed beyond the cost of media or duplication for such
distribution.

AMOS the Creator and AMOS Professional are copyright © François Lionet.

reqtools.library is copyright © Nico François.

@endnode

@node Future "The future of the Intuition Extension"
@next Me
@prev Misc

The future of the Intuition Extension will be up to those who choose to
continue its development as public-domain software.  I simply don't
have the time to work on it anymore.

  --Andy Church

@endnode

@node Me "The author of the Intuition Extension"
@prev Future

The Intuition Extension was developed by Andrew Church
<achurch@dragonfire.net> through 22 February 1996.  As of 1 May 1998
it was placed in the public domain.

@endnode

@node DispInfo "Intuition Extension 1.3b - Display Information Commands"
@next Screens

These instructions return information about the custom chips in the
computer, the hardware coordinates of the display, and some screen
mode constants.

	@{"=Aga        " link C_Aga}
	@{"=Ecs        " link C_Ecs}
	@{"=Ehb        " link C_Ehb}
	@{"=Ham        " link C_Ham}
	@{"=Superhires " link C_Superhires}
	@{"=X Hard Min " link C_XHardMin}
	@{"=Y Hard Min " link C_YHardMin}

@endnode

@node Screens "Intuition Extension 1.3b - Screen Commands"
@next Windows
@prev DispInfo

These instructions control opening, closing, positioning, and general
manipulation of Intuition screens, and return information about them.

	@{" Iscreen Open         " link C_IscreenOpen}
	@{" Iscreen Open Public  " link C_IscrOpenPublic}
	@{" Iscreen Open Front   " link C_IscrOpenFront}
	@{" Iscreen Open Back    " link C_IscrOpenBack}
	@{" Iscreen Close        " link C_IscreenClose}
	@{" Set Iscreen          " link C_SetIscreen}
	@{"=Iscreen              " link C_GetIscreen}

	@{" Iscreen Display      " link C_IscreenDisplay}
	@{" Iscreen Offset       " link C_IscreenOffset}
	@{" Iscreen To Back      " link C_IscreenToBack}
	@{" Iscreen To Front     " link C_IscreenToFront}
	@{" Set Iscreen Title    " link C_SetIscreenTitle}
	@{"=Iscreen Width        " link C_IscreenWidth}
	@{"=Iscreen Height       " link C_IscreenHeight}
	@{"=Iscreen Title Height " link C_IscreenTitleHeight}
	@{"=Iscreen Colour       " link C_IscreenColour}
	@{"=Iscreen Mode         " link C_IscreenMode}
	@{"=Iscreen Base         " link C_IscreenBase}

	@{" Set Icolour          " link C_SetIcolour}
	@{"=Icolour              " link C_GetIcolour}
	@{" Ipalette             " link C_Ipalette}
	@{" Iget Sprite Palette  " link C_IgetSprPal}
	@{" Iget Icon Palette    " link C_IgetIconPal}
	@{" Icls                 " link C_Icls}
	@{" Iscreen Copy         " link C_IscreenCopy}
	@{" Amos Iscreen Copy    " link C_AIscrCopy}
	@{" Iscreen Amos Copy    " link C_AIscrCopy}
	@{"=X Ihard              " link C_XIhard}
	@{"=Y Ihard              " link C_YIhard}
	@{"=X Iscreen            " link C_XIscreen}
	@{"=Y Iscreen            " link C_YIscreen}

@endnode

@node Windows "Intuition Extension 1.3b - Window Commands"
@next IO
@prev Screens

These instructions handle opening, closing, and manipulation of
windows.  Note that each screen's windows are completely separate, so
you need to select the right screen before you start doing anything.
(Workbench windows are an exception to this rule.)

	@{" Iwindow Open          " link C_IwindowOpen}
	@{" Iwindow Open Wb       " link C_IwindowOpenWB}
	@{" Iwindow Close         " link C_IwindowClose}
	@{" Iwindow Close Wb      " link C_IwindowCloseWB}
	@{"=Iwindow               " link C_GetIwindow}
	@{" Set Iwindow           " link C_SetIwindow}
	@{" Set Iwindow Wb        " link C_SetIwindowWB}
	@{"=Iwindow On Wb         " link C_IwindowOnWB}

	@{" Iwindow To Front      " link C_IwindowToFront}
	@{" Iwindow To Back       " link C_IwindowToBack}
	@{" Iwindow Move          " link C_IwindowMove}
	@{" Iwindow Size          " link C_IwindowSize}
	@{" Set Iwindow Title     " link C_SetIwindowTitle}
	@{"=Iwindow X             " link C_IwindowX}
	@{"=Iwindow Y             " link C_IwindowY}
	@{"=Iwindow Width         " link C_IwindowWidth}
	@{"=Iwindow Height        " link C_IwindowHeight}
	@{"=Iwindow Actual Width  " link C_IwindowActual}
	@{"=Iwindow Actual Height " link C_IwindowActual}
	@{"=Iwindow Base          " link C_IwindowBase}
	@{"=Iwindow Status        " link C_IwindowStatus}

	@{" Iwindow Activate      " link C_IwindowActivate}
	@{"=Iwindow Active        " link C_IwindowActive}
	@{"=Iwindow Active Num    " link C_IwindowActiveNum}
	@{"=Iwindow Active Base   " link C_IwindowActiveBase}

	@{" Iclw                  " link C_Iclw}

@endnode

@node IO "Intuition Extension 1.3b - Input/Output Commands"
@next Fonts
@prev Screens

These instructions allow you to get information from the user and give
information back to him, both textually and graphically.

Input:
	@{"=Imouse X    " link C_ImouseX}
	@{"=Imouse Y    " link C_ImouseY}
	@{"=Imouse Key  " link C_ImouseKey}
	@{"=Iget$       " link C_Iget}
	@{"=Iread Char$ " link C_IreadChar}
	@{"=Iread Str$  " link C_IreadStr}
	@{"=Iread Int   " link C_IreadInt}
	@{"=Iscan       " link C_Iscan}
	@{"=Ishift      " link C_Ishift}

Waiting for input:
	@{" Iwait Mouse " link C_IwaitMouse}
	@{" Iwait Key   " link C_IwaitKey}
	@{"=Iwait Event " link C_IwaitEvent}
	@{"=Ievent Data " link C_IeventData}
	@{"=Ievent      " link C_IeventType}
	@{" Iclear      " link C_Iclear}

Output:
	@{" Ilocate     " link C_Ilocate}
	@{" Ilocate Gr  " link C_IlocateGr}
	@{"=Ixgr        " link C_Ixgr}
	@{"=Iygr        " link C_Iygr}
	@{" Iink        " link C_Iink}
	@{" Igr Writing " link C_IgrWriting}
	@{" Itext       " link C_Itext}
	@{" Icentre     " link C_Icentre}
	@{" Iwrite      " link C_Iwrite}
	@{" Iplot       " link C_Iplot}
	@{" Idraw       " link C_Idraw}
	@{" Ibox        " link C_Ibox}
	@{" Ibar        " link C_Ibar}
	@{" Icircle     " link C_Icircle}
	@{" Iellipse    " link C_Iellipse}
	@{" Set Ipens   " link C_SetIpens}

	@{" Iget Icon   " link C_IgetIcon}
	@{" Ipaste Icon " link C_IpasteIcon}

@endnode

@node Fonts "Intuition Extension 1.3b - Font Commands"
@next Requesters
@prev IO

These instructions select a font to be used and return information
about it.

	@{" Set Ifont    " link C_SetIfont}
	@{"=Ifont$       " link C_IfontName}
	@{"=Ifont Height " link C_IfontHeight}
	@{"=Itext Base   " link C_ItextBase}
	@{"=Itext Length " link C_ItextLength}
	@{"=Ifont Base   " link C_IfontBase}

@endnode

@node Requesters "Intuition Extension 1.3b - Requester Commands"
@next Menus
@prev Fonts

These instructions ask the user for a specific kind of input and
return it.

	@{" Irequest Def Title   " link C_IreqDefTitle}
	@{"=Irequest File$       " link C_IrequestFile}
	@{"=Irequest File Multi$ " link C_IreqFileMulti}
	@{"=Irequest File Next$  " link C_IreqFileNext}
	@{"=Irequest Font$       " link C_IrequestFont}
	@{"=Irequest Screen      " link C_IrequestScreen}	(Kickstart 2.0 only)
	@{"=Ireq Scr Colour      " link C_IreqScrCols}	(Kickstart 2.0 only)
	@{"=Ireq Scr Height      " link C_IreqScrHeight}	(Kickstart 2.0 only)
	@{"=Ireq Scr Mode        " link C_IreqScrMode}	(Kickstart 2.0 only)
	@{"=Ireq Scr Width       " link C_IreqScrWidth}	(Kickstart 2.0 only)

	@{" Irequest Error       " link C_IrequestError}
	@{"=Irequest Warning     " link C_IrequestWarning}
	@{"=Irequest Message     " link C_IrequestMessage}

As of version 1.2b, ReqTools.library is no longer required.  However,
if you try to use any of the above instructions and ReqTools is not
installed, an error will be generated.  To check whether the library
is present in the system, use this function:

	@{"=Reqtools Here        " link C_ReqtoolsHere}

@endnode

@node Menus "Intuition Extension 1.3b - Menu Commands"
@next Gadgets
@prev Requesters

These instructions control the creation of menus, and let you find out
which menu item the user has selected.

	@{" Set Imenu " link C_SetImenu}
	@{"=Ichoice   " link C_Ichoice}
	@{" Imenu On  " link C_ImenuOnOff}
	@{" Imenu Off " link C_ImenuOnOff}

@endnode

@node Gadgets "Intuition Extension 1.3b - Gadget Commands"
@next Other
@prev Menus

These instructions allow you to create, display, and respond to
gadgets of various types.

	@{" Reserve Igadget     " link C_ReserveIgadget}
	@{" Set Igadget Toggle  " link C_SetIgadToggle}
	@{" Set Igadget Hit     " link C_SetIgadHit}
	@{" Set Igadget Hslider " link C_SetIgadSlider}
	@{" Set Igadget Vslider " link C_SetIgadSlider}
	@{" Set Igadget String  " link C_SetIgadString}
	@{" Set Igadget Int     " link C_SetIgadInt}

	@{" Igadget On          " link C_IgadgetOn}
	@{" Igadget Off         " link C_IgadgetOff}
	@{" Igadget Active      " link C_IgadgetActive}
	@{" Igadget Inactive    " link C_IgadgetInactive}
	@{"=Igadget Read        " link C_IgadgetRead}
	@{"=Igadget Down        " link C_IgadgetDown}

	@{" Set Igadget Value   " link C_SetIgadValue}
	@{" Set Igadget Value$  " link C_SetIgadValue}

@endnode

@node Other "Intuition Extension 1.3b - Other Commands"
@prev Gadgets

These instructions don't fit into any of the other categories, so they
go here.

	@{" Iwait     " link C_Iwait}
	@{" Iwait Vbl " link C_IwaitVbl}

	@{"=Ierr      " link C_Ierr}
	@{"=Ierr$     " link C_IerrStr}
	@{" Ierror    " link C_Ierror}
	@{" Itrap On  " link C_Itrap}
	@{" Itrap Off " link C_Itrap}
	@{"=Ierrtrap  " link C_IerrTrap}

	@{" I Flush   " link C_IFlush}

@endnode

@node Index "Intuition Extension 1.3b - Command Index"
@next Errors

	@{"=Aga                   " link C_Aga}
	@{" Amos Iscreen Copy     " link C_AIscrCopy}

	@{"=Ecs                   " link C_Ecs}
	@{"=Ehb                   " link C_Ehb}

	@{"=Ham                   " link C_Ham}

	@{" I Flush               " link C_IFlush}
	@{" Ibar                  " link C_Ibar}
	@{" Ibox                  " link C_Ibox}
	@{" Icentre               " link C_Icentre}
	@{"=Ichoice               " link C_Ichoice}
	@{" Icircle               " link C_Icircle}
	@{" Iclear All            " link C_Iclear}
	@{" Iclear Key            " link C_Iclear}
	@{" Iclear Menu           " link C_Iclear}
	@{" Iclear Mouse          " link C_Iclear}
	@{" Icls                  " link C_Icls}
	@{" Iclw                  " link C_Iclw}
	@{"=Icolour               " link C_GetIcolour}
	@{" Idraw                 " link C_Idraw}
	@{" Iellipse              " link C_Iellipse}
	@{"=Ierr                  " link C_Ierr}
	@{"=Ierr$                 " link C_IerrStr}
	@{" Ierror                " link C_Ierror}
	@{"=Ierrtrap              " link C_IerrTrap}
	@{"=Ievent                " link C_IeventType}
	@{"=Ievent Data           " link C_IeventData}
	@{"=Ifont Base            " link C_IfontBase}
	@{"=Ifont Height          " link C_IfontHeight}
	@{"=Ifont$                " link C_IfontName}
	@{" Igadget Active        " link C_IgadgetActive}
	@{"=Igadget Down          " link C_IgadgetDown}
	@{" Igadget Inactive      " link C_IgadgetInactive}
	@{" Igadget Off           " link C_IgadgetOff}
	@{" Igadget On            " link C_IgadgetOn}
	@{"=Igadget Read          " link C_IgadgetRead}
	@{" Iget Icon             " link C_IgetIcon}
	@{" Iget Icon Palette     " link C_IgetIconPal}
	@{" Iget Sprite Palette   " link C_IgetSprPal}
	@{"=Iget$                 " link C_Iget}
	@{" Igr Writing           " link C_IgrWriting}
	@{" Iink                  " link C_Iink}
	@{" Ilocate               " link C_Ilocate}
	@{" Ilocate Gr            " link C_IlocateGr}
	@{" Imenu Off             " link C_ImenuOnOff}
	@{" Imenu On              " link C_ImenuOnOff}
	@{"=Imouse Key            " link C_ImouseKey}
	@{"=Imouse X              " link C_ImouseX}
	@{"=Imouse Y              " link C_ImouseY}
	@{" Ipalette              " link C_Ipalette}
	@{" Ipaste Icon           " link C_IpasteIcon}
	@{" Iplot                 " link C_Iplot}
	@{"=Iread Char$           " link C_IreadChar}
	@{"=Iread Int             " link C_IreadInt}
	@{"=Iread Str$            " link C_IreadStr}
	@{"=Ireq Scr Colour       " link C_IreqScrCols}	(Kickstart 2.0 only)
	@{"=Ireq Scr Height       " link C_IreqScrHeight}	(Kickstart 2.0 only)
	@{"=Ireq Scr Mode         " link C_IreqScrMode}	(Kickstart 2.0 only)
	@{"=Ireq Scr Width        " link C_IreqScrWidth}	(Kickstart 2.0 only)
	@{" Irequest Def Title    " link C_IreqDefTitle}
	@{" Irequest Error        " link C_IrequestError}
	@{"=Irequest File$        " link C_IrequestFile}
	@{"=Irequest File Multi$  " link C_IreqFileMulti}
	@{"=Irequest File Next$   " link C_IreqFileNext}
	@{"=Irequest Font$        " link C_IrequestFont}
	@{"=Irequest Message      " link C_IrequestMessage}
	@{"=Irequest Screen       " link C_IrequestScreen}	(Kickstart 2.0 only)
	@{"=Irequest Warning      " link C_IrequestWarning}
	@{"=Iscan                 " link C_Iscan}
	@{"=Iscreen               " link C_GetIscreen}
	@{" Iscreen Amos Copy     " link C_AIscrCopy}
	@{"=Iscreen Base          " link C_IscreenBase}
	@{" Iscreen Close         " link C_IscreenClose}
	@{"=Iscreen Colour        " link C_IscreenColour}
	@{" Iscreen Copy          " link C_IscreenCopy}
	@{" Iscreen Display       " link C_IscreenDisplay}
	@{"=Iscreen Height        " link C_IscreenHeight}
	@{"=Iscreen Mode          " link C_IscreenMode}
	@{" Iscreen Offset        " link C_IscreenOffset}
	@{" Iscreen Open          " link C_IscreenOpen}
	@{" Iscreen Open Back     " link C_IscrOpenBack}
	@{" Iscreen Open Front    " link C_IscrOpenFront}
	@{" Iscreen Open Public   " link C_IscrOpenPublic}	(Kickstart 2.0 only)
	@{"=Iscreen Title Height  " link C_IscreenTitleHeight}
	@{" Iscreen To Back       " link C_IscreenToBack}
	@{" Iscreen To Front      " link C_IscreenToFront}
	@{"=Iscreen Width         " link C_IscreenWidth}
	@{"=Ishift                " link C_Ishift}
	@{" Itext                 " link C_Itext}
	@{"=Itext Base            " link C_ItextBase}
	@{"=Itext Length          " link C_ItextLength}
	@{" Itrap Off             " link C_Itrap}
	@{" Itrap On              " link C_Itrap}
	@{" Iwait                 " link C_Iwait}
	@{"=Iwait Event           " link C_IwaitEvent}
	@{"=Iwait Event Vbl       " link C_IwaitEvent}
	@{" Iwait Key             " link C_IwaitKey}
	@{" Iwait Mouse           " link C_IwaitMouse}
	@{" Iwait Vbl             " link C_IwaitVbl}
	@{"=Iwindow               " link C_GetIwindow}
	@{" Iwindow Activate      " link C_IwindowActivate}
	@{"=Iwindow Active        " link C_IwindowActive}
	@{"=Iwindow Active Base   " link C_IwindowActiveBase}
	@{"=Iwindow Active Num    " link C_IwindowActiveNum}
	@{"=Iwindow Actual Width  " link C_IwindowActual}
	@{"=Iwindow Actual Height " link C_IwindowActual}
	@{"=Iwindow Base          " link C_IwindowBase}
	@{" Iwindow Close         " link C_IwindowClose}
	@{" Iwindow Close Wb      " link C_IwindowCloseWB}
	@{"=Iwindow Height        " link C_IwindowHeight}
	@{" Iwindow Move          " link C_IwindowMove}
	@{"=Iwindow On Wb         " link C_IwindowOnWB}
	@{" Iwindow Open          " link C_IwindowOpen}
	@{" Iwindow Open Wb       " link C_IwindowOpenWB}
	@{" Iwindow Size          " link C_IwindowSize}
	@{"=Iwindow Status        " link C_IwindowStatus}
	@{" Iwindow To Back       " link C_IwindowToBack}
	@{" Iwindow To Front      " link C_IwindowToFront}
	@{"=Iwindow Width         " link C_IwindowWidth}
	@{"=Iwindow X             " link C_IwindowX}
	@{"=Iwindow Y             " link C_IwindowY}
	@{"=Ixgr                  " link C_Ixgr}
	@{"=Iygr                  " link C_Iygr}

	@{"=Reqtools Here         " link C_ReqtoolsHere}
	@{" Reserve Igadget       " link C_ReserveIgadget}

	@{" Set Icolour           " link C_SetIcolour}
	@{" Set Ifont             " link C_SetIfont}
	@{" Set Igadget Hit       " link C_SetIgadHit}
	@{" Set Igadget Hslider   " link C_SetIgadSlider}
	@{" Set Igadget Int       " link C_SetIgadInt}
	@{" Set Igadget String    " link C_SetIgadString}
	@{" Set Igadget Toggle    " link C_SetIgadToggle}
	@{" Set Igadget Value     " link C_SetIgadValue}
	@{" Set Igadget Value$    " link C_SetIgadValue}
	@{" Set Igadget Vslider   " link C_SetIgadSlider}
	@{" Set Imenu             " link C_SetImenu}
	@{" Set Ipens             " link C_SetIpens}
	@{" Set Iscreen           " link C_SetIscreen}
	@{" Set Iscreen Title     " link C_SetIscreenTitle}
	@{" Set Iwindow           " link C_SetIwindow}
	@{" Set Iwindow Title     " link C_SetIwindowTitle}
	@{" Set Iwindow Wb        " link C_SetIwindowWB}
	@{"=Superhires            " link C_Superhires}

	@{"=X Hard Min            " link C_XHardMin}
	@{"=X Ihard               " link C_XIhard}
	@{"=X Iscreen             " link C_XIscreen}

	@{"=Y Hard Min            " link C_YHardMin}
	@{"=Y Ihard               " link C_YIhard}
	@{"=Y Iscreen             " link C_YIscreen}

@endnode

@node Errors
@prev Index

Backward coordinates (25)

Coordinate ranges (x1,y1 To x2,y2) must ALWAYS have the upper-left
corner first, followed by the lower-right corner.  Otherwise, you'll
get this error.  (But it's better than visiting the Guru!)


Error text not available (22)

You compiled a program without error messages, and later tried to use
the Ierr$ function.  You'll never actually see this message text, but
the error number can be useful in conjunction with error trapping.


Font not available (15)

Set Ifont couldn't find the font you requested.  Make sure it is
available in the FONTS: directory.  If you included the ".font"
extension to the font name, make sure it is all lower case - something
like Set Ifont "fontname.Font" won't work.


Gadget already active (31)

You tried to change the definition of a gadget that was already
displayed.  Make sure you call Igadget Off first.


Gadget not defined (33)

You tried to use (enable, display, etc.) a gadget that was not first
defined with Set Igadget.


Gadget not reserved (34)

You tried to define a gadget with a number higher than the one you
gave to Reserve Igadget.  This error also occurs if you try to define
or use a gadget and do not first use Reserve Igadget.


Icon bank not defined (21)

The program does not have an icon bank.


Icon not defined (20)

The icon number given to Ipaste Icon represented a nonexistent icon.


Illegal function call (13)

A general catch-all error.  Something is wrong with a value you gave
to a command.  Check the command's documentation and your code to find
out exactly where the problem is.


Illegal number of colours (18)

Screens can only have certain numbers of colours, all powers of 2; a
screen can't have only 12 colours, for example.  Check the
@{" Iscreen Open " link C_IscreenOpen} documentation for details.


Illegal screen parameter (17)

A screen must be at least one pixel in each dimension.  If either the
width or the height of a new screen is less than or equal to zero,
this error will be generated.


Illegal window parameter (9)

You gave an illegal parameter to the Iwindow Open instruction; for
example, a window position that is off the screen.


Internal error (27, 28)

These errors should never occur; if they do, it means the Intuition
Extension has become very confused.  The error is followed by an
eight-digit code and possibly an eight-digit subcode; record these
codes and send them to me, preferably with a code sample.


Menu already active (26)

Before adding items to a menu or deleting items from a menu, or adding
or deleting menus, you must first disable the menus with Imenu Off.


Need Kickstart 2.0 or higher (2)

You called a function that requires Kickstart 2.0 or higher, such as
Irequest Screen, on a Kickstart 1.3b system.


Object bank not defined (24)

The program does not have an object bank.


Object not defined (23)

An instruction tried to use a nonexistent object (sprite or bob).


Only 16 colours allowed on non-AGA hires screen (0)

On original-chipset and ECS Amigas, high resolution screens are
limited to 16 colours.  If you try to open a hires screen with more
colours, this error will be generated.  You can check whether the
Amiga your program is running on has the AGA chipset with the @{" Aga " link C_Aga}
function.


Only 65535 gadgets allowed (30)

You cannot reserve space for more than 65535 gadgets with the Reserve
Igadget command.  (This is not usually a problem.)


Out of memory (14)

Some function ran out of memory while trying to do its stuff.  If the
Editor status line says you've still got lots of memory, save your
program and reboot your Amiga.  If you really are low on memory, try
using one or more of Close Editor, Kill Editor, and Kill Workbench
(although the last won't help if you're trying to use Workbench
windows!).


Program interrupted (12)

You pressed Ctrl-C to stop your program.  Note that this "error"
cannot be caught with Itrap.


ReqTools.library version 2 or higher required (29)

For any of the requester commands to work, ReqTools.library must be
installed in your system.  If it is not, those commands will generate
this error.


Screen not closed (19)

An open screen can't be reopened.  You have to close it first.


Screen not opened (16)

You tried to use a command that requires a screen (e.g. Icls), but
there are no screens open; or you tried to set the current screen
to a nonexistent screen.


Unable to open screen (1)

Some error (e.g. out of memory) occurred while trying to open a
screen.  If you get this error, then the problem occurred inside
Intuition's internal open-screen routine, rather than in the
Intuition Extension, and therefore there's no specific error
message that can be given.


Unable to open window (3)

An error occurred while trying to open a window.


Unable to open Workbench (11)

The Workbench screen couldn't be opened (for example, to put a
Workbench window on).


Valid AMOS screen numbers range from 0 to 7 (35)

You gave Amos Iscreen Copy an invalid AMOS screen number.


Window 0 can't be closed (4)
Window 0 can't be modified (5)

Window 0 is the base window on the screen.  It fills the whole screen,
and has to remain open as long as the screen is open.  (The Workbench
doesn't have this limitation, as it doesn't need a background window.)


Window not closed (10)

This error appears for one of two reasons:

	- You tried to close a screen that still had open windows.

	- You tried to open a window, but another window with the same
	  number was already open.


Window not opened (6)

You tried to use a window-related command (e.g. Iclw) without an open
window; or you gave Set Iwindow a number for a nonexistent window.

This error does not always mean you need a window opened with Iwindow
Open; remember that each screen has a base window as well!


Window too large (8)

A window can't be opened or resized so that it would extend past the
bottom or right side of the screen.


Window too small (7)

The minimum size of a window is 80x48 pixels.  If you try to open or
resize a window to smaller dimensions, you'll get this error.


Wrong gadget type (32)

You tried to use Igadget Read$ with a non-string gadget, or Igadget
Read with a string gadget.

@endnode


***COMMANDS BEGIN HERE
@node C_Aga "Intuition Extension 1.3b Command: =Aga"
@next C_AIscrCopy

=AGA
----

x=Aga

Returns True (-1) if the Amiga has the Advanced Graphics Architecture
(AGA) chipset; returns False (0) otherwise.  At the moment, the only
Amigas with the AGA chipset are the A1200 and A4000.

See also: @{" Ecs " link C_Ecs}

@endnode

@node C_AIscrCopy "Intuition Extension 1.3b Command: Amos Iscreen Copy"
@next C_Ecs
@prev C_Aga

AMOS ISCREEN COPY
ISCREEN AMOS COPY
-----------------

Amos Iscreen Copy source To destination
Amos Iscreen Copy source,x1,y1,x2,y2 To destination,x,y
Iscreen Amos Copy source To destination
Iscreen Amos Copy source,x1,y1,x2,y2 To destination,x,y

Copies part or all of an AMOS screen to an Intuition screen (first two
forms), or all or part of an Intuition screen to an AMOS screen (last
two forms).  The command's parameters are the same as those for
@{" Iscreen Copy " link C_IscreenCopy}, except that the source screen number (for Amos Iscreen
Copy) or destination screen number (Iscreen Amos Copy) refers to an
AMOS screen rather than an Intuition screen, and hence must be from 0
to 7 inclusive.

@endnode

@node C_Ecs "Intuition Extension 1.3b Command: =Ecs"
@next C_Ehb
@prev C_AIscrCopy

=ECS
----

x=Ecs

Returns True (-1) if the Amiga has the Enhanced Chip Set; returns
False (0) otherwise.  If the Amiga has half of the ECS (e.g. an ECS
Agnus and normal Denise), this returns False.

See also: @{" Aga " link C_Aga}

@endnode

@node C_Ehb "Intuition Extension 1.3b Command: =Ehb"
@next C_Ham
@prev C_Ecs

=EHB
----

x=Ehb

Returns the screen mode value for the ExtraHalfBrite mode.

See also: @{" Ham        " link C_Ham}
	  @{" Superhires " link C_Superhires}

@endnode

@node C_Ham "Intuition Extension 1.3b Command: =Ham"
@next C_IFlush
@prev C_Ehb

=HAM
----

x=Ham

Returns the screen mode value for Hold And Modify mode.

See also: @{" Ehb        " link C_Ehb}
	  @{" Superhires " link C_Superhires}

@endnode

@node C_IFlush "Intuition Extension 1.3b Command: I Flush"
@next C_Ibar
@prev C_Ham

I FLUSH
-------

I Flush

Frees any temporary memory the Intuition Extension has allocated.

WARNING: Because of the way AMOS handles strings, some of this memory
         may still be in use!  This can occur if you assign the result
         of a string-returning function directly to a string variable;
         for example,

A$=Irequest File$

         If you then execute the I Flush command, A$ will probably
         contain garbage!  This can be circumvented by adding the
         empty string to any variables you intend to save:

A$=Irequest File$+""

         Normally, string functions would use AMOS's string space to
         return values which might later be cleaned up during "garbage
         collection", but unfortunately, I can't take advantage of
         that.  The functions which handle allocation of string space
         for extensions work inconsistently between AMOS Creator and
         AMOS Pro, and are known to not work at all in at least one
         version.  Yes, this is really a kludge to avoid having memory
         get filled up, but due to AMOS's poor design, it is the only
         workable option.

@endnode

@node C_Ibar "Intuition Extension 1.3b Command: Ibar"
@next C_Ibox
@prev C_IFlulsh

IBAR
----

Ibar x1,y1 To x2,y2

Draws a filled-in box from (x1,y1) to (x2,y2) in the current colour.

@endnode

@node C_Ibox "Intuition Extension 1.3b Command: Ibox"
@next C_Icentre
@prev C_Ibar

IBOX
----

Ibox x1,y1 To x2,y2

Draws a box from (x1,y1) to (x2,y2) in the current colour.

@endnode

@node C_Icentre "Intuition Extension 1.3b Command: Icentre"
@next C_Ichoice
@prev C_Ibox

ICENTRE
-------

Icentre s$

Centres the string s$ on the current line.

@endnode

@node C_Ichoice "Intuition Extension 1.3b Command: =Ichoice"
@next C_Icircle
@prev C_Icentre

=ICHOICE
--------

num=Ichoice(level)

Returns the last menu number, item number, or subitem number selected,
depending on the value of level.  A value of 1 for level returns the
menu number; a value of 2 returns the item number; and a value of 3
returns the subitem number.  If the user has not selected a menu item
since the last call to Ichoice WITH THE SAME LEVEL VALUE, 0 is
returned.  Note that the different levels are distinct, so that, for
example, calling Ichoice(2) after Ichoice(1) returns the item number,
as you would expect, instead of 0.

As an example, this code determines what to do based on the user's
selection:

C1=Ichoice(1)
If C1=1
  C2=Ichoice(2)
  If C2=1
    'stuff for item 1
  End If
  If C2=2
    'stuff for item 2
  End If
  ...
End If
If C1=2
  ...
End If
...

The "If ... End If / If ... End If" constructs above could have been
replaced in AMOS Pro by "If ... Else If ... End If".

Note that the following code will NOT work:

If Ichoice(1)=1
  If Ichoice(2)=1
    ...
  Else If Ichoice(2)=2
    ...
  End If
Else If Ichoice(1)=2
  ...
End If
...

The second call to Ichoice(2) will return 0, no matter what the user
selected.  Likewise, the second call to Ichoice(1) will also return 0.

@endnode

@node C_Icircle "Intuition Extension 1.3b Command: Icircle"
@next C_Iclear
@prev C_Ichoice

ICIRCLE
-------

Icircle cx,cy,r

Draws a circle with centre (cx,cy) and radius r.  Equivalent to
Iellipse cx,cy,r,r.  Either or both of cx and cy may be omitted.

See also: @{" Iellipse " link C_Iellipse}

@endnode

@node C_Iclear "Intuition Extension 1.3b Command: Iclear"
@next C_Icls
@prev C_Icircle

ICLEAR
------

Iclear {Key | Mouse | Menu}
Iclear All

Input from windows and screens is stored in three buffers: one for
keystrokes, one for mouse button clicks, and one for menu selections.
When you read a key from the keyboard, for example, you are actually
reading from the keystroke buffer.

To clear any one of these buffers, so that any events that have
already been typed but not read are discarded, use the first form of
the command with the name of the buffer you want to clear.  To clear
all of the buffers, use the second form of the command.

@endnode

@node C_Icls "Intuition Extension 1.3b Command: Icls"
@next C_Iclw
@prev C_Iclear

ICLS
----

Icls
Icls colour
Icls colour,x1,y1 To x2,y2

Clears the current screen.  If colour is given, the screen is cleared
to that colour; otherwise, it is cleared to colour 0.  If any windows
are open on the screen, they are left intact.  So the statement

Icls 0

is essentially the same as

W=Iwindow : Set Iwindow 0 : Iclw : Set Iwindow W

although the first is faster and easier to understand.

The Icls statement can also clear a portion of the screen, if you
specify a range; for example:

Icls 0,20,20 To 180,100

See also: @{" Iclw " link C_Iclw}

@endnode

@node C_Iclw "Intuition Extension 1.3b Command: Iclw"
@next C_GetIcolour
@prev C_Icls

ICLW
----

Iclw
Iclw colour
Iclw colour,x1,y1 To x2,y2

Clears the current window.  If colour is given, the window is cleared
to that colour; otherwise, it is cleared to colour 0.  If a range is
giben, only that range of the window is cleared.

See also: @{" Icls " link C_Icls}

@endnode

@node C_GetIcolour "Intuition Extension 1.3b Command: =Icolour"
@next C_Idraw
@prev C_Iclw

=ICOLOUR
--------

rgb=Icolour(n)

Returns the RGB value of colour n.

See also: @{" Ipalette    " link C_Ipalette}
	  @{" Set Icolour " link C_SetIcolour}

@endnode

@node C_Idraw "Intuition Extension 1.3b Command: Idraw"
@next C_Iellipse
@prev C_GetIcolour

IDRAW
-----

Idraw x1,y1 To x2,y2
Idraw To x,y

Draws a line from the first pair of coordinates to the second.  If the
first pair is omitted, the line starts from the current coordinates
(the coordinates where the last output occurred).

@endnode

@node C_Iellipse "Intuition Extension 1.3b Command: Iellipse"
@next C_Ierr
@prev C_Idraw

IELLIPSE
--------

Iellipse cx,cy,rx,ry

Draws an ellipse with centre (cx,cy) and radii rx and ry.  Either or
both of cx and cy may be omitted.

See also: @{" Icircle " link C_Icircle}

@endnode

@node C_Ierr "Intuition Extension 1.3b Command: =Ierr"
@next C_IerrStr
@prev C_Iellipse

=IERR
-----

errnum=Ierr

Returns the error number of the last error that occurred.  This is
useful in conjunction with error trapping.

See also: @{"=Ierr$  " link C_IerrStr}
	  @{" Ierror " link C_Ierror}

@endnode

@node C_IerrStr "Intuition Extension 1.3b Command: =Ierr$"
@next C_Ierror
@prev C_Ierr

=IERR$
------

err$=Ierr$

Returns the text corresponding to the last error that occurred.  This
is useful in conjunction with error trapping.

See also: @{"=Ierr   " link C_Ierr}
	  @{" Ierror " link C_Ierror}

@endnode

@node C_Ierror "Intuition Extension 1.3b Command: Ierror"
@next C_Ierrtrap
@prev C_IerrStr

IERROR
------

Ierror n

Generates error number n.  Unless trapped, the program is halted and
the appropriate Intuition Extension error message is displayed.
(Remember to press LeftAmiga+A to get back to the AMOS screen if
you're on the Workbench!)

See also: @{"=Ierr  " link C_Ierr}
	  @{"=Ierr$ " link C_IerrStr}

@endnode

@node C_Ierrtrap "Intuition Extension 1.3b Command: =Ierrtrap"
@next C_IeventType
@prev C_Ierror

=IERRTRAP
---------

x=Ierrtrap

If error trapping is enabled (see @{" Itrap On/Off " link C_Itrap}), this function
returns True if an error occurred since the last call to Ierrtrap (or
since the call to Itrap On), and False if no errors have occurred.  If
True is returned, the @{" Ierr " link C_Ierr} and @{" Ierr$ " link C_IerrStr} functions can be used to
determine which error occurred.

After calling this function, its value is automatically reset to False.

@endnode

@node C_IeventType "Intuition Extension 1.3b Command: =Ievent"
@next C_IeventData
@prev C_Ierrtrap

=IEVENT
-------

event=Ievent type

This is a special kind of function which does not use parentheses
around its argument.  It returns a value which is the "event number"
of the event type passed to it.  The type can be any of:

	Vbl	    Vertical blank occurred
	Close	    Window's close gadget clicked on
	Menu	    Menu item selected
	Gadget	    Gadget clicked on
	Key	    Key pressed

This is commonly used in conjunction with the @{" Iwait Event " link C_IwaitEvent} function
to determine what action to take after an event has occurred.

@endnode

@node C_IeventData "Intuition Extension 1.3b Command: =Ievent Data"
@next C_IfontBase
@prev C_IeventType

=IEVENT DATA
------------

data=Ievent Data

This function is used in conjunction with @{" Iwait Event " link C_IwaitEvent} to give extra
information about an event that has occurred.  Currently, only a
gadget event has extra data to be read by this function; it returns
the number of the gadget that was clicked on.

See also: @{"=Ievent " link C_IeventType}

@endnode

@node C_IfontBase "Intuition Extension 1.3b Command: =Ifont Base"
@next C_IfontHeight
@prev C_IeventData

=IFONT BASE
-----------

address=Ifont Base

Returns the address of the TextFont structure of the current font.

NOTE: This command is Fonti Base in AMOS Creator.

@endnode

@node C_IfontHeight "Intuition Extension 1.3b Command: =Ifont Height"
@next C_IfontName
@prev C_IfontBase

=IFONT HEIGHT
-------------

h=Ifont Height

Returns the height, in pixels, of the current font.

NOTE: This command is Fonti Height in AMOS Creator.

See also: @{" Set Ifont " link C_SetIfont}
	  @{"=Ifont$    " link C_IfontName}

@endnode

@node C_IfontName "Intuition Extension 1.3b Command: =Ifont$"
@next C_IgadgetActive
@prev C_IfontHeight

=IFONT$
-------

font$=Ifont$

Returns the name of the current font, including the ".font" extension.

NOTE: This command is Fonti$ in AMOS Creator.

See also: @{" Set Ifont    " link C_SetIfont}
	  @{"=Ifont Height " link C_IfontHeight}

@endnode

@node C_IgadgetActive "Intuition Extension 1.3b Command: Igadget Active"
@next C_IgadgetDown
@prev C_IfontName

IGADGET ACTIVE
--------------

Igadget Active
Igadget Active n

Activates gadget number n, or (if n is omitted) all defined gadgets
for the current window.

See also: @{" Igadget Inactive " link C_IgadgetInactive}

@endnode

@node C_IgadgetDown "Intuition Extension 1.3b Command: =Igadget Down"
@next C_IgadgetInactive
@prev C_IgadgetActive

=IGADGET DOWN
-------------

down=Igadget Down(n)

Returns whether gadget number n is currently selected or depressed.
For string and integer gadgets, this function returns True if the
gadget is in use (the user is typing in the gadget); for hit-select
and toggle gadgets, it returns True if the pointer is over the gadget
and the left mouse button is depressed; for sliders, it returns True
if the pointer is over the slider bar and the left mouse button is
depressed.

This function is useful for selective updating of a display; for
example, if a gadget were used to scroll through a list of images, and
and the program had a "preview" window in which it displayed a scaled-
down version of the image, the program could update only the image
name and description while the user was moving the slider, then update
the preview window when the user released the mouse button, allowing
for faster response to the user's actions.  This could be implemented
in code similarly to the following:

While Not QUIT
   ...

   'See if the slider moved
   If Igadget Read(1)<>IMAGENUM
      'See if the user is moving the slider with the mouse.  This does
      '   not necessarily have to be the case - the user could have
      '   clicked in the container but not on the slider itself.
      '
      'We use a Repeat/Until loop because, even if the slider is not
      '   "down", we need to get the new image number and display the
      '   name.
      Repeat
         IMAGENUM=Igadget Read(1)
         UPDATE_IMAGE_NAME[IMAGENUM] : Rem Only update the image name
      Until Not Igadget Down(1)
      'Now update the preview window
      UPDATE_PREVIEW_WINDOW[IMAGENUM]
   End If

   ...
Wend

@endnode

@node C_IgadgetInactive "Intuition Extension 1.3b Command: Igadget Inactive"
@next C_IgadgetOff
@prev C_IgadgetDown

IGADGET INACTIVE
----------------

Igadget Inactive
Igadget Inactive n

Deactivates gadget number n, or (if n is omitted) all defined gadgets
for the current window.  An inactive gadget cannot be selected, and is
"ghosted" (overlaid with a pattern of dots).

See also: @{" Igadget Inactive " link C_IgadgetInactive}

@endnode

@node C_IgadgetOff "Intuition Extension 1.3b Command: Igadget Off"
@next C_IgadgetOn
@prev C_IgadgetInactive

IGADGET OFF
-----------

Igadget Off
Igadget Off n

Removes one or all gadgets from the current window.  When a gadget is
removed, it disappears from the window; however, its value remains in
memory unless it is redefined or a @{" Reserve Igadget " link C_ReserveIgadget} command is
executed.

See also: @{" Igadget On " link C_IgadgetOn}

@endnode

@node C_IgadgetOn "Intuition Extension 1.3b Command: Igadget On"
@next C_IgadgetRead
@prev C_IgadgetOff

IGADGET ON
----------

Igadget On
Igadget On n

Adds one or more gadgets to the current window.  If n is given, that
gadget is added; otherwise, all defined gadgets are added (unless
they have been added previously).  After an Igadget On command, the
current value of a gadget can be obtained with the @{" Igadget Read " link C_IgadgetRead}
function.

See also: @{" Igadget On " link C_IgadgetOff}

@endnode

@node C_IgadgetRead "Intuition Extension 1.3b Command: =Igadget Read"
@next C_IgetIcon
@prev C_IgadgetOn

=IGADGET READ
-------------

value=Igadget Read(n)
value$=Igadget Read$(n)

Returns the current value of the specified gadget.  Igadget Read$ can
only be used with string gadgets; Igadget Read can be used with any
gadget type other than string gadgets.  If the gadget type is
inappropriate for the function, the "Wrong gadget type" error is
generated.

The value returned by the Igadget Read function depends on the type
of gadget.  String gadgets return the text in the gadget; integer
gadgets return the value in the gadget; sliders return the position
of the slider in units (as specified in the @{" Set Igadget Hslider " link C_SetIgadSlider}
or @{" Set Igadget Vslider " link C_SetIgadSlider} instruction; toggle gadgets return True if
the gadget is "on", False if it is "off".

@endnode

@node C_IgetIcon "Intuition Extension 1.3b Command: Iget Icon"
@next C_IgetIconPal
@prev C_IgadgetRead

IGET ICON
---------

Iget Icon n,x1,y1 To x2,y2
Iget Icon screen,n,x1,y1 To x2,y2
Iget Icon screen,window,n,x1,y1 To x2,y2

Grabs an image and stores it in the icon bank.  N is the icon number
to store the image in; it must already exist, so you should use the
built-in Ins Icon instruction to create it if necessary.  For example,
if you needed to grab 10 icons, you could use code similar to the
following:

Ins Icon 1 To 10
Iget Icon 1,0,0 To 15,11
Iget Icon 2,0,16 To 31,11

and so on.

Following the icon number are the coordinates to grab the image from.
Normally, these are taken from the current screen or window.  If you
want to use a different source for the icon, you can specify the
screen number and, if necessary, the window number to take the image
from.  If you specify a screen number but omit the window number, the
base window (window number 0) is used.

Note that the only way to grab icons from a Workbench window is to
first set the current window to that window with Set Iwindow Wb, then
call Iget Icon.

@endnode

@node C_IgetIconPal "Intuition Extension 1.3b Command: Iget Icon Palette"
@next C_IgetSprPal
@prev C_IgetIcon

IGET ICON PALETTE
-----------------

Iget Icon Palette
Iget Icon Palette mask

Reads the colour palette from the icon bank of the program, and uses it
as the palette for the current screen.

Mask is an optional parameter that indicates which colours should be
copied from the icon bank.  Each bit represents one colour, and the
lowest bit represents colour 0.  So, if you just wanted to get colours
1, 2, 6, and 8, and leave the other colours alone, you could use:

Iget Icon Palette %101000110

Note that only the first 32 colours can be affected in any case, since
object and icon banks only contain 32-colour palettes.  (The exception
is Extra-Half-Brite mode, in which colours 32-63 are half the intensity
of colours 0-31, and are therefore also changed.)

If mask is omitted, all of the colours (0-31) are copied.

See also: @{" Iget Sprite Palette " link C_IgetSprPal}
	  @{" Ipalette            " link C_Ipalette}

@endnode

@node C_IgetSprPal "Intuition Extension 1.3b Command: Iget Sprite Palette"
@next C_Iget
@prev C_IgetIconPal

IGET SPRITE PALETTE
-------------------

Iget Sprite Palette
Iget Sprite Palette mask

Reads the colour palette from the object (sprite) bank of the
program, and uses it as the palette for the current screen.

Mask is an optional parameter that indicates which colours should be
copied from the icon bank.  Each bit represents one colour, and the
lowest bit represents colour 0.  So, if you just wanted to get colours
1, 2, 6, and 8, and leave the other colours alone, you could use:

Iget Sprite Palette %101000110

Note that only the first 32 colours can be affected in any case, since
object and icon banks only contain 32-colour palettes.  (The exception
is Extra-Half-Brite mode, in which colours 32-63 are half the intensity
of colours 0-31, and are therefore also changed.)

If mask is omitted, all of the colours (0-31) are copied.

See also: @{" Iget Icon Palette " link C_IgetIconPal}
	  @{" Ipalette          " link C_Ipalette}

@endnode

@node C_Iget "Intuition Extension 1.3b Command: =Iget$"
@next C_IgrWriting
@prev C_IgetSprPal

=IGET$
------

ch$=Iget$

Returns the next character in the input buffer, or an empty string if
there are no characters waiting.

See also: @{"=Iread Char$ " link C_IreadChar} to wait for a key before returning
	  @{" Iwait Key   " link C_IwaitKey} to just wait for a key to be pressed

@endnode

@node C_IgrWriting "Intuition Extension 1.3b Command: Igr Writing"
@next C_Iink
@prev C_Iget

IGR WRITING
-----------

Igr Writing n

Changes the mode for writing text and graphics to the screen.  The
lower three bits of n are used as follows:

Bit 2: 1 = Swap foreground and background colours (inverse text).
       0 = Use foreground and background colours normally.
Bit 1: 1 = Write the text using an XOR operation.
       0 = Write the text using a standard MOVE operation.
Bit 0: 1 = Write both foreground and background colours to the screen.
       0 = Write only the foreground colour to the screen.

Igr Writing affects *all* graphics commands, including Itext, Iwrite,
Idraw, Ibar, etc.  However, it does not affect commands like Iscreen
Copy that work at the screen level.

Here are some examples:

Iscreen Open 0,320,200,4,0 : Ipalette 0,$F00,$F0,$F
Iink 2,1
Igr Writing 1
Iwrite "Green on red"
Igr Writing 5
Iwrite "Red on green"
Igr Writing 0
Iwrite "Green on black"
X=Ixgr : Y=Iygr
Igr Writing 4
Itext X,Y,"Red on black"
Iwait 50
Igr Writing 6
Itext X,Y,"Red on black" : Rem This makes the text disappear

@endnode

@node C_Iink "Intuition Extension 1.3b Command: Iink"
@next C_Ilocate
@prev C_IgrWriting

IINK
----

Iink foreground
Iink foreground,background

Sets the colours to be used for drawing.  Foreground is the colour
used for almost all drawing operations.  Background is the colour used
for the background of text written to the screen.

[Outline is a bit different: when the Iflood instruction is called with
a mode parameter of 0, the flood fill stops at pixels of colour
"outline".]

@endnode

@node C_Ilocate "Intuition Extension 1.3b Command: Ilocate"
@next C_ImouseKey
@prev C_Iink

ILOCATE
-------

Ilocate x,y

Positions the graphics cursor at (x,y) in text coordinates.  Either
parameter can be omitted.  The standard height and width for the
current font are used, so strange results can be obtained when a
proportinal font is being used.

This command is useful in conjunction with @{" Itext " link C_Itext} to position the
cursor on a certain line without getting into complex expressions.

See also: @{" Iwrite     " link C_Iwrite}
          @{" Ilocate Gr " link C_IlocateGr}

@endnode

@node C_IlocateGr "Intuition Extension 1.3b Command: Ilocate Gr"
@next C_ImenuOnOff
@prev C_Ilocate

ILOCATE GR
----------

Ilocate Gr x,y

Positions the graphics cursor at graphics coordinates (x,y).  This is
not very useful, as all output instructions accept coordinates, but
it is included for copmleteness, and in case somebody discovers that
they need it. :-)

See also: @{" Ilocate " link C_Ilocate}
          @{"=Ixgr    " link C_Ixgr}
          @{"=Iygr    " link C_Iygr}

@endnode

@node C_ImenuOnOff "Intuition Extension 1.3b Command: Imenu On/Off"
@next C_ImouseKey
@prev C_IlocateGr

IMENU ON
IMENU OFF
---------

Imenu On
Imenu Off

Imenu On activates the menu bar for the currently active window, if
that window has any menus defined.  Imenu Off turns the menu bar off.

See also: @{" Set Imenu " link C_SetImenu}

@endnode

@node C_ImouseKey "Intuition Extension 1.3b Command: =Imouse Key"
@next C_ImouseX
@prev C_IlocateGr

=IMOUSE KEY
-----------

k=Imouse Key

Returns the status of the mouse buttons.  Bit 0 is the left button,
bit 1 is the right button, and bit 2 is the middle button.  So a value
of %011 indicates that both the left and right mouse buttons are
pressed.

See also: @{"=Imouse X " link C_ImouseX}
	  @{"=Imouse Y " link C_ImouseY}

@endnode

@node C_ImouseX "Intuition Extension 1.3b Command: =Imouse X"
@next C_ImouseY
@prev C_ImouseKey

=IMOUSE X
---------

mx=Imouse X

Returns the current X coordinate of the mouse pointer relative to the
current screen (in screen coordinates).

See also: @{"=Imouse Y   " link C_ImouseY}
	  @{"=Imouse Key " link C_ImouseKey}

@endnode

@node C_ImouseY "Intuition Extension 1.3b Command: =Imouse Y"
@next C_Ipalette
@prev C_ImouseX

=IMOUSE Y
---------

mx=Imouse Y

Returns the current Y coordinate of the mouse pointer relative to the
current screen (in screen coordinates).

See also: @{"=Imouse X   " link C_ImouseX}
	  @{"=Imouse Key " link C_ImouseKey}

@endnode

@node C_Ipalette "Intuition Extension 1.3b Command: Ipalette"
@next C_IpasteIcon
@prev C_ImouseY

IPALETTE
--------

Ipalette colour-list

Sets one or more colour values on the current screen.  Colour-list is
a list of the colours to be set; any values omitted in the list are
not changed on the screen.  For example, the statement

	Ipalette ,,,$F00,,,$F0,$F

would set colour 3 to red, colour 6 to green, and colour 7 to blue.
The list of colours can be as long or as short as necessary, providing
that it does not exceed the 251-character line length limit of the
AMOS editor.

See also: @{" Set Icolour " link C_SetIcolour}
	  @{"=Icolour     " link C_GetIcolour}

@endnode

@node C_IpasteIcon "Intuition Extension 1.3b Command: Ipaste Icon"
@next C_Iplot
@prev C_Ipalette

IPASTE ICON
-----------

Ipaste Icon x,y,n

Copies icon number n to the current screen/window at coordinates x,y.
The graphics pointer is left at the top left corner of the icon image.
Normally, the image will completely replace whatever is underneath it;
however, if the Make Icon Mask instruction is executed first, colour 0
will be transparent, so that whatever is underneath blank areas of the
icon will show through.

@endnode

@node C_Iplot "Intuition Extension 1.3b Command: Iplot"
@next C_IreadChar
@prev C_IpasteIcon

IPLOT
-----

Iplot x,y
Iplot x,y,colour

Plots a point on the screen at coordinates (x,y).  If colour is given,
that colour is used to plot the point; otherwise, the current
foreground colour is used.

@endnode

@node C_IreadChar "Intuition Extension 1.3b Command: =Iread Char$"
@next C_IreadInt
@prev C_Iplot

=IREAD CHAR$
------------

ch$=Iread Char$

Waits for a key to be pressed and returns it.  If there are characters
in the buffer, it takes the first of those instead.  The character is
not echoed to the screen.

See also: @{"=Iget$     " link C_Iget} to return a value without waiting
	  @{" Iwait Key " link C_IwaitKey} to just wait for a key without returning anything

@endnode

@node C_IreadInt "Intuition Extension 1.3b Command: =Iread Int"
@next C_IreadStr
@prev C_IreadChar

=IREAD INT
----------

n=Iread Int

Reads an integer and returns it.  The integer may be in decimal,
hexadecimal, or binary, and can cover the full range of integers
(-2147483648..2147483647).  Illegal characters are ignored; if no
characters are typed before Return, 0 is returned.

See also: @{"=Iread Str$ " link C_IreadStr} to read a string

@endnode

@node C_IreadStr "Intuition Extension 1.3b Command: =Iread Str$"
@next C_IreqScrCols
@prev C_IreadInt

=IREAD STR$
-----------

s$=Iread Str$

Reads a string, terminated with a Return; each character is echoed on
the screen as it is typed.  Similar to "Line Input S$".

See also: @{"=Iread Int " link C_IreadInt} to read a number with input checking

@endnode

@node C_IreqScrCols "Intuition Extension 1.3b Command: =Ireq Scr Colour"
@next C_IreqScrHeight
@prev C_IrequestScreen

=IREQ SCR COLOUR (Kickstart 2.0 only)
----------------

nc=Ireq Scr Colour

Returns the number of colours from the most recent Irequest Screen.

See also: @{"=Irequest Screen " link C_IrequestScreen}
          @{"=Ireq Scr Width  " link C_IreqScrWidth}
          @{"=Ireq Scr Height " link C_IreqScrHeight}
          @{"=Ireq Scr Mode   " link C_IreqScrMode}

@endnode

@node C_IreqScrHeight "Intuition Extension 1.3b Command: =Ireq Scr Height"
@next C_IreqScrMode
@prev C_IreqScrCols

=IREQ SCR HEIGHT (Kickstart 2.0 only)
----------------

h=Ireq Scr Height

Returns the height from the most recent Irequest Screen.

See also: @{"=Irequest Screen " link C_IrequestScreen}
          @{"=Ireq Scr Width  " link C_IreqScrWidth}
          @{"=Ireq Scr Colour " link C_IreqScrCols}
          @{"=Ireq Scr Mode   " link C_IreqScrMode}

@endnode

@node C_IreqScrMode "Intuition Extension 1.3b Command: =Ireq Scr Mode"
@next C_IreqScrWidth
@prev C_IreqScrHeight

=IREQ SCR MODE (Kickstart 2.0 only)
--------------

mode=Ireq Scr Mode(n)

Returns the screen mode or display mode from the most recent Irequest
Screen.  If n is 0, the screen mode (e.g. Ham, Hires) is returned.  If
n is 1, the display mode (see @{" Iscreen Open " link C_IscreenOpen})
is returned.

See also: @{"=Irequest Screen " link C_IrequestScreen}
          @{"=Ireq Scr Width  " link C_IreqScrWidth}
          @{"=Ireq Scr Height " link C_IreqScrHeight}
          @{"=Ireq Scr Colour " link C_IreqScrCols}

@endnode

@node C_IreqScrWidth "Intuition Extension 1.3b Command: =Ireq Scr Width"
@next C_IrequestError
@prev C_IreqScrMode

=IREQ SCR WIDTH (Kickstart 2.0 only)
---------------

w=Ireq Scr Width

Returns the width from the most recent Irequest Screen.

See also: @{"=Irequest Screen " link C_IrequestScreen}
          @{"=Ireq Scr Height " link C_IreqScrHeight}
          @{"=Ireq Scr Colour " link C_IreqScrCols}
          @{"=Ireq Scr Mode   " link C_IreqScrMode}

@endnode

@node C_IreqDefTitle "Intuition Extension 1.3b Command: Irequest Def Title"
@next C_IrequestError
@prev C_IreqScrWidth

IREQUEST DEF TITLE
------------------

Irequest Def Title title$

Sets the default title for all message requesters (those displayed by
@{" Irequest Message " link C_IrequestMessage}, @{" Irequest Warning " link C_IrequestWarning}, or @{" Irequest Error " link C_IrequestError}) to
title$.  Initially, the default title is "AMOS Request".  If title$ is
empty, the title is set back to this.  If you really want a blank
title, use a single space (" ") for title$.

@endnode

@node C_IrequestError "Intuition Extension 1.3b Command: Irequest Error"
@next C_IrequestFile
@prev C_IreqDefTitle

IREQUEST ERROR
--------------

Irequest Error s$
Irequest Error s$,cancel$
Irequest Error title$,s$,cancel$

Displays a requester containing an error message; one gadget, a
"Cancel" gadget, is provided.  This command should be used when an
error has occurred that prevents your program from proceeding normally
(such as a bad file format).  Irequest Error does not actually stop
your program, but just displays the requester.

Title$ is the title to display in the title bar.  If omitted, the
default title is used.

The variable s$ contains the text to display in the requester window.
Each line of text should be separated by a vertical bar.

The cancel$ parameter allows you to change the text on the Cancel
gadget from its default of "Cancel".  What you specify here is printed
in the gadget.

See also: @{" Irequest Def Title " link C_IreqDefTitle}
	  @{"=Irequest Message   " link C_IrequestMessage}
	  @{"=Irequest Warning   " link C_IrequestWarning}

@endnode

@node C_IrequestFile "Intuition Extension 1.3b Command: =Irequest File$"
@next C_IreqFileMulti
@prev C_IrequestError

=IREQUEST FILE$
---------------

filename$=Irequest File$
filename$=Irequest File$(title$ [,pattern$ [,default$] ] )

Displays a file requester on the current screen, or on the Workbench
screen if there are no screens open.  Title$ is the text to display
in the title bar of the requester.  It must be small enough to fit in
the title bar - no two-line titles, as with the AMOS file reqester.

Pattern$ is a standard AmigaDOS wildcard to determine which files are
displayed in the requester.  Note that this differs from the AMOS
wildcard format; for example, AMOS's "**" (all files) pattern is "#?"
in AmigaDOS.  See your system manuals for more on AmigaDOS wildcards.

Default$ is the filename displayed in the requester's file gadget when
it comes up.  If the user just presses Return, this is the filename
that is returned.  If this parameter is omitted and the user just
presses Return, an empty string is returned.

Note that the "Cancel" gadget in the file requester always causes
Irequest File$ to return an empty string.

See also: @{"=Irequest File Multi$ " link C_IreqFileMulti}

@endnode

@node C_IreqFileMulti "Intuition Extension 1.3b Command: =Irequest File Multi$"
@next C_IreqFileNext
@prev C_IrequestFile

=IREQUEST FILE MULTI$
---------------------

f$=Irequest File Multi$
f$=Irequest File Multi$(title$ [,pattern$] )

Asks the user to select multiple files.  Returns the first file in the
list; the rest can be obtained with @{" Irequest File Next$ " link C_IreqFileNext}.  The
parameters to Irequest File Multi$ are the same as those to
@{" Irequest File$ " link C_IrequestFile}, except that you cannot specify a default filename.
See also: @{"=Irequest File$      " link C_IrequestFile}

@endnode

@node C_IreqFileNext "Intuition Extension 1.3b Command: =Irequest File Next$"
@next C_IrequestFont
@prev C_IreqFileMulti

=IREQUEST FILE NEXT$
--------------------

f$=Irequest File Next$

Returns the next file in a list of files following an
@{" Irequest File Multi$ " link C_IreqFileMulti}.  When all the files have been read, this
returns an empty string.

@endnode

@node C_IrequestFont "Intuition Extension 1.3b Command: =Irequest Font$"
@next C_IrequestMessage
@prev C_IrequestFileNext

=IREQUEST FONT$
---------------

font$=Irequest Font$
font$=Irequest Font$(title$)

Displays a font requester, and returns the font selected in the format
"fontname/size", or the null string if the requester was canceled.
This string can be passed to @{" Set Ifont " link C_SetIfont} to set the font to the user's
preference.

@endnode

@node C_IrequestMessage "Intuition Extension 1.3b Command: =Irequest Message"
@next C_IrequestScreen
@prev C_IrequestFont

=IREQUEST MESSAGE
-----------------

response=Irequest Message(text$,gadget$)
response=Irequest Message(title$,text$,gadget$)

Displays a requester containing a message, with any number of possible
responses.

Title$, if given, is the title to put in the title bar of the
requester.  If not given, the default title is used.

Text$ is the text to display in the requester.  Each line of text
should be separated with a vertical bar.  For example, the string

"Please select the|number of players."

would display as:

Please select the
number of players.

Gadget$ is the list of all the gadgets to include in the requester.
There must be at least one gadget, and each gadget name should be
separated with a vertical bar.  So, for example, the gadget$ parameter
from the last example might be "1|2|3|4", resulting in the following
requester:
 ____________________
|.| Requester Title  |
|_|__________________|
|                    |
| Please select the  |
| number of players. |
|____________________|
| ___  ___  ___  ___ |
||   ||   ||   ||   ||
|| 1 || 2 || 3 || 4 ||
||___||___||___||___||
|____________________|


The return value is set to the number of the gadget, starting at one
(for the leftmost gadget) and increasing toward the right.

See also: @{"=Irequest Def Title " link C_IreqDefTitle}
	  @{"=Irequest Warning   " link C_IrequestWarning}
	  @{" Irequest Error     " link C_IrequestError}

@endnode

@node C_IrequestScreen "Intuition Extension 1.3b Command: =Irequest Screen"
@next C_IrequestWarning
@prev C_IrequestMessage

=IREQUEST SCREEN (Kickstart 2.0 only)
----------------

ok=Irequest Screen
ok=Irequest Screen(title$)

Requests a screen mode, size, and depth from the user.  The returned
values can be examined using the Ireq Scr XXX functions.  If
the user cancelled, the return value is False; otherwise, it is True.

See also: @{"=Ireq Scr Width  " link C_IreqScrWidth}
          @{"=Ireq Scr Height " link C_IreqScrHeight}
          @{"=Ireq Scr Colour " link C_IreqScrCols}
          @{"=Ireq Scr Mode   " link C_IreqScrMode}

@endnode

@node C_IrequestWarning "Intuition Extension 1.3b Command: =Irequest Warning"
@next C_Iscan
@prev C_IrequestScreen

=IREQUEST WARNING
-----------------

response=Irequest Warning(s$)
response=Irequest Warning(s$,ok$,cancel$)
response=Irequest Warning(title$,s$,ok$,cancel$)

Displays a requester with a warning message.  If the user selects the
"OK" gadget, True is returned; otherwise, False is returned.

Title$ is the title to display in the title bar.  If omitted, the
default title is used.

S$ is the text string to display in the requester.  Text that should
appear on different lines in the requester should be separated by a
vertical bar.

Ok$ and Cancel$ allow you to replace the default gadget text of "OK"
and "Cancel" with text of your choice.  For example, you could replace
them with "Continue" and "Abort".

See also: @{" Irequest Def Title " link C_IreqDefTitle}
	  @{"=Irequest Message   " link C_IrequestMessage}
	  @{" Irequest Error     " link C_IrequestError}

@endnode

@node C_Iscan "Intuition Extension 1.3b Command: =Iscan"
@next C_GetIscreen
@prev C_IrequestWarning

=ISCAN
------

scancode=Iscan

Returns the scan code of the last key pressed.

See also: @{"=Ishift " link C_Ishift}

@endnode

@node C_GetIscreen "Intuition Extension 1.3b Command: =Iscreen"
@next C_IscreenBase
@prev C_Iscan

=ISCREEN
--------

n=Iscreen

Returns the number of the current screen.

See also: @{" Set Iscreen " link C_SetIscreen}

@endnode

@node C_IscreenBase "Intuition Extension 1.3b Command: =Iscreen Base"
@next C_IscreenClose
@prev C_GetIscreen

=ISCREEN BASE
-------------

address=Iscreen Base

Returns the address of the Intuition Screen structure for the current
screen.

@endnode

@node C_IscreenClose "Intuition Extension 1.3b Command: Iscreen Close"
@next C_IscreenColour
@prev C_IscreenBase

ISCREEN CLOSE
-------------

Iscreen Close n

Closes screen number n.

See also: @{" Iscreen Open " link C_IscreenOpen}

@endnode

@node C_IscreenColour "Intuition Extension 1.3b Command: =Iscreen Colour"
@next C_IscreenCopy
@prev C_IscreenClose

=ISCREEN COLOUR
---------------

colours=Iscreen Colour
colours=Iscreen Colour(n)

Returns the number of colours available for use on screen n or the
current screen.

See also: @{"=Iscreen Width  " link C_IscreenWidth}
	  @{"=Iscreen Height " link C_IscreenHeight}
	  @{"=Iscreen Mode   " link C_IscreenMode}

@endnode

@node C_IscreenCopy "Intuition Extension 1.3b Command: Iscreen Copy"
@next C_IscreenDisplay
@prev C_IscreenColour

ISCREEN COPY
------------

Iscreen Copy source To destination
Iscreen Copy source,x1,y1,x2,y2 To destination,x,y

Copies part or all of one screen to another.  With the first form, the
entire source screen is copied to the destination screen.  (If the
destination screen is smaller than the source, you will probably crash
your Amiga!)

With the second form, the rectangular block (x1,y1)-(x2.y2) is copied
from the source screen to coordinates (x,y) on the destination screen.
Again, you have to make sure that the entire block will fit on the
destination screen at the coordinates you specify to avoid corrupting
memory.

@endnode

@node C_IscreenDisplay "Intuition Extension 1.3b Command: Iscreen Display"
@next C_IscreenHeight
@prev C_IscreenCopy

ISCREEN DISPLAY
---------------

Iscreen Display n,x,y,w,h

Positions a screen, and sets its visible size.  Any of the position
and size parameters can be omitted; the corresponding value will
remain the same.  The screen is moved to coordinates (x,y) relative to
the top left corner of the Intuition display (in screen pixels), and
the visible size is set to w by h pixels.  The screen position is
limited to the borders of the Intuition display.

NOTE: Under Kickstart 1.3b, screens cannot be moved horizontally.

See also: @{" Iscreen Offset " link C_IscreenOffset}

@endnode

@node C_IscreenHeight "Intuition Extension 1.3b Command: =Iscreen Height"
@next C_IscreenMode
@prev C_IscreenDisplay

=ISCREEN HEIGHT
---------------

h=Iscreen Height
h=Iscreen Height(n)

Returns the height of screen n or the current screen.

See also: @{"=Iscreen Width  " link C_IscreenWidth}
	  @{"=Iscreen Colour " link C_IscreenColour}
	  @{"=IScreen Mode   " link C_IscreenMode}

@endnode

@node C_IscreenMode "Intuition Extension 1.3b Command: =Iscreen Mode"
@next C_IscreenOffset
@prev C_IscreenHeight

=ISCREEN MODE
-------------

mode=Iscreen Mode
mode=Iscreen Mode(n)

Returns the mode value of screen n or the current screen.

See also: @{"=Iscreen Width  " link C_IscreenWidth}
	  @{"=Iscreen Height " link C_IscreenHeight}
	  @{"=Iscreen Colour " link C_IscreenColour}

@endnode

@node C_IscreenOffset "Intuition Extension 1.3b Command: Iscreen Offset"
@next C_IscreenOpen
@prev C_IscreenMode

ISCREEN OFFSET
--------------

Iscreen Offset n,xoffset,yoffset

Offsets the viewable portion of screen n to (xoffset,yoffset).  This
is used for screens which are larger than their visible area.

See also: @{" Iscreen Display " link C_IscreenDisplay}

@endnode

@node C_IscreenOpen "Intuition Extension 1.3b Command: Iscreen Open"
@next C_IscrOpenBack
@prev C_IscreenOffset

ISCREEN OPEN
------------

Iscreen Open n,width,height,colours,mode
Iscreen Open n,width,height,colours,mode,title$
Iscreen Open n,width,height,colours,mode,title$,displayID

Opens an Intuition screen and brings it to the front. The screen
number n can be any integer, so you are not limited to 8 screens as
with standard AMOS screens.  If screen n already exists, the
"Screen not closed" error is generated.

Width and height determine the size of the screen, as with the AMOS
Screen Open command.

Colours specifies the number of colours you want your screen to have.
Unlike Screen Open, if you want your screen to use a special mode like
ExtraHalfBrite or HAM, it is not enough to just use 64 or 4096 here;
you must also give the appropriate mode value (@{" Ehb " link C_Ehb}
or @{" Ham " link C_Ham}) in the Mode parameter.

Mode determines the screen mode (i.e. Lowres, Hires, Productivity,
EHB, HAM).

DisplayID, if given, is a system display identification number.
Common values are NTSC=$11000 and PAL=$21000.  Other values can be
found in the system reference manuals.  If this parameter is omitted,
the screen opens in the default display mode.  WARNING: only use this
parameter if you know what you are doing!

Title$, if given, is the title of the screen.  It will appear on the
screen title bar.  If title$ is empty or not given, the title bar will
not appear.

Following is a list of common screen types, normal width and height
(for PAL/NTSC), maximum number of colours (for normal/AGA chipsets),
and mode parameters.  Modes only available on AGA are marked with '*';
modes only available on ECS or AGA are marked with '+'.  Interlaced
modes are not listed; to construct them, simply add Laced to the Mode
parameter.  For HAM modes, be sure to specify the correct number of
colours (the one listed).

Type (*=AGA, +=ECS)	Width	Height	  MaxCols	     Mode
-------------------	-----	-------	-----------	--------------
 Lowres			 320	256/200	  32/   256	Lowres (or 0)
 Lowres EHB		 320	256/200	  64/   256	Ehb
 Lowres HAM		 320	256/200	4096/  4096	Ham
*Lowres HAM8		 320	256/200	----/262144	Ham
 Hires			 640	256/200	  16/   256	Hires
*Hires EHB		 640	256/200	----/   256	Hires+Ehb
*Hires HAM		 640	256/200	----/  4096	Hires+Ham
*Hires HAM8		 640	256/200	----/262144	Hires+Ham
+SuperHires		1280	256/200	   4/   256	Superhires
*SuperHires EHB		1280	256/200	----/   256	Superhires+Ehb
*SuperHires HAM		1280	256/200	----/  4096	Superhires+Ham
*SuperHires HAM8	1280	256/200	----/262144	Superhires+Ham

Note that the Intuition screen will not be actually displayed until an
Amos To Back instruction is executed (or the user presses
LeftAmiga+A).

See also: @{" Iscreen Open Front  " link C_IscrOpenFront}
          @{" Iscreen Open Back   " link C_IscrOpenBack}
          @{" Iscreen Open Public " link C_IscrOpenPublic}
          @{" Iscreen Close       " link C_IscreenClose}
	  @{" Set Iscreen         " link C_SetIscreen}
	  @{"=Iscreen             " link C_GetIscreen}

@endnode

@node C_IscrOpenBack "Intuition Extension 1.3b Command: Iscreen Open Back"
@next C_IscrOpenFront
@prev C_IscreenOpen

ISCREEN OPEN BACK
-----------------

Iscreen Open Back

Causes any screens opened in the future to be opened in back of all
other screens.

See also: @{" Iscreen Open       " link C_IscreenOpen}
          @{" Iscreen Open Front " link C_IscrOpenFront}

@endnode

@node C_IscrOpenFront "Intuition Extension 1.3b Command: Iscreen Open Front"
@next C_IscrOpenPublic
@prev C_IscrOpenBack

ISCREEN OPEN FRONT
------------------

Iscreen Open Front

Causes any screens opened in the future to be opened in front of all
pther screens.

See also: @{" Iscreen Open      " link C_IscreenOpen}
          @{" Iscreen Open Back " link C_IscrOpenBack}

@endnode

@node C_IscrOpenPublic "Intuition Extension 1.3b Command: Iscreen Open Public"
@next C_IscrTitleHeight
@prev C_IscrOpenFront

ISCREEN OPEN PUBLIC (Kickstart 2.0 only)
-------------------

Iscreen Open Public n,width,height,colours,mode
Iscreen Open Public n,width,height,colours,mode,title$
Iscreen Open Public n,width,height,colours,mode,title$,displayID

Opens an Intuition screen.  The parameters are the same as those given
to Iscreen Open.  However, this instruction opens the screen in the
special "public" mode of Kickstart/Workbench 2.0 and above.  The
difference between a public screen and a normal screen is that other
programs may open their own windows on public screens.  Be careful
using this instruction; if your program tries to close a public screen
with other programs' windows still open on it, your program will
crash!

See also: @{" Iscreen Open " link C_IscreenOpen}

@endnode

@node C_IscrTitleHeight "Intuition Extension 1.3b Command: =Iscreen Title Height"
@next C_IscreenToBack
@prev C_IscrOpenPublic

=ISCREEN TITLE HEIGHT
---------------------

=Iscreen Title Height
=Iscreen Title Height(n)

Returns the height of the title bar of the current screen, or of screen
number n.  Useful to ensure that your output does not overwrite the
screen's title bar.  For example:

Text 0,Iscreen Title Height+Itext Base,"Text right below the title bar"

See also: @{" Set Iscreen Title " link C_SetIscreenTitle}

@endnode

@node C_IscreenToBack "Intuition Extension 1.3b Command: Iscreen To Back"
@next C_IscreenToFront
@prev C_IscrTitleHeight

ISCREEN TO BACK
---------------

Iscreen To Back
Iscreen To Back n

Sends screen number n or the current screen to the back of all
Intuition screens.

See also: @{" Iscreen To Front " link C_IscreenToFront}

@endnode

@node C_IscreenToFront "Intuition Extension 1.3b Command: Iscreen To Front"
@next C_IscreenWidth
@prev C_IscreenToBack

ISCREEN TO FRONT
----------------

Iscreen To Front
Iscreen To Front n

Brings screen number n or the current screen to the front of all
Intuition screens.

See also: @{" Iscreen To Back " link C_IscreenToBack}

@endnode

@node C_IscreenWidth "Intuition Extension 1.3b Command: =Iscreen Width"
@next C_Ishift
@prev C_IscreenToBack

=ISCREEN WIDTH
--------------

w=Iscreen Width
w=Iscreen Width(n)

Returns the width of screen n or the current screen.

See also: @{"=Iscreen Height " link C_IscreenHeight}
	  @{"=Iscreen Colour " link C_IscreenColour}
	  @{"=Iscreen Mode   " link C_IscreenMode}

@endnode

@node C_Ishift "Intuition Extension 1.3b Command: =Ishift"
@next C_Itext
@prev C_IscreenWidth

=ISHIFT
-------

shiftstate=Ishift

Returns the keyboard shift state at the time of the last keypress.

See also: @{"=Iscan " link C_Iscan}

@endnode

@node C_Itext "Intuition Extension 1.3b Command: Itext"
@next C_ItextBase
@prev C_Ishift

ITEXT
-----

Itext x,y,s$

Writes text to the current screen/window at coordinates X,Y.  If
either coordinate is omitted, the current value of that coordinate is
used.

Note that the Y coordinate corresponds to the baseline of the font.
To determine this value, use the @{" Itext Base " link C_ItextBase} function.

The Itext instruction leaves the current graphics position at the
right edge of the text, on the baseline.

See also: @{" Set Ifont    " link C_SetIfont}
          @{" Ilocate Gr   " link C_Ilocate}
          @{"=Itext Length " link C_ItextLength}
          @{" Iwrite       " link C_Iwrite}

@endnode

@node C_ItextBase "Intuition Extension 1.3b Command: =Itext Base"
@next C_ItextLength
@prev C_Itext

=ITEXT BASE
-----------

y=Itext Base

Returns the baseline coordinate of the font for the current
screen/window.  Useful in conjunction with @{" Itext " link C_Itext}, for example:

	Itext 0,Itext Base,"Text at the top of the screen"

See also: @{" Set Ifont    " link C_SetIfont}
          @{"=Itext Length " link C_ItextLength}

@endnode

@node C_ItextLength "Intuition Extension 1.3b Command: =Itext Length
@next C_Itrap
@prev C_ItextBase

=ITEXT LENGTH
-------------

w=Itext Length(s$)

Returns the width in pixels of s$ using the current font.

See also: @{" Itext      " link C_Itext}
          @{"=Itext Base " link C_ItextBase}

@endnode

@node C_Itrap "Intuition Extension 1.3b Command: Itrap On/Off"
@next C_Iwait
@prev C_ItextLength

ITRAP ON
ITRAP OFF
---------

Itrap On
Itrap Off

Activates or deactivates error trapping for Intuition Extension
commands.  When the Itrap On instruction is executed, any commands
that cause errors will set an error flag rather than crashing the
program.  You can check this flag with the @{" Ierrtrap " link C_Ierrtrap} function.

The Itrap Off instruction returns the system to normal (i.e. errors
will cause the program to abort).

@endnode

@node C_Iwait "Intuition Extension 1.3b Command: Iwait"
@next C_IwaitEvent
@prev C_Itrap

IWAIT
-----

Iwait n

Waits for n vertical blanks before returning control to the program.
The length of time between vertical blanks depends on the type of
screen being used.  A standard PAL screen is 50 hertz, meaning that
vertical blank cycle is 1/50th of a second.  A standard NTSC screen is
60 hertz.

See also: @{" Iwait Key   " link C_IwaitKey}
          @{" Iwait Mouse " link C_IwaitMouse}
          @{" Iwait Vbl   " link C_IwaitVbl}
@endnode

@node C_IwaitEvent "Intuition Extension 1.3b Command: =Iwait Event"
@next C_IwaitKey
@prev C_Iwait

=IWAIT EVENT
------------

event=Iwait Event
event=Iwait Event Vbl

The Iwait Event function is used to wait for an event to occur.  With
the first form of the command, AMOS will wait for any kind of input to
occur (mouse click, keypress, menu selection, etc.) before returning;
the value returned is an "event value", and can be compared against
the values returned by the @{" Ievent " link C_IeventType} function to determine what event
occurred.

This method of "event waiting" is superior to repeatedly checking for
input in a loop, known as "busy waiting", because event waiting uses
no processor time at all - other programs can run at full speed while
your program is waiting for input.  Busy waiting, on the other hand,
takes up processor time because the program must keep checking whether
there is anything to do.

Nearly all programs that use input (which is most programs written)
can and should use event waiting.  Suppose you have a program that
accepts keyboard input and mouse clicks, and has menus.  Your main
loop might look something like:

	EVENT=Iwait Event
	If EVENT=Ievent Key
	   'A key was pressed
	Else If EVENT=Ievent Mouse
	   'The mouse button was clicked
	Else If EVENT=Ievent Menu
	   'A menu item was selected
	End If

The second form of the command is used in programs that need to
continuously update a display of some sort.  It waits for either an
input event or the vertical blank.  While there are commands that
allow you to wait until the next vertical blank, Iwait Event Vbl has
the advantage that it tells you whether any input happened before the
vertical blank occurred, which (again) saves processor time.

See also: @{"=Ievent Data " link C_IeventData}

@endnode

@node C_IwaitKey "Intuition Extension 1.3b Command: Iwait Key"
@next C_IwaitMouse
@prev C_Iwait

IWAIT KEY
---------

Iwait Key

Waits for a key to be pressed.

See also: @{"=Iget$       " link C_Iget} to read a key without waiting
	  @{"=Iread Char$ " link C_IreadChar} to wait for and read a key

@endnode

@node C_IwaitMouse "Intuition Extension 1.3b Command: Iwait Mouse"
@next C_IwaitVbl
@prev C_IwaitKey

IWAIT MOUSE
-----------

Iwait Mouse

Waits for a mouse click.

See also: @{"=Imouse Key " link C_ImouseKey}

@endnode

@node C_IwaitVbl "Intuition Extension 1.3b Command: Iwait Vbl"
@next C_GetIwindow
@prev C_IwaitMouse

IWAIT VBL
---------

Waits for the next vertical blank interrupt returning control to the
program.

See also: @{" Iwait " link C_Iwait}

@endnode

@node C_GetIwindow "Intuition Extension 1.3b Command: =Iwindow"
@next C_IwindowActivate
@prev C_IwaitVbl

=IWINDOW
--------

n=Iwindow

Returns the number of the current window.

See also: @{" Set Iwindow  " link C_SetIwindow}
	  @{" Iwindow Open " link C_IwindowOpen}
@endnode

@node C_IwindowActivate "Intuition Extension 1.3b Command: Iwindow Activate"
@next C_IwindowActive
@prev C_GetIwindow

IWINDOW ACTIVATE
----------------

Iwindow Activate n

Activates window number n for input and makes it the current output
window.  Use this function with discretion, as the user may not like
having his input suddenly going to your program when he wasn't
expecting it!  If you do use this command, it is also recommended to
do an @{" Iscreen To Front " link C_IscreenToFront} to inform the user of the new active window.

See also: @{" Set Iwindow " link C_SetIwindow}

@endnode

@node C_IwindowActive "Intuition Extension 1.3b Command: =Iwindow Active"
@next C_IwindowActiveBase
@prev C_IwindowActivate

=IWINDOW ACTIVE
---------------

result=Iwindow Active

If the currently active window (in the Intuition sense) is on the
current screen, this function returns True; otherwise, it returns
False.

@endnode

@node C_IwindowActiveBase "Intuition Extension 1.3b Command: =Iwindow Active Base"
@next C_IwindowActiveNum
@prev C_IwindowActive

=IWINDOW ACTIVE BASE
--------------------

adr=Iwindow Active Base

Returns the base address of the currently active Intuition window.

Note for system programmers: this simply gets and returns the value of
the ActiveWindow field of the IntuitionBase structure.

See also: @{"=Iwindow Base   " link C_IwindowBase}
	  @{"=Iwindow Active " link C_IWindowActive}
@endnode

@node C_IwindowActiveNum "Intuition Extension 1.3b Command: =Iwindow Active Num"
@next C_IwindowActual
@prev C_IwindowActiveBase

=IWINDOW ACTIVE NUM
-------------------

n=Iwindow Active Num

Returns the number of the currently active window.  WARNING: if the
currently active window is not on the current screen, the resultant
value is undefined!  So check beforehand whether it is using the
Iwindow Active function.

See also: @{"=Iwindow Active " link C_IwindowActive}

@endnode

@node C_IwindowActual "Intuition Extension 1.3b Command: =Iwindow Actual Width/Height"
@next C_IwindowBase
@prev C_IwindowActiveNum

=IWINDOW ACTUAL WIDTH
=IWINDOW ACTUAL HEIGHT
----------------------

w=Iwindow Actual Width
h=Iwindow Actual Height

Return the dimensions of the usable area of the current window.

Normally, all windows opened have a border which takes up part of the
window area.  (The base window of a screen is an exception to this
rule.)  All of the drawing operations start at the top-left corner of
the empty area of the window inside the border.  Because of this
border, you cannot use the width you gave in Iwindow Open as a measure
of the window's size, because that would cause your drawing operations
to flood over onto the window's right and bottom borders!  Instead,
use Iwindow Actual Width/Height to find out how much you can use.

@endnode

@node C_IwindowBase "Intuition Extension 1.3b Command: =Iwindow Base"
@next C_IwindowClose
@prev C_IwindowActual

=IWINDOW BASE
-------------

address=Iwindow Base

Returns the base address of the Intuition Window structure for the
current window.

@endnode

@node C_IwindowClose "Intuition Extension 1.3b Command: Iwindow Close"
@next C_IwindowCloseWB
@prev C_IwindowBase

IWINDOW CLOSE
-------------

Iwindow Close n

Closes window number n.  Note that window number 0 cannot be closed.

See also: @{" Iwindow Open     " link C_IwindowOpen}
	  @{" Iwindow Close Wb " link C_IwindowCloseWB}

@endnode

@node C_IwindowCloseWB "Intuition Extension 1.3b Command: Iwindow Close Wb"
@next C_IwindowHeight
@prev C_IWindowClose

IWINDOW CLOSE WB
----------------

Iwindow Close Wb n

Closes Workbench window number n.

See also: @{" Iwindow Open Wb " link C_IwindowOpenWB}

@endnode

@node C_IwindowHeight "Intuition Extension 1.3b Command: =Iwindow Height"
@next C_IwindowMove
@prev C_IwindowCloseWB

=IWINDOW HEIGHT
---------------

h=Iwindow Height
h=Iwindow Height(n)
h=Iwindow Height Wb(n)

Returns the height of the current window, or of window number n.  If
n is 0, or n is omitted and the current window is window 0 (the
screen's main window), the screen's height is returned, as if
@{" Iscreen Height " link C_IscreenHeight} had been called.

See also: @{" Iwindow Size  " link C_IwindowSize}
	  @{"=Iwindow Width " link C_IwindowWidth}

@endnode

@node C_IwindowMove "Intuition Extension 1.3b Command: Iwindow Move"
@next C_IwindowOnWB
@prev C_IwindowHeight

IWINDOW MOVE
------------

Iwindow Move n,x,y
Iwindow Move Wb n,x,y

Moves window number n to coordinates (x,y).  If either coordinate
would result in the window being partly or fully off the screen, an
"Illegal function call" error is generated.

See also: @{"=Iwindow X " link C_IwindowX}
	  @{"=Iwindow Y " link C_IwindowY}

@endnode

@node C_IwindowOnWB "Intuition Extension 1.3b Command: =Iwindow On Wb"
@next C_IwindowOpen
@prev C_IwindowMove

IWINDOW ON WB
-------------

wb=Iwindow On Wb

Returns True if the current window is a Workbench window, False
otherwise.

@endnode

@node C_IwindowOpen "Intuition Extension 1.3b Command: Iwindow Open"
@next C_IwindowOpenWB
@prev C_IwindowOnWB

IWINDOW OPEN
------------

Iwindow Open n,x,y,w,h [,title$ [,flags]]

Opens an Intuition window.  The window is designated with the number n
given in the command.  Only one window with a particular number may
be open on a screen at a time, but different screens may have same-
numbered windows.  In other words, the code

Iscreen Open 0,320,200,2,0
Iwindow Open 1,0,0,320,200
Iscreen Open 1,320,200,2,0
Iwindow Open 1,20,20,200,80

will open two different windows on two different screens, both
numbered 1.

If window n already exists, the "Window not closed" error is
generated.

The x and y parameters tell AMOS where the top left corner of the
window should be, while w and h indicate the size of the new window.
Both corners must be on the screen.  In addition, the width and height
of the window must be at least 80 x 48 pixels, and cannot be larger
than the currently visible size of the screen.

If title$ is given, it is used as the title of the new window, and is
displayed in the window's title bar.  If title$ is omitted, the title
bar remains blank.

If the flags parameter is specified, it determines how the window is
set up.  To determine what value to use, add the appropriate values
from this list together:

	Item			 Value:	 Dec.	 Hex
	----				-----   -----
	Sizing gadget			    1	$0001
	Draggable window		    2	$0002
	Depth gadget(s)			    4	$0004
	Close gadget			    8	$0008
	*Sizing gadget in right border	   16	$0010
	*Sizing gadget in bottom border	   32	$0020
	+Backdrop window		  256	$0100
	Borderless window		 2048	$0800
	Activate on open		 4096	$1000

Notes:	* These flags determine whether the right or bottom borders are
	  expanded to accommodate the sizing gadget.

	+ A backdrop window always stays in back of all other windows.
	  The "backdrop window" flag cannot be used with any other
	  flags.

So, for example, to open a draggable window with only a close gadget,
the value of flags would be 10.

After the window has been opened, it can be moved, sized, and depth-
arranged using the standard Intuition gadgets, as well as with the
Intuition Extension commands designed for that purpose.  (The close
gadget does not immediately close the window, but rather sets a status
flag that the program can check and take whatever action is
appropriate, e.g. quitting the program.)

Note that window number 0 is reserved for the default window that is
opened at the same time a screen is opened; any attempt to reopen,
move, size, depth-arrange, or close this window will result in an
error.

See also: @{" Iwindow Close    " link C_IwindowClose}
	  @{"=Iwindow          " link C_GetIwindow}
	  @{" Set Iwindow      " link C_SetIwindow}
	  @{" Iwindow Move     " link C_IwindowMove}
	  @{" Iwindow Size     " link C_IwindowSize}
	  @{" Iwindow To Front " link C_IwindowToFront}
	  @{" Iwindow To Back  " link C_IwindowToBack}
	  @{"=Iwindow Status   " link C_IwindowStatus}

@endnode

@node C_IwindowOpenWB "Intuition Extension 1.3b Command: Iwindow Open Wb"
@next C_IwindowSize
@prev C_IwindowOpen

IWINDOW OPEN WB
---------------

Iwindow Open Wb n,x,y,w,h [,title$ [,flags]]

Opens an Intuition window.  Similar to Iwindow Open, but opens the
window on the Workbench screen.  If the Workbench screen is closed and
cannot be opened (e.g. low memory), an error is generated.  Note that
window number 0 *is* a valid number for a Workbench window.

See also: @{" Iwindow Open     " link C_IwindowOpen}
	  @{" Iwindow Close Wb " link C_IwindowCloseWB}

@endnode

@node C_IwindowSize "Intuition Extension 1.3b Command: Iwindow Size"
@next C_IwindowStatus
@prev C_IwindowOpenWB

IWINDOW SIZE
------------

Iwindow Size n,w,h
Iwindow Size Wb n,w,h

Resizes window n to dimensions w by h.  If this is less than 80 x 48
or would extend beynd the bottom right corner of the currently visible
part of the screen, an error is generated.

See also: @{"=Iwindow Width  " link C_IwindowWidth}
	  @{"=Iwindow Height " link C_IwindowHeight}

@endnode

@node C_IwindowStatus "Intuition Extension 1.3b Command: =Iwindow Status"
@next C_IwindowToBack
@prev C_IwindowSize

=IWINDOW STATUS
---------------

status=Iwindow Status
status=Iwindow Status(n)
status=Iwindow Status Wb(n)

Returns an integer representing the current status of the current
window (or window number n, either on the current screen or on the
Workbench screen).  At present, only one bit is defined:

	Bit 1: Indicates whether the window's close gadget was
		 pressed.

However, due to a bug in AMOS (at least in AMOS Pro), the following
code to check whether a window's close gadget was pressed will not
work:

If Btst(1,Iwindow Status(N))
  Iwindow Close N
End If

Instead, you must use

ST=Iwindow Status(N)
If Btst(1,ST)
  Iwindow Close N
End If

@endnode

@node C_IwindowToBack "Intuition Extension 1.3b Command: Iwindow To Back"
@next C_IwindowToFront
@prev C_IwindowStatus

IWINDOW TO BACK
---------------

Iwindow To Back
Iwindow To Back n
Iwindow To Back Wb n

Sends window number n (or the current window) to the back.

See also: @{" Iwindow To Front " link C_IwindowToFront}

@endnode

@node C_IwindowToFront "Intuition Extension 1.3b Command: Iwindow To Front"
@next C_IwindowWidth
@prev C_IwindowToBack

IWINDOW TO FRONT
----------------

Iwindow To Front
Iwindow To Front n
Iwindow To Front Wb n

Brings window number n (or the current window) to the front.

See also: @{" Iwindow To Back " link C_IwindowToBack}

@endnode

@node C_IwindowWidth "Intuition Extension 1.3b Command: =Iwindow Width"
@next C_IwindowX
@prev C_IwindowToFront

=IWINDOW WIDTH
--------------

w=Iwindow Width
w=Iwindow Width(n)
w=Iwindow Width Wb(n)

Returns the width of the current window, or of window number n.  If n
is 0, or n is omitted and the current window is window 0 (the screen's
main window), the screen's width is returned, as if @{" Iscreen Width " link C_IscreenWidth} had
been called.

See also: @{" Iwindow Size   " link C_IwindowMove}
	  @{"=Iwindow Height " link C_IwindowHeight}
@endnode

@node C_IwindowX "Intuition Extension 1.3b Command: =Iwindow X"
@next C_IwindowY
@prev C_IwindowWidth

=IWINDOW X
----------

x=Iwindow X
x=Iwindow X(n)
x=Iwindow X Wb(n)

Returns the X coordinate of the upper left corner of the current
window, or of window number n.  If n is 0, or if n is omitted and the
current window is window 0 (the screen's main window), 0 is returned.

See also: @{" Iwindow Move " link C_IwindowMove}
	  @{"=Iwindow Y    " link C_IwindowY}

@endnode

@node C_IwindowY "Intuition Extension 1.3b Command: =Iwindow Y"
@next C_Iwrite
@prev C_IwindowX

=IWINDOW Y
----------

y=Iwindow Y
y=Iwindow Y(n)
y=Iwindow Y Wb(n)

Returns the Y coordinate of the upper left corner of the current
window, or of window number n.  If n is 0, or if n is omitted and the
current window is window 0 (the screen's main window), 0 is returned.

See also: @{" Iwindow Move " link C_IwindowMove}
	  @{"=Iwindow X    " link C_IwindowX}

@endnode

@node C_Iwrite "Intuition Extension 1.3b Command: Iwrite"
@next C_Ixgr
@prev C_IwindowY

IWRITE
------

Iwrite
Iwrite s$

Prints a string to the screen, then moves the graphics cursor to the
start of the next line.  Similar to Print, but only accepts a single
string argument, due to the limitations of extensions.  Without the
argument, it just goes to the next line, like Print without any
parameters.

See also: @{" Ilocate " link C_Ilocate}
          @{" Itext   " link C_Itext}

@endnode

@node C_Ixgr "Intuition Extension 1.3b Command: =Ixgr"
@next C_Iygr
@prev C_Iwrite

=IXGR
-----

x=Ixgr

Returns the current X coordinate of the graphics cursor.

See also: @{" Ilocate Gr " link C_IlocateGr}
          @{"=Iygr       " link C_Iygr}

@endnode

@node C_Iygr "Intuition Extension 1.3b Command: =Iygr"
@next C_ReqtoolsHere
@prev C_Ixgr

=IYGR
-----

y=Iygr

Returns the current Y coordinate of the graphics cursor.

See also: @{" Ilocate Gr " link C_IlocateGr}
          @{"=Ixgr       " link C_Ixgr}

@endnode

@node C_ReqtoolsHere "Intuition Extension 1.3b Command: =Reqtools Here"
@next C_ReserveIgadget
@prev C_Iygr

=REQTOOLS HERE
--------------

res=Reqtools Here

Returns whether ReqTools.library is installed in the system.  This
function can be used to determine whether to use requesters or an
alternate method of input.

@endnode

@node C_ReserveIgadget "Intuition Extension 1.3b Command: Reserve Igadget"
@next C_SetIcolour
@prev C_ReqtoolsHere

RESERVE IGADGET
---------------

Reserve Igadget
Reserve Igadget n

Allocates space for gadgets in the current window.  If the parameter
n is given, space is reserved for that many gadgets; if it is omitted,
the memory is freed and returned to the system.  There is no limit to
the number of gadgets you can reserve, apart from the amount of memory
in your system.

Note that issuing the Reserve Igadget command, with or without a
parameter, clears any previous gadget definitions for the current
window.

@endnode

@node C_SetIcolour "Intuition Extension 1.3b Command: Set Icolour"
@next C_SetIfont
@prev C_ReserveIgadget

SET ICOLOUR
-----------

Set Icolour n,c

Sets colour n on the current screen to c, a value in the format
$RGB.  So to set

See also: @{" Ipalette " link C_Ipalette}
	  @{"=Icolour  " link C_GetIcolour}

@endnode

@node C_SetIfont "Intuition Extension 1.3b Command: Set Ifont"
@next C_SetIgadHit
@prev C_SetIcolour

SET IFONT
---------

Set Ifont name$,size
Set Ifont namesize$

Sets the font for the current screen/window.  In the first format,
name$ is the name of the font you want to use; this may or may not
include the ".font" extension, but if it does, it (the ".font") MUST
be in lower case.  Size is the vertical size of the font.

In the second format, namesize$ is a string of the form
"fontname/NNN", where "fontname" is the name of the font and NNN is
the size.  This is useful in conjunction with @{" Irequest Font " link C_IrequestFont}.

See also: @{"=Ifont$     " link C_IfontName}

@endnode

@node C_SetIgadHit "Intuition Extension 1.3b Command: Set Igadget Hit"
@next C_SetIgadInt
@prev C_SetIfont

SET IGADGET HIT
---------------

Set Igadget Hit n,x,y,w,h

Defines a "hit-select" gadget - in other words, a gadget that stays
down only as long as the mouse button is held down.  If the mouse
button is released over the gadget, a "hit" is reported.  This kind of
gadget is probably the most common; it can be seen in any Intuition
window or screen - the close gadget, zoom gadget (in Workbench 2.0),
and depth gadget(s) are all hit-select gadgets.  (The sizing gadget in
the lower right corner of a window is also a hit-select gadget, as is
the entire title-bar, although Intuition gives them special handling.)

N is the number of the gadget to define; x, y, w, and h define the
gadget's position and size.

A hit-select gadget must be at least 4 pixels wide and 4 pixels tall.

See also: @{" Reserve Igadget     " link C_ReserveIgadget}
	  @{" Set Igadget Hslider " link C_SetIgadSlider}
	  @{" Set Igadget Int     " link C_SetIgadInt}
	  @{" Set Igadget String  " link C_SetIgadString}
	  @{" Set Igadget Toggle  " link C_SetIgadToggle}
	  @{" Set Igadget Vslider " link C_SetIgadSlider}

@endnode

@node C_SetIgadInt "Intuition Extension 1.3b Command: Set Igadget Int"
@next C_SetIgadSlider
@prev C_SetIgadHit

SET IGADGET INT
---------------

Set Igadget Int n,x,y,w,h
Set Igadget Int n,x,y,w,h,init
Set Igadget Int n,x,y,w,h,init,strpos

Defines an integer gadget.  N is the number of the gadget to define;
x, y, w, and h define the gadget's position and size.  Init sets the
initial value for the gadget; if omitted, the inital value is 0.
Strpos determines how the integer is displayed in the gadget: 0 means
left-justified (the default), 1 means centred, and 2 means right-
justified.  Any other value will result in an "Illegal function call"
error.

An integer gadget must be at least 32 pixels wide and two more than the
current font height tall.  If you omit the height parameter, the
gadget will automatically be set to this height.

See also: @{" Reserve Igadget     " link C_ReserveIgadget}
	  @{" Set Igadget Hit     " link C_SetIgadToggle}
	  @{" Set Igadget Hslider " link C_SetIgadSlider}
	  @{" Set Igadget String  " link C_SetIgadString}
	  @{" Set Igadget Toggle  " link C_SetIgadToggle}
	  @{" Set Igadget Vslider " link C_SetIgadSlider}

@endnode

@node C_SetIgadSlider "Intuition Extension 1.3b Command: Set Igadget Hslider/Vslider"
@next C_SetIgadString
@prev C_SetIgadInt

SET IGADGET HSLIDER
SET IGADGET VSLIDER
-------------------

Set Igadget Hslider n,x,y,w,h,units,pos,size,overlap
Set Igadget Vslider n,x,y,w,h,units,pos,size,overlap

Defines a slider gadget.  N is the number of the gadget to define;
x, y, w, and h define the gadget's position and size.  Units is the
total number of units the slider represents (e.g. the number of lines
in a text file).  Pos is the initial position of the slider and size
is its size, both measured in units.

Overlap is best defined using an example:  If a vertical slider bar
represents a text file, then the slider represents the portion of the
file that is visible.  When the user clicks in the slider bar but not
on the slider, the text will scroll to display the next screen up or
down - but may also leave one of the old lines on the screen to remind
the user of where he is.  In this case, the value of "overlap" would
be 1, since there is a one-line overlap between screens.

For "level" type controls, such as volume or colour intensity, always
set size to 1 and overlap to 0.

A horizontal gadget must be at least 16 pixels wide and 8 pixels tall;
a vertical gadget must be at least 10 pixels wide and 16 pixels tall.

Note that the slider bar is also called the "container", since it
contains the slider.

See also: @{" Reserve Igadget    " link C_ReserveIgadget}
	  @{" Set Igadget Hit    " link C_SetIgadToggle}
	  @{" Set Igadget Int    " link C_SetIgadInt}
	  @{" Set Igadget String " link C_SetIgadString}
	  @{" Set Igadget Toggle " link C_SetIgadToggle}

@endnode

@node C_SetIgadString "Intuition Extension 1.3b Command: Set Igadget String"
@next C_SetIgadToggle
@prev C_SetIgadSlider

SET IGADGET STRING
------------------

Set Igadget String n,x,y,w,h,maxlen
Set Igadget String n,x,y,w,h,maxlen,init$
Set Igadget String n,x,y,w,h,maxlen,init$,strpos

Defines a string gadget.  N is the number of the gadget to define;
x, y, w, and h define the gadget's position and size.  Maxlen is the
maximum length of the string; if the user tries to enter a string
longer than this length, it will not be accepted.  Init$ allows you
to change the initial value from the default of the empty string.
Strpos determines how the integer is displayed in the gadget: 0 means
left-justified (the default), 1 means centred, and 2 means right-
justified.  Any other value will result in an "Illegal function call"
error.

A string gadget must be at least 32 pixels wide and two more than the
current font height tall.  If you omit the height parameter, the
gadget will automatically be set to this height.

See also: @{" Reserve Igadget     " link C_ReserveIgadget}
	  @{" Set Igadget Hit     " link C_SetIgadToggle}
	  @{" Set Igadget Hslider " link C_SetIgadSlider}
	  @{" Set Igadget Int     " link C_SetIgadInt}
	  @{" Set Igadget Toggle  " link C_SetIgadToggle}
	  @{" Set Igadget Vslider " link C_SetIgadSlider}

@endnode

@node C_SetIgadToggle "Intuition Extension 1.3b Command: Set Igadget Toggle"
@next C_SetIgadValue
@prev C_SetIgadString

SET IGADGET TOGGLE
------------------

Set Igadget Toggle n,x,y,w,h
Set Igadget Toggle n,x,y,w,h,init

Defines a toggle gadget.  N is the number of the gadget to define;
x, y, w, and h define the gadget's position and size.  Init defines
the initial state of the gadget: False puts the gadget in an "off"
(unselected) state, while True puts it in an "on" (selected) state.
The default is off.

A toggle gadget must be at least 4 pixels wide and 4 pixels tall.

See also: @{" Reserve Igadget     " link C_ReserveIgadget}
	  @{" Set Igadget Hit     " link C_SetIgadToggle}
	  @{" Set Igadget Hslider " link C_SetIgadSlider}
	  @{" Set Igadget Int     " link C_SetIgadInt}
	  @{" Set Igadget String  " link C_SetIgadString}
	  @{" Set Igadget Vslider " link C_SetIgadSlider}

@endnode

@node C_SetIgadValue
@next C_SetImenu
@prev C_SetIgadToggle

SET IGADGET VALUE
SET IGADGET VALUE$
------------------

Set Igadget Value n,value
Set Igadget Value$ n,value$

Changes the value of an existing gadget.  N is the number of the
gadget whose value you want to change; the value parameter is
interpreted according to the type of the gadget, as follows:

    Toggle gadget - On (non-zero value) or off (zero)
    Slider	  - Position of the slider, in the units specified
			when the gadget was created
    Integer       - The new value of the gadget
    String        - The new string to put into the gadget

If you try to modify a hit-select gadget, an Illegal Function Call
error will be generated.

@endnode

@node C_SetImenu "Intuition Extension 1.3b Command: Set Imenu"
@next C_SetIpens
@prev C_SetIgadValue

SET IMENU
---------

Set Imenu s$,menu [,item [,sub]]

Defines a menu, item, or subitem.  Menu is the menu number; it can
range from 1 to 31.  Item, the item number, can be 1-63, and sub, the
subitem number, can be 1-31.

A menu is a set of options that the user can select to control the
actions of a program.  A menu can contain zero or more items -
although a menu with zero items is not very useful! - which are drawn
underneath the menu when it is selected; that is, when the user
presses the right mouse button and moves the pointer over the menu
name.  Each of those items can have zero or more subitems.  If a menu
item has subitems, then when the user places the pointer over the menu
item, the list of subitems appears to the right of the menu item.

By checking which menu item the user has selected (see the @{"=Ichoice " link C_Ichoice}
function), you can act appropriately; for example, when the user
chooses the "Quit" function, your program would close down and exit.

Set Imenu creates or removes a menu, item, or subitem, depending on
how many of menu, item, and sub you pass to Set Imenu.  When a menu is
initially created, it contains no items; a newly-created item contains
no subitems.  The menu's or item's string is set to s$.  If s$ is
empty, the appropriate menu/item (along with all subitems) is deleted.
An out-of-range value will cause an Illegal Function Call error; a
value of 0 is equivalent to omitting the parameter.  If any parameter
is included (and non-zero), all the parameters before it must also be
included and non-zero.  So calling Set Imenu s$,1,0,2 will result in
an error.

In order for the user to be able to use the menus you have created,
you will need to use the @{" Imenu On " link C_ImenuOnOff} instruction.  Once menus are
activated, you cannot make any changes without first deactivating them
(with @{" Imenu Off " link C_ImenuOnOff}).

@endnode

@node C_SetIpens "Intuition Extension 1.3b Command: Set Ipens"
@next C_SetIscreen
@prev C_SetImenu

SET IPENS
---------

Set Ipens highlight,shadow

Sets the pen numbers used in drawing gadget borders.  The highlight
pen is used to draw the light part of the border of a toggle or hit-
select gadget (the left and top borders when the gadget is not
selected); the shadow pen is used to draw the dark part of the border
(the right and bottom borders).  The shadow pen is also used to draw
the borders for string and integer gadgets and sliders.

@endnode

@node C_SetIscreen "Intuition Extension 1.3b Command: Set Iscreen"
@next C_SetIscreenTitle
@prev C_SetIpens

SET ISCREEN
-----------

Set Iscreen n

Sets the current screen to screen number N.

See also: @{"=Iscreen " link C_GetIscreen}

@endnode

@node C_SetIscreenTitle "Intuition Extension 1.3b Command: Set Iscreen Title"
@next C_SetIscreen
@prev C_SetIwindow

SET ISCREEN TITLE
-----------------

Set Iscreen Title s$ [,n]

Sets the title of the current screen (or screen number n) to s$.  This
title is used if the active window has not defined its own title for
the screen.

See also: @{" Set Iwindow Title    " link C_SetIwindowTitle }
          @{"=Iscreen Title Height " link C_IscrTitleHeight }

@endnode

@node C_SetIwindow "Intuition Extension 1.3b Command: Set Iwindow"
@next C_SetIwindowTitle
@prev C_SetIscreenTitle

SET IWINDOW
-----------

Set Iwindow n

Sets the current window to window number n on the current screen.

See also: @{"=Iwindow        " link C_GetIwindow}
	  @{" Set Iwindow Wb " link C_SetIwindowWB}

@endnode

@node C_SetIwindowTitle "Intuition Extension 1.3b Command: Set Iwindow Title"
@next C_SetIwindowWB
@prev C_SetIwindow

SET IWINDOW TITLE
-----------------

Set Iwindow Title [n],[window$],[screen$]

Sets the window and screen titles of window number n (or, if n is
omitted, the current window) to window$ and screen$, respectively.  If
either is omitted, the corresponding title string is unchanged.  The
window title is displayed in the title bar; the screen title is
shown in the screen title bar whenever the window is active.

@endnode

@node C_SetIwindowWB "Intuition Extension 1.3b Command: Set Iwindow Wb"
@next C_Superhires
@prev C_SetIwindowTitle

SET IWINDOW WB
--------------

Set Iwindow Wb n

Sets the current window to window number n on the Workbench screen.

See also: @{"=Iwindow       " link C_GetIwindow}
	  @{"=Iwindow On Wb " link C_IwindowOnWB}
	  @{" Set Iwindow   " link C_SetIwindowWB}

@endnode

@node C_Superhires "Intuition Extension 1.3b Command: =Superhires"
@next C_XHardMin
@prev C_SetIwindowWB

=SUPERHIRES
-----------

x=Superhires

Returns the screen mode value for the SuperHires mode.

See also: @{" Ehb " link C_Ehb}
	  @{" Ham " link C_Ham}

@endnode

@node C_XHardMin "Intuition Extension 1.3b Command: =X Hard Min"
@next C_XIhard
@prev C_Superhires

=X HARD MIN
-----------

x=X Hard Min

Returns the minimum X hardware coordinate on the Intuition display.

See also: @{"=Y Hard Min " link C_YHardMin}

@endnode

@node C_XIhard "Intuition Extension 1.3b Command: =X Ihard"
@next C_XIscreen
@prev C_XHardMin

=X IHARD
--------

x2=X Ihard(x1)

Converts screen X coordinate x1 to hardware X coordinate x2.

See also: @{"=Y Ihard   " link C_YIhard}
	  @{"=X Iscreen " link C_XIscreen}
	  @{"=Y Iscreen " link C_YIscreen}

@endnode

@node C_XIscreen "Intuition Extension 1.3b Command: =X Iscreen"
@next C_YHardMin
@prev C_XIhard

=X ISCREEN
----------

x2=X Iscreen(x1)

Converts hardware X coordinate x1 to screen X coordinate x2.

See also: @{"=X Ihard   " link C_XIhard}
	  @{"=Y Ihard   " link C_YIhard}
	  @{"=Y Iscreen " link C_YIscreen}

@endnode

@node C_YHardMin "Intuition Extension 1.3b Command: =Y Hard Min"
@next C_YIhard
@prev C_XIscreen

=Y HARD MIN
-----------

y=Y Hard Min

Returns the minimum Y hardware coordinate on the Intuition display.

See also: @{"=X Hard Min " link C_XHardMin}

@endnode

@node C_YIhard "Intuition Extension 1.3b Command: =Y Ihard"
@next C_YIscreen
@prev C_YHardMin

=Y IHARD
--------

y2=Y Ihard(y1)

Converts screen Y coordinate y1 to hardware Y coordinate y2.

See also: @{"=X Ihard   " link C_YIhard}
	  @{"=X Iscreen " link C_XIscreen}
	  @{"=Y Iscreen " link C_YIscreen}

@endnode

@node C_YIscreen "Intuition Extension 1.3b Command: =Y Iscreen"
@prev C_YIhard

=Y ISCREEN
----------

y2=Y Iscreen(y1)

Converts hardware Y coordinate y1 to screen Y coordinate y2.

See also: @{"=X Ihard   " link C_XIhard}
	  @{"=Y Ihard   " link C_YIhard}
	  @{"=X Iscreen " link C_XIscreen}

@endnode
