amiga-request@abcfd20.larc.nasa.gov (Amiga Sources/Binaries Moderator) (09/29/90)
Submitted-by: Paul-Erik Raue <peraue@cs.vu.nl>
Posting-number: Volume 90, Issue 261
Archive-name: libraries/reqlib-1.2/part03
#!/bin/sh
# This is a shell archive. Remove anything before this line, then unpack
# it by saving it into a file and typing "sh file". To overwrite existing
# files, type "sh file -c". You can also feed this as standard input via
# unshar, or by typing "sh <file", e.g.. If this archive is complete, you
# will see the following message at the end:
# "End of archive 3 (of 3)."
# Contents: req.doc
# Wrapped by tadguy@abcfd20 on Fri Sep 28 14:45:31 1990
PATH=/bin:/usr/bin:/usr/ucb ; export PATH
if test -f 'req.doc' -a "${1}" != "-c" ; then
echo shar: Will not clobber existing file \"'req.doc'\"
else
echo shar: Extracting \"'req.doc'\" \(60498 characters\)
sed "s/^X//" >'req.doc' <<'END_OF_FILE'
X
X The req.library is a run time re-entrant library that is designed
Xto make it easier for programmers to use powerful, easy to use
Xrequesters for communicating with users. The requester library
Xincludes such functions as a color requester, file requester, message
Xdisplay requester and many functions to make the creation of gadgets
Xfor your own custom requesters easier.
X
X Req.library was written by Colin Fox (of Pyramyd Designs) and
XBruce Dawson (of CygnusSoft Software). Req.library is a freely
Xdistributable library that may be used in commercial products without
Xpaying any royalties. We encourage you to use the requester library
Xin all of your programs, to make them easier to write, and to use.
X
X Req.library is not public domain. The requester library and all
Xdocumentation and example programs are all copyright 1989.
X
X The requester library must be distributed with the documentation
Xfile (req.doc), and the three include files (req.h, reqbase.h and
Xreqbase.i).
X
X
X
X Req.library is dedicated to the programmers who make the Amiga
Xshine the way it was meant to.
X
X
XOverView:
X
X All of the req.library functions that bring up requesters allow
Xyou two ways of specifying what screen you would like the requester to
Xappear on. The first way is the more efficient way, because you only
Xhave to set it up once and then it takes care of things automatially.
XThere is a field in all process structures called the pr_WindowPtr.
XThis pointer is used by DOS to decide where to put it's requesters.
XIf pr_WindowPtr contains a zero, requesters go on the workbench
Xscreen. If it contains the address of a window, then requesters go on
Xthat window's screen. If it contains a negative one, then no DOS
Xrequesters come up. The req.library requesters all use this variable,
Xif they are called from a process . However, if the pointer is -1,
Xthe req.library functions do still appear, on the workbench screen.
X
X The second way was put in mainly so that the requesters can be
Xcalled from tasks. Since a task does not have a process structure, it
Xalso lacks a pr_WindowPtr. Therefore, all of the requester functions
Xwhich can be used from a task (currently everything except the file
Xrequester) can be passed a window pointer, either as a parameter or as
Xan element in a structure. Important: This pointer takes precedence
Xover the pr_WindowPtr so if you wish the requesters to use the
Xpr_WindowPtr you must zero the window fields that the routines are
Xexpecting. In the case of fields in a structure this can be easy as
Xlong as you make sure your structure defaults to being zero
Xeverywhere.
X
X Setting the pr_WindowPtr is quite a simple matter. All you have
Xto do is do a FindTask((char *)0); which returns a pointer to your own
Xtask and your own process (a task structure is the first element of a
Xprocess structure). Then you simply preserve the old value of
Xpr_WindowPtr (VERY IMPORTANT!!!) and put a window pointer into it.
X
Xeg:
X /* Find my task. */
X myprocess = (struct Process *)FindTask((char *)0);
X oldwindowptr = myprocess->pr_WindowPtr;
X myprocess->pr_WindowPtr = window;
X
Xor:
X
X MOVE.L 4,A6
X MOVE.L #0,A1
X SYS FindTask ;Find my task.
X MOVE.L D0,_myprocess
X MOVE.L D0,A0
X MOVE.L pr_WindowPtr(A0),_oldwindowptr
X MOVE.L _window,pr_WindowPtr(A0)
X
X Before your program exits it is VERY important that it restore the
Xprevious value of pr_WindowPtr. If you don't, then your program will
Xwork in some situations, but will BLOW UP in others. For example, if
Xyou execute (without using the 'run' command) a program, which then
Xsets the pr_WindowPtr to point at one of its windows and the exits
Xwithout restoring it, then the next time a DOS requester tries to
Xappear... BOOM! The machine will probably crash as DOS tries to open
Xa requester on a now closed screen. Therefore, before leaving:
X
X myprocess->pr_WindowPtr = oldwindowptr;
X
Xor:
X
X MOVE.L _myprocess,A0
X MOVE.L _oldwindowptr,pr_WindowPtr(A0)
X
X
X
X One final note. The pr_WindowPtr field exists in the process
Xstructure. This means that a task does not have this field.
XTherefore, if you want to call one of the requester library functions
Xfrom a task, you will not be able to specify what screen you would
Xlike the requester to appear on by setting the pr_WindowPtr field.
XAll of the functions that open requesters and can be called from a
Xtask (the file requester/font requester is the only one that can't be
Xcalled froma task) have some other way of specifying which screen you
Xwould like them to open on. They will have either have a field in the
Xstructure which you must pass them or a parameter which can contain a
Xwindow pointer to one of the windows on your custom screen. If this
Xpointer is non-zero then it overrides the pr_WindowPtr field.
X
X
X
X
X By opening the requester library, you not only gain access to all
Xof the functions documented below, but to some other goodies as well.
XReq.library needs and therefore opens several other libraries,
Xincluding dos.library, intuition.library, graphics.library and the
Xconsole device. All of these pointers are stored in the ReqLib
Xstructure which you get a pointer to when you open the req.library.
XTherefore, you can save yourself a little bit of code by grabbing
Xthese fields after opening the requester library. The only thing to
Xbeware of is don't use these values after you have close the requester
Xlibrary, because at that point there is no guarantee that they will
Xstill be valid.
X
X In addition to these libraries, the Images pointer in the req
Xlibrary structure points to a set of ten small images (four arrows and
Xssix letters) which have are guaranteed to be in chip memory. These
Xcan be used if your program requires this type of images.
X
X
X
X
X One thing to keep in mind when using the gadget creation routines
Xis that there isn't any way for us to check that you have passed us a
Xpointer to the correct size of buffer, so you _must_ make sure that
Xyou are allocating the right amount of memory.
X
X
X--------------------------------------------------------------
XHere's a quick list of the functions available:
X--------------------------------------------------------------
X
XCenter..................Center a new window over the mouse.
X
XSetSize.................Prop gadget handling routines (32 bit)
XSetLocation
XReadLocation
X
XFormat..................sprintf() format routine
X
XSimpleRequest...........Starter gluecode to TextRequest- Single gadget
XTwoGadRequest...........Starter gluecode to TextRequest- Two gadgets
X
XFileRequester...........FileRequester routines
XPurgeFiles
X
XColorRequester..........a colorrequester
X
XMakeGadget..............Gadget creation routines
XMakeString
XMakeProp
XMakeButton
X
XMakeScrollBar...........3 part gadget; 2 arrows and a prop.
X Horizontal or Vertical
X
XLinkGadget..............Gadget creation routines that self-hook into
X the newwindow
XLinkStringGadget........gadget list.
XLinkPropGadget
X
XDrawBox.................Draw a box (x1y1)(x2y2) in one command
X
XGetFontHeightAndWidth...return height and width of current font
X
XRealTimeScroll..........scroll routine used in file requester
X
XTextRequest.............Powerful requester function
X
XGetString...............Get a line of text from the user
XGetLong.................Get a signed long from the user
X
XRawKeyToAscii...........Convert raw key to ascii
X
X----------------------------------------------------------------
X
X
XNAME
X Center
X
X
XSYNOPSIS
X Center( &nw, x, y)
X A0 D0 D1
X
Xstruct NewWindow *nw;
XUSHORT x,y;
X
XDESCRIPTION
X
X Center() is used to adjust a NewWindow structure so that the
Xwindow that it opens will appear immediately under the mouse. The x,y
Xvalues are used to specify which part of the window you would like to
Xappear underneath the mouse. If x or y is zero, that tells Center()
Xto position the window so that the window center (in the x or y
Xdirection respectively) is underneath the mouse. If x or y is
Xpositive, that tells Center() to position the window so that the mouse
Xis that many pixels from the left or top edge of the window
Xrespectively. If x or y is negative, that tells Center() to position
Xthe window structure so that the mouse appears that many pixels from
Xthe right or bottom edge of the window respectively (ie; x = -10 tells
XCenter to position the mouse ten pixels to the left of the right
Xedge).
X
X If it is impossible to position the window exactly where requested
X(if the mouse pointer is too close to the edge of the screen) then
Xthis routine will position the window as close as possible to the
Xcorrect location.
X
X To allow this routine to work accurately it is necessary to have
Xalready initialized the new window structure to specify on what screen
Xthe window is going to be open. ie; you should set the Type and
XScreen fields before calling Center().
X
X This routine disturbs no registers.
X
XRETURNS
X nothing
XSEE
X
XBUGS
X None known
X
X
X;--------------------------------------------------------------------
X
XNAME
X SetSize
XSYNOPSIS
X
X SizeVal=SetSize(MaxValue,ViewSize)
X D0.W D0.L D1.L
X
Xshort SizeVal;
Xlong MaxValue,ViewSize;
X
XDESCRIPTION
X
X This routine is designed to correctly handle sizing a prop gadget
Xto a range. The range is given in in MaxValue/ViewSize. MaxValue is
Xthe maximum value that this prop is supposed to be able to represent.
XViewsize is how large the display area is. For instance, if your
Xmaximum value was 200 (files, for example), and your viewsize was 15
X(lines of text), then you would call this as so:
X
X SizeVal=SetSize(200,15);
X
X Then you would put SizeVal into the appropriate PropInfo structure
Xelement (in the case of the file requester, that would be VertBody).
X
XRETURNS
X The 16 bit value to be put into the PropInfo structure of the
Xprop gadget.
X
XSEE
X SetLocation, ReadLocation
XBUGS
X Bugs? what bugs?
X
X
X;--------------------------------------------------------------------
X
XNAME
X SetLocation
XSYNOPSIS
X
XNewLoc = SetLocation(MaxValue,ViewSize,Value);
X D0 D0 D1 D2
X
Xshort NewLoc;
Xlong MaxValue,ViewSize,Value;
X
XDESCRIPTION
X
X When you have a prop gadget that you wish to directly set,
Xthen this is the routine to use. It allows you to pass any 32 bit
Xvalue and properly set the gadget.
X
XRETURNS
X
X The return is the value to put into either HorizPot or VertPot,
Xdepending on what orientation you have the gadget.
X
X
XBUGS
X
X n/a
X
XEXAMPLE
X
XSEE
X SetSize(),ReadLocation()
X
X;--------------------------------------------------------------------
X
XNAME
X ReadLocation
XSYNOPSIS
X
XLocVal=ReadLocation(MaxValue,ViewSize,PotValue)
X D0 D0.L D1.L D2.W
X
Xlong LocVal,MaxVal,ViewSize;
Xshort PotValue;
X
X
XDESCRIPTION
X
X If you prop gadget has been moved, this is the routine that
Xyou would use to determine where it's been moved to.
X
XRETURNS
X Returns the decoded value of the prop, as an unsigned 32 bit.
XThis is the element number (line number usually) that should be
Xdisplayed on the first line of your display window.
X
XSEE
X
X SetSize(), SetLocation()
X
XBUGS
X n/a
X
XEXAMPLE
X
X;--------------------------------------------------------------------
X
XNAME
X Format
XSYNOPSIS
X
X Format(Buffer,string,values)
X A2 A0 A1
X
Xchar *Buffer,string[];
Xchar **values;
X
XDESCRIPTION
X
X This does the same thing as sprintf(), except that it isn't in
Xthe stdio library, and doesn't use up very much room. This function
Xuses the ROM function RawDoFmt to do the print() style formatting.
XThis routine does not allow the use of all of the '%' directives (for
Xexample, floating point numbers can not be printed with this). For
Xfull documentation on what directives are supported, see the
Xdocumentation on RawDoFmt. This is the routine that TextRequest (and
Xtherefore SimpleRequest and TwoGadRequest) use for their text
Xformatting, so these restrictions apply to them also.
X
X The RawDoFmt routine also assumes that 'int's are sixteen bits
Xlong. Therefore, if you are using a compiler with an int size of
Xthirty-two bits and you want to print an int or a short, you must use
X'%ld', rather than '%d'.
X
XRETURNS
X The number of characters in the formatted string.
XBUGS
X none known
X
XEXAMPLE
X
X Format(Buffer,"There are %d changes to the file %s.",numchanges,
Xfilename);
X
X Format(Buffer,"%x is a hex number, %c is a character.", num, chr);
X
XSEE
X TextRequest, SimpleRequest, TwoGadRequest.
X Further information on printf() style formatting is available in
Xthe AutoDocs on RawDoFmt and in C manuals discussing printf().
X
X;--------------------------------------------------------------------
X
X
X
XNAME
X ColorRequester
XSYNOPSIS
X
XNewColor=ColorRequester(DesiredColor);
X D0 D0
Xlong DesiredColor;
X
XDESCRIPTION
X
X This is a full-fledged color requester. It is intelligent enough
Xto open with the right number of colours in the palette automatically.
XIt shows you both the colour you are working with, and the numerical
XRGB value of that colour. It has Spread, Undo, Ok and Cancel
Xfunctions. Planned is the addition of HSV.
X
X The cursor keys move the color-cursor around the palette, RETURN
Xselects the current color and ESC cancels out.
X
X You pass this routine the color that you would like initially
Xhighlighted (typically the current drawing colour).
X
X The ExtendedColorRequester function has slightly more options, but
Xis slightly more work to call.
X
XRETURNS
X
X Color number that the user selected, -1 if the user cancels the
Xcolour requester. The changed colours will be in the viewport
Xstructure for your screen.
X
XSEE
X ExtendedColorRequester
X
XBUGS
X
X none known.
X
XEXAMPLE
X
X newcolor = ColorRequester(oldcolor);
X
X;--------------------------------------------------------------------
X
XNAME
X ExtendedColorRequester
XSYNOPSIS
X
XNewColor=ExtendedColorRequester(&(struct ExtendedColorRequester)
X D0 A0
Xstruct ExtendedColorRequester colorreqstruct;
X
XDESCRIPTION
X This call brings up exactly the same color requester as the
XColorRequester call. The only difference is that this routine allows
Xyou to specify more parameters. The difference is actually quite
Xsmall right now, because there is only one additional parameter that
Xcan be passed through this entry point. This is the ecr_window
Xparameter, used to specify what window (and hence what screen) the
Xcolor 'requester' appears on. This parameter is rarely needed because
Xthe window the requester opens up on can be specified by setting the
Xpr_WindowPtr field in your process structure to the address of your
Xwindow structure (see the beginning of the docs for an overview on
Xthis procedure). The only time this entry point is needed, currently,
Xis if you try to bring up the color requester on a custom screen from
Xa task, since a task does not have a pr_WindowPtr and can therefore
Xnot specify the window and screen.
X
XRETURNS
X
X Color number that the user selected, -1 if the user cancels the
Xcolour requester. The changed colours will be in the viewport
Xstructure for your screen.
X
XSEE
X ColorRequester
X
XBUGS
X
X none known.
X
XEXAMPLE
X
X /* This should generally be declared as a global variable */
X /* so that all of it's elements get initialized to zero. */
X /* If you declare it as a local variable, be sure to zero */
X /* all of the fields, even the unused ones. */
X struct ExtendedColorRequester colorstruct;
X
X colorstruct.defcolor = 0;
X colorstruct.window = mywindow;
X newcolor = ExtendedColorRequester(&colorstruct);
X
X;--------------------------------------------------------------------
X
XNAME
X MakeGadget
XSYNOPSIS
XMakeGadget(Buffer,String, X, Y)
X A0 A1 D0 D1
Xstruct Buffer *GadgetBlock;
Xchar *String;
Xlong D0,D1;
XDESCRIPTION
X
X This routine prepares a buffer to be a standard BOOLEAN text
Xgadget. This is a simple way of producing gadgets for code that must
Xbe reentrant, and it is more efficient than defining gadgets in data
Xstatements. The routine initializes the gadgets to a set of
X'standard' values that should cover most cases and then links the four
Xparts of the GadgetBlock together.
X
X Buffer is a pointer to a unitialized GadgetBlock, which contains
Xthe necessary Gadget, Border, border pairs and IntuitText structures
Xneeded to render a boolean gadget with a border and some text.
X
X String is a pointer to the text that should appear inside the
Xgadget. The gadget is automatically sized to match the strings
Xlength.
X
X X and Y are the gadgets initial position, they are simply copied
Xinto LeftEdge and TopEdge in the gadget structure.
X
XRETURNS
XSEE
XBUGS
XEXAMPLE
X
X
X;--------------------------------------------------------------------
X
XNAME
X MakeString
X
XSYNOPSIS
XMakeString(Buffer,StringBuff,UndoBuff,MaxWidthBits,MaxNumChars, X, Y)
X A0 A1 A2 D0 D1 D2 D3
X
Xstruct Buffer *StringBlock;
Xchar *StringBuff;
Xchar *UndoBuff;
Xlong MaxWidthBits, MaxNumChars, X, Y;
X
XDESCRIPTION
X
X As with all of the MakeGadget functions, this one prepares a
Xbuffer to be used as a string gadget, that may be used re-entrantly.
XThe buffer need not be cleared first. This means that you may create
Xa temporary gadget on the stack.
X
X The StringBuff is where the body of text inside the gadget will
Xreside.
X
X When the gadget is activated, the text in StringBuff is
Xautomatically copied (by intuition) into UndoBuff. This allows you to
Xtype Amiga-Q and get the old string back. This field may be null if
Xyou wish to have no undo.
X
X MaxWidthBits is the width of the frame around the gadget.
X
X MaxNumChars is the maximum number of characters that you will be
Xable to type into the gadget, including the terminating zero on the
Xstring. MAKE SURE that this number is no greater than your StringBuff
Xsize, or else you're going to be typing over memory that isn't yours.
X
X X,Y are the position of the upper left hand corner of the gadget.
XThe border is actually 2 pixels above and to the left of this corner.
X
XRETURNS
X Nothing
XSEE
X
X MakeGadget,MakeProp,MakeScrollbar,LinkGadget,LinkProp,LinkString
X
X
X;--------------------------------------------------------------------
X
XNAME
X MakeProp
XSYNOPSIS
X
XMakeProp(Buffer,Width,Height,Flags)
X A0 D0 D1 D2
X
Xstruct Buffer *PropBlock;
Xlong Width, Height, Flags;
X
XDESCRIPTION
X
X This routine prepares an un-initialized buffer for use as a prop
Xgadget.
X
X Buffer, on return, will contain the gadget, along with the
Xnecessary PropInfo and Image structures, all linked together.
X
X Width is the with of the container, in pixels.
X Height is the height of the container in pixels.
X
X The Flags parameter is where you decide if you want FREEHORIZ,
XFREEVERT, or both. It is simply copied into the gadget flags field.
X
X
XRETURNS
X
X Nothing
X
X
X;--------------------------------------------------------------------
X
XNAME
X DrawBox
XSYNOPSIS
X
XDrawBox(rp,MinX,MinY,MaxX,MaxY)
X A1 D0 D1 D2 D3
X
Xstruct RastPort *rp;
Xlong MinX,MinY,MaxX,MaxY;
X
X
XDESCRIPTION
X
X This routine allows you to draw a simple box in one command.
XIt draws the box in APen color, in the current draw mode, with the
Xcurrent line pattern.
X
X (MinX,MinY) are the upper left corner of the box, and
X(MaxX,MaxY) are the lower right.
X
X The pen is left at the upper left corner (MinX,MinY).
X
X;--------------------------------------------------------------------
X
XNAME
X MakeButton
XSYNOPSIS
X
XMakeButton(Buffer,Image,Image2,Width,Height,Depth)
X A0 A1 A2 D0 D1 D2
X
X
Xstruct TwoImageGadget *Buffer;
Xchar *Image; /* Pointer to the actual bitplane data */
Xchar *Image2; /* Pointer to the second image. */
Xlong Width,Height,Depth;
X
X
X
X
XDESCRIPTION
X
X The purpose of this routine is one similar to MakeGadget, but
Xinstead of using text for the button, it uses a graphic. You supply a
Xbitmap, and MakeButton will use it in it's rendering.
X
X You may have either one or two images, the routine handles it
Xroutinely. If you supply one image, then this sets GADGHCOMP, and if
Xyou have two images, it sets GADGHIMAGE. RELVERIFY is always set, so
Xas long as you the user is pressing that gadget, the alternate
Xhighlight is shown.
X
X Buffer has room for two images.
X
X Image is a pointer to the actual image data, in CHIP memory, for
Xthis gadget.
X Image2 is a pointer to the alternate image data.
X
X Width and Height make up the size of your image.
X
X Depth is how many bitplanes of data you've supplied.
X
XBUGS
X It's not really a bug, but if your images aren't the same size,
Xthen one won't erase the other when it is drawn, so you may be showing
Xan image with traces of the other one left there.
X
X;--------------------------------------------------------------------
X
XNAME
X MakeScrollBar
XSYNOPSIS
X
XMakeScrollBar(Buffer,Flags,Size,X,Y)
X A0 D0 D1 D2 D3
X
Xstruct ScrollBlock *Buffer;
Xlong Flags,Size,X,Y;
X
X
XDESCRIPTION
X
X This is a special routine that creates a scrollbar (which consists
Xof a prop gadget and two arrows) and you handle it like it's a single
Xgadget. You may have either a horizontal scrollbar, or a vertical
Xscrollbar. These scrollbars are very much like the ones in workbench
Xwindow borders. These use slightly different images on the arrows,
Xhowever.
X
X The way you determine how this set up and oriented is by flag
Xcombinations. If you wished to put a scrollbar in the bottom border
Xof a window, then you would pass (in flags):
X
X Flags = (HORIZSLIDER | GRELBOTTOM | GRELWIDTH)
X
X If you wished it in the right border:
X
X Flags = (VERTSLIDER | GRELRIGHT | GRELHEIGHT)
X
X The idea is to allow you to manipulate the scrollbar as though it
Xwere a single gadget, not three. If you pass confusing flags (like
XGRELBOTTOM|GRELHEIGHT) then it is undefined what will happen.
X
X If all you want is a simple scrollbar that doesn't size, then just
Xset VERTSLIDER or HORIZSLIDER.
X
XSEE
X
X
X;--------------------------------------------------------------------
X
XNAME
X PurgeFiles
XSYNOPSIS
X PurgeFiles(&FileRequesterStructure)
X A0
XDESCRIPTION
X Clear up all memory and file locks allocated by the file
Xrequester. This routine must be called before your program exits if
Xyou use the file requester with either FRQEXTSELECTM bit set or the
XFRQCACHINGM bit set. The first bit is if you want the user to be able
Xto select multiple files. The file requester has to allocate a linked
Xlist of file names which this function will purge. The FRQCACHINGM
Xbit is set if you want the file requester to remember the contents of
Xa directory between calls.
X
X This routine can be called any time you want the buffers and file
Xlocks purge.
X
XRETURNS
X This routine does not return anything.
X
XSEE
X FileRequest
XBUGS
X None known.
XEXAMPLE
X
Xmain()
X {
X FileRequest(&FileRequesterStructure);
X
X .
X .
X .
X
X PurgeFiles(&FileRequesterStructure);
X }
X
X
X
X;--------------------------------------------------------------------
X
XNAME
X GetFontHeightAndWidth
XSYNOPSIS
X
XDESCRIPTION
X
X This allows you quick access to the font attributes set by the
Xuser in preferences. The font width is returned in D0 and the height
Xis returned in D1.
X
XRETURNS
XSEE
XBUGS
XEXAMPLE
X
X
X
X;--------------------------------------------------------------------
X
XNAME
X LinkGadget
XSYNOPSIS
X
XLinkGadget(Buffer,String,nw, X, Y)
X A0 A1 A3 D0 D1
X
Xstruct GadgetBlock *Buffer;
Xchar *String;
Xstruct NewWindow *nw;
Xlong X,Y;
X
XDESCRIPTION
X
X This is actually a superset of the previous command MakeGadget.
XWhat this does is automatically link the gadget into your NewWindow
Xstructure's gadget list.
X
X No registers are disturbed.
X
XSEE
X MakeGadget
XBUGS
X n/a
X
X
X
X;--------------------------------------------------------------------
X
XNAME
X LinkStringGadget
XSYNOPSIS
XLinkStringGadget(Buffer,StringBuf,UndoBuf,nw, WidthBits,NumChars, X, Y)
X A0 A1 A2 A3 D0 D1 D2 D3
X
Xstruct StringBlock *Buffer;
Xchar *StringBuf;
Xchar *UndoBuf;
Xstruct NewWindow *nw;
Xlong WidthBits,NumChars,X,Y;
X
XDESCRIPTION
X
X This is number 2 in the LinkGadget routines. This one obviously
Xlinks the string gadget to the window's gadget list. In fact, the
Xonly difference between this and the MakeString routine is the
Xaddition of the NewWindow pointer.
X
XSEE
X MakeStringGadget
X
X
X;--------------------------------------------------------------------
X
XNAME
X LinkPropGadget
XSYNOPSIS
X
XLinkPropGadget(Buffer,nw, Width, Height, Flags, LeftEdge, TopEdge)
X A0 A3 D0 D1 D2 D3 D4
X
Xstruct PropBlock *Buffer;
Xstruct NewWindow *nw
Xlong Width,Height,Flags,LeftEdge,TopEdge;
X
XDESCRIPTION
X
X Here we have a superset for MakeProp. It works exactly the same
Xas MakeProp, except that it attaches the gadget to the head of the
Xlist in the window.
X
XSEE
X MakeProp
X
X
X;--------------------------------------------------------------------
X
XFileRequester
X
XNAME
X FileRequester - bring up a file/font requester.
X
XSYNOPSIS
X success = FileRequester(&FileRequesterStructure)
X D0 A0
X
XFUNCTION
X Bring up a fully intuitionized file/font requester (actually a
Xwindow) and let the user select a file/font.
X
XINPUTS
X &FileRequesterStructure - pointer to an initialized (can be
Xinitialized mostly to zeroes) file requester structure.
X
XRESULT
X Returns TRUE or FALSE to say whether the user selected a file or
Xnot. The file name(s) or font selected are then found by looking at
Xthe file requester structure whose address was passed.
X
X For ideas on customizing the file requester for your particular
Xsystem (thus overriding the defaults used by programmers who use the
Xfile requester) see the customizefile.asm file.
X
XBUGS
X Problem with an Intuition bug that messes up the current active
Xwindow if a window closes when one of its string gadgets is still
Xactive. This bug show up if you run the file requester straight from
Xa CLI window and then exit it with Amiga-L.
X I have heard that it resets some window flags when run on a custom
Xscreen, but I believe this is a feature of Intuition, not of the file
Xrequester.
X
XSEE ALSO
X PurgeFiles
X
X
X The file requester in the requester library allows to put a
Xpowerful and easy to use file requester into your programs with a
Xminimum of work and at a very small expense in program size. The file
Xrequester was designed to be as easy as possible to call, while not
Xsacrificing power.
X
X To get the file requester to come up all you need to do (after
Xopening the requester library of course) is to allocate space for a
XFileRequester structure and then call the file requester with the
Xaddress of this structure, with all fields initialized to zero, like
Xthis:
X
Xstruct FileRequester MyFileReqStruct;
X
Xsuccess = FileRequester(&MyFileReqStruct);
X
X The function will return either one or zero for success or failure
Xrespectively.
X
X You can specify what screen the file requester should appear on in
Xone of two ways. If you want it to appear on a custom screen, then
Xthe best way is to set the pr_WindowPtr field in your process
Xstructure to point at one of the windows on your screen (this should
Xbe done anyway, so that DOS requesters appear on your custom screen).
XThis field is looked at by all functions in the requester library so
Xthis way is the simplest method. The other way, which overrides the
Xpr_WindowPtr field is to initialize the frq_Window field to point at
Xone of your windows. If this field is non-zero, it is used instead of
Xthe pr_WindowPtr field of your process structure. Important note: It
Xis VERY important that you reset the pr_WindowPtr field back to its
Xoriginal value before your program exits. If you don't, the next
Xprogram run may try to open a requester window on a now closed screen.
X
X The file requester was carefully designed so that it could be
Xcalled without having to initialize very many fields. This is
Xdemonstrated by seeing that it is possible to call it without
Xinitializing any fields. There are a few fields that are necessary to
Xactually get any use out of it, but very view. Those few are
Xdocumented in the following paragraph.
X
X Although you can bring the file requester up without initializing
Xany fields there are a couple of fields that you will definitely want
Xto initialize. The file requester isn't much use unless you get a
Xfile name back out of it, and for this you need to initialize the Dir
Xand File fields. These two fields should point to character arrays
Xthat are, respectively, DSIZE+1 and FCHARS+1 bytes long. When the
Xfile requester is first run the file requester looks in these arrays
Xfor the default directory and file names and if the user selects a
Xfile name the directory and file name are copied back into these
Xarrays. You will probably want to initialize the Title field with the
Xmessage that you want to have appear at the top of the file requester
Xwindow.
X
X If you initialize the PathName field (it should point an array of
Xat least DSIZE+FCHARS+2 characters) then when the user selects a file,
Xthe complete path name will be put into this array.
X
X The Window field is used to specify what window the file requester
Xis associated with. This is used to get the file requester to show up
Xon a custom screen. Generally this field should be unnecessary.
XThere is a variable provided in a process structure which is used for
Xthis purpose. Any program that opens a custom screen and uses any DOS
Xfunctions should set the pr_Window pointer in their process structure
Xto a pointer to their window so that DOS requesters will show up on
Xtheir custom screen. If you do this, then the file requester will
Xalso show up on your custom screen. If you are not using a custom
Xscreen then you don't need to set the pr_Window pointer or the Window
Xfield in the file requester structure. Note: If you do set the
Xpr_Window structure in the process structure, be sure to return it to
Xits old value before your program exits.
X
X If the extended select bit is set in the Flags field then the
XMaxExtendedSelect fields specifies the maximum number of files that
Xthe user can select. This is ignored if the extended bit isn't set in
Xthe Flags field.
X
X numlines and numcolumns specify the maximum size that the file box
Xwill be in characters. If the system is low on memory, or the screen
Xis too small, these will be shrunk as necessary. devcolumns is the
Xnumber of columns of characters wide that the device box will be.
X
X The Flags field can currently contain seven different flags. The
Xfirst flag, FRQSHOWINFOM, specifies whether or not '*.info' files
X(files containing information for icons) should be filtered out. The
Xdefault is for them to be filtered.
X
X The FRQEXTSELECTM flags specifies whether extended select is
Xwanted. If you set this flag then you should probably also set the
XMaxExtendedSelect field. If you don't then the maximum number of
Xfiles the user will be able to select will be 65536, which is a bit
Xhigh for most purposes. Note: If you use this bit then you _must_
Xcall PurgeFiles() with the address of your FileRequester structure
Xafter the last time you call the file requester, in order to free up
Xany memory used in the extended select structures. When the user
Xselects multiple files, a linked list of the file names selected (not
Xincluding the directory name) will appear in the ExtendedSelect field.
XThe list is a linked list of ESStructures. The directory name which
Xshould be prepended to all of these names will appear in the array
Xpointed to by the Dir field.
X
X The FRQCACHINGM flag specifies whether or not directories are
Xcached from one call to the next. This is a very handy features,
Xespecially for those who lack hard drives. However, if this features
Xis used, you _must_ call the PurgeFiles() routine with the address of
Xyour FileRequester structure after the last time you call the file
Xrequester, in order to free up any memory used in caching.
X
X As well as being a file requester, this routine can be used as a
Xfont requester too. Just set the FRQGETFONTSM flags to turn it into a
Xfont requester. You should also put the name 'fonts:' in the Dir
Xarray. The file/font requester will return a one or zero for success
Xor failure as usual, the font name will be returned in the File array
Xand the font size and style will be returned in the FontYSize and
XFontStyle fields. Note that the font requester allows the user to
Xchange the directory where the fonts are read from. Although you
Xshould put 'fonts:' there, you should allow for the possibility that
Xthe user might change the directory. They might, perhaps, have a
Xseparate disk full of fonts. The simplest way to deal with fonts
Xcoming from different directories, is to set the PathName field
Xinstead of the Dir field. You can then use the string in the PathName
Xfield (which will contain the directory and font name) as the font
Xname. If you don't do this, then you have to concatenate the font
Xname and the directory name yourself. If you use the PathName
Xvariable then it is quite reasonable to leave the File field blank,
Xsince all the information you need can be obtained from the PathName
Xstring.
X
X The FRQINFOGADGETM flag specifies whether or not a hide/show info
Xgadget should appear on the file requester. This lets the user toggle
Xthe state of the FRQSHOWINFOM flag to decide whether or not to let
X'*.info' files show up. This is not recommended for most programs,
Xsince most users have no reason to look at '*.info' files. The
Xdefault is to _not_ have this gadget show up.
X
X The FRQHIDEWILDSM flag specifies whether or not to have 'show' and
X'hide' string gadgets. These gadgets let the user use wildcards to
Xspecify which files should show up. All files are first compared
Xagainst the 'show' gadget. If they fail the comparison, they are not
Xdisplayed. Then they are compared against the 'hide' gadget. If they
Xmatch here then they are not displayed. If the gadgets are empty, no
Xcomparisons are done. Important note: Even if these gadgets are not
Xdisplayed, the comparisons are still done on the data which is in the
XHide and Show fields of the file requester structure. The standard
XAmigaDOS wildcards (including '#', '?', '|' and '*') are supported.
X
X Normally the file requester appears centered under the mouse
Xpointer. If you would like to specify its opening position you must
Xset the ABSOLUTEXYM flag and then put the x,y position in
XWindowLeftEdge and WindowTopEdge.
X
X If you feel that the file requester's cached directories (selected
Xby FRQCACHINGM) should be purged whenever the directory has been
Xchanged, then set FRQCACHEPURGEM field and the file requester will
Xcheck the dates whenever it is opened.
X
X If you feel that the file requester should never cache directories
Xunless it manages to read in the entire directory before the user
Xsends it away, then set the FRQNOHALFCACHEM flag. This flag will
Xcause the file requester to automatically flush any incompletely read
Xdirectories when it exits.
X
X If you would like your directories to appear in 'natural' order
Xinstead of alphabetically sorted, set the FRQNOSORTM flag.
X
X If you would like the file requester to appear without a drag bar
Xor depth arrangement gadgets, set the FRQNODRAGM flag.
X
X If you are using the file requester to select a filename to save
Xto, you should set the FRQSAVINGM flag. Similarly, if you are using
Xthe file requester to select a filename to load from, you should set
Xthe FRQLOADINGM flag. These flags are not currently used by the file
Xrequester, but they may be used in the future. They also make it
Xeasier for people who want to personalize the file requester to make
Xit behave differently for loading vs. saving.
X
X
X The various color fields let you specify the colors of many
Xaspects of the file requester. If they are left as zero then the file
Xrequester uses various non-zero certain default values for them.
X
X The WindowLeftEdge and WindowTopEdge fields are covered in the
Xsection on the ABSOLUTEXYM flag.
X
X The FontYSize and FontStyle fields are covered in the section on
Xthe FRQGETFONTSM flag.
X
X The ExtendedSelect field is covered in the section on the
XFRQEXTSELECTM flag.
X
X The Hide and Show fields are covered in the section on the
XFRQHIDEWILDSM flag.
X
XSet this bit if you are selecting a file to save to.
XSet this bit if you are selecting a file(s) to load from.
XThese two bits (save and load) aren't currently used for
Xanything, but they may be in the future, so you should
Xremember to set them. Also, these bits make it easier if
Xsomebody wants to customize the file requester for their
Xmachine. They can make it behave differently for loading
Xvs saving.
X
X The four BufferPos and DispPos variables are copies of the
Xequivalent variables from the four string gadgets. This is so that
Xwhen the file requester goes away and then is brought up again, the
Xcursor in the string gadgets will appear in the same places as before.
XThese fields should not need to be touched by the programmer.
X
X The rest of the fields are private. Don't go touching them. We
Xguarantee to move them around and change their meaning, just to make
Xsure that nobody tries to use them. They are largely concerned with
Xkeeping track of memory used in directory caching. This memory is
Xfreed with the PurgeFiles() routine. That's all you should need to
Xknow.
X
X
X
X
X
X;--------------------------------------------------------------------
X
XRealTimeScroll
X
XNAME
X RealTimeScroll - do the calculations necessary for a responsive,
Xpixel resolution, real time scroll routine.
X
XSYNOPSIS
X RealTimeScroll(&ScrollStruct);
X A0
X
XFUNCTION
X Make the implementation of real time scrolling area easier and
Xmake the real time scrolling area more responsive to the user by doing
Xpixel resolution scrolling and by checking the current position of the
Xscroll bar in mid scroll. This routine calculates how far to scroll
Xeach time and calculates which lines of text, graphics etc. need to
Xbe redrawn to fill in the empty area.
X
XINPUTS
X &ScrollStruct - pointer to an initialized scroll structure.
X
XRESULT
X This routine returns no result code.
X
XBUGS
X None known
X
XSEE ALSO
X n/a
X
X
X It is relatively easy to implement a real time scrolling area, but
Xthe most obvious implementations suffer from a lack of responsiveness.
XTypically the routines look at where the scroll bar is, calculate
Xwhere to scroll to, scroll there in several jumps to make the
Xscrolling look smooth, and the examine the scroll bar again to see if
Xit has moved. This means that there are periods, perhaps annoyingly
Xlong, where the program may be scrolling in one direction while the
Xscroll bar is being dragged in another. The answer is to examine the
Xscroll bar to find out the desired location, scroll partway towards
Xthe destination and then recheck the scroll bar's location. This can
Xgreatly increase the responsiveness, since the program is checking
Xafter every ScrollRaster() call, instead of after a dozen or more.
XHowever, the calculations, especially of which lines need to be
Xrefreshed and where, get somewhat more complicated. This routine is
Xdesigned to simplify this situation by taking care of as many of the
Xmessy details as possible.
X
X First you must initialize the scroll structure. The
XTopEntryNumber, NumEntries and NumLines fields describe where the data
Xis currently. NumEntries is the number of lines of data in total,
XNumLines is the number of lines that are visible, and TopEntryNumber
Xis the line number of the first line visible (it therefore ranges from
Xzero to NumEntries - 1).
X
X LineSpacing is the number of pixels high that each line of data
Xis. For text this will typically be eight or nine (for eighty or
Xsixty column topaz). This can be set to one if your data is
Xcontinuous (as in the case of some graphics).
X
X PropGadget is a pointer to the prop gadget which is being used to
Xcontrol this scroll area.
X
X RedrawAll is a pointer to a function that you must supply to
Xredraw the entire visible window. This routine is called whenever the
Xuser gets so far ahead of the scroll routine that scrolling to where
Xthe users wants to be would take to long. Before calling this
Xroutine, the ScrollStruct that was passed to this routine is updated
Xwith the desired TopEntryNumber so that your routine will know which
Xdata to redraw.
X
X ReadMore is an optional routine that will usually not be used. It
Xis used if more data is being added while the scrolling is going on.
XThis is used, for instance, by the FileRequest in the requester
Xlibrary, to continue attempting to read the directoy while the user is
Xscrolling. Leave this set to zero if you don't need it. It is only
Xcalled when no scrolling is being done, but the user has not released
Xthe scroll bar.
X
X ScrollAndDraw is the most important routine. This routine, which
Xyou must supply, is called whenever the data must be scrolled. The
Xactual scrolling and redrawing of the data is done by this routine,
Xbut because the scroll amount, the lines to be drawn and the number of
Xlines to be drawn are passed to this routine, the routine is fairly
Xsimple. Four parameters are passed to this routine:
X
XScrollAndDraw(firstlinenum, firstliney, scrollamount, numlines);
X
X All four parameters are passed as longs, both on the stack and in
XD0-D3, so that the routine can easily be written in either C or
Xassembler.
X
X When the ScrollAndDraw, ReadMore or RedrawAll routines are called,
XA4, A5 and A6 all contain the same values they contained when
XRealTimeScroll was called. This allows programs written in C using
Xthe small data model to be able to access their data properly from
Xthese routines without any special work. All other registers (except
Xthose that are used to pass parameters in) could contain anything.
X
X
X
X
X;--------------------------------------------------------------------
X
X
X
XTextRequest
X
XNAME
X TextRequest - bring up a text requester with one to three gadgets
Xand get a response.
X
XSYNOPSIS
X result = TextRequest(&TRStructure);
X D0 A0
X
XFUNCTION
X Bring up a requester (actually a window) containing a message to
Xthe user and give him a choice of from one to three different
Xresponses. The window automatically sizes to fit the text and
Xprintf() style formatting can be used by TextRequest() to generate the
Xmessage to the user.
X
XINPUTS
X &TRStructure - pointer to an initialized text requester structure.
X
XRESULT
X Returns either zero, one or two, depending on which gadget the
Xuser clicks on. All of the gadgets are optional, so that the
Xrequester can be used to bring up requesters that give the user a
Xmessage, without demanding an answer, by having only a single gadget.
XThe gadget in the lower right hand corner (the negative gadget)
Xreturns a zero, the gadget in the lower left hand corner (the positive
Xgadget) returns a one and the gadget in the middle returns a two. If
Xnone of these three gadgets are requested, a close gadget is attached
Xto the window and it returns a zero.
X
XBUGS
X If any line of the text to be printed is too long, then the
Xrequester will attempt to open up an impossibly large window, which
Xwill fail and the requester will return a zero.
X The buffer used for formatting the text is 5000 bytes long, so no
Xmessages can be longer than this.
X
XSEE ALSO
X SimpleRequest
X TwoGadRequest
X
X
X The purpose of this routine is to make it as easy to print
Xformatted messages in intuitionized window with gadgets as it is to
Xprint them on the CLI screen. For maximum ease of use, at a loss of
Xflexibility, please see the functions SimpleRequest and TwoGadRequest
Xwhich are simply glue code functions to make calling TextRequest a
Xtrivial matter.
X
X If you want the text requester to appear on a custom screen, then
Xyou must set the pr_WindowPtr field in your process structure to point
Xat one of the windows on your screen (this should be done anyway, so
Xthat DOS requesters appear on your custom screen). This field is
Xlooked at by all functions in the requester library so this way is the
Xsimplest method. Important note: It is VERY important that you reset
Xthe pr_WindowPtr field back to its original value before your program
Xexits. If you don't, the next program run may try to open a requester
Xwindow on a now closed screen.
X
X The structure whose address is passed to this routine must be
Xinitialized first.
X
X The Text field is initialized with the body of the text you would
Xlike displayed. This text can contain both printf() style formatting
Xand end of line characters ('\n' in C, ascii 10 in assembler). The
Xprintf() style formatting, is expanded out into the final text string
Xusing the parameter list which is pointed to by the Controls field.
XLine feeds are used, as usual, to specify a new line, thus allowing
Xvery long and complex messages to be displayed. The are some
Xlimitations on the types of printf() formatting that can be used.
XSince the RawDoFmt() function of the ROM is used to do the formatting,
Xonly functions supported by it can be used. For complete
Xdocumentation, see the documentation of the RawDoFmt() command. The
Xmain things to be aware of is that floating point numbers can not be
Xprinted, and, if you are using a compiler that uses thirty-two bit
Xints then we will have to specify '%ld' to print an int, since the
XRawDoFmt command assumes an int size of sixteen bits.
X
X The Controls field points to a list of parameters, one for each of
Xthe '%' parameters in the Text field. Normally these will be pushed
Xon to the stack and the stack pointer copied into the Controls field.
XThe first parameter used (the first one to occur in the string) should
Xbe at the beginning of the list, that is, at the lowest address, the
Xone pointed at by the Controls parameter.
X
X The Window field can be used to specify what screen you would like
Xthe requester to appear on. This field is usually not necessary since
Xthe same information can be conveyed in the pr_WindowPtr field of your
Xprocess structure. However this field was left in so that the
XTextRequest function could be called from a task (which lacks a
Xprocess structure and therefore a pr_WindowPtr field). If this field
Xis non-zero or if the calling program is a task then this field takes
Xprecedence over the pr_WindowPtr field.
X
X MiddleText, PositiveText and NegativeText are the pieces of text
Xused for the three gadgets. These three gadgets, when present, are
Xplaced in the middle, the left and the right of the window
Xrespectively. All three gadgets are placed along the bottom of the
Xwindow. All of the gadgets are optional. If a gadget is not wanted,
Xthe text pointer should be set to zero. The values returned if the
Xuser clicks on these gadgets are two, one or zero, respectively. If
Xnone of the gadgets are present (if all of the text fields are zero)
Xthen a standard CLOSEWINDOW gadget is attached to the window. This
Xgadget returns a zero.
X
X The requester attempt to appear so that the negative gadget is
Xunderneath the mouse pointer. If the negative gadget is not present
Xit will attempt to appear so that a different gadget is underneath the
Xmouse pointer. This is to make it as convenient as possible for the
Xuser to respond to, and especially to respond negatively to, the
Xrequester.
X
X In addition to responding to the requester with the mouse,
Xkeyboard shortcuts are available. The user can type ESC, 'N', 'Q' or
X'B' as a shortcut to clicking on the negative gadget. The user can
Xtype 'Y' or 'V' as a shortcut to clicking on the positive gadget and
Xcan type 'M' as a shortcut to clicking on the middle gadget.
X
X The Title field of the structure should either point to a null
Xterminated string to be used in the windows title bar or should be
Xnull.
X
X The KeyMask field is used to regulate the use of keyboard
Xshortcuts. The qualifier field of all keyboard messages is ANDed with
Xthis field, and the keypress is ignored if the result is zero.
XTherefore, to enable all keypresses to be used as keyboard shortcuts,
Xinitialize this field to $FFFF. To turn off the keyboard shortcuts,
Xinitialize this field to 0. To force the user to hold down the left
Xor right amiga key, initialize this field to AMIGAKEYS.
X
X The textcolor, detailcolor and blockcolor fields can be left
Xunitialized (ie; set to zero) if you wish, in which case the requester
Xwill use the default values of one, zero and one respectively. The
Xtextcolor field is used for the color of the actual text message and
Xthe detail and block color fields are simple copied into the fields of
Xthe same name in the new window structure.
X
X;--------------------------------------------------------------------
X
X
XSimpleRequest
X
XNAME
X SimpleRequest - bring up a text requester and wait for the user to
Xacknowledge it.
X
XSYNPOSIS
X SimpleRequest(string, parameterlist, , ,)
X A0 A1
X
XFUNCTION
X Bring up a requester (actually a window) containing a message to
Xthe user and wait for the user to acknowledge it. The window
Xautomatically sizes to fit the text and printf() style formatting can
Xbe used by TextRequest() to generate the message to the user.
X
XINPUTS
X string - a null terminated string, containing printf() style
Xformatting commands if desired.
X parameterlist - the parameters corresponding to the printf() style
Xformatting commands in the string. In C these are listed after the
Xcontrol string, exactly as with printf(). In assembler, the address
Xof the list of parameters is put in A1.
X
XRESULT
X No result code is returned.
X
XBUGS
X See TextRequest
X
XSEE ALSO
X TextRequest
X TwoGadRequest
X
X
X This function was designed to make it as easy to give messages to
Xthe user and await acknowledgment in an intuition style requester as
Xit is using printf() and getc(). Simply replace almost any call to
Xprintf() with a call to SimpleRequest and a requester will appear and
Xnot disappear until the user acknowledges it (either with a keystroke
Xor with the mouse).
X
X Example:
X SimpleRequest("There have %d changes made to this file.",
X numchanges);
X
X Please see the TextRequest documentation for further important
Xdetails. This routine is simply a few lines of assembler glue code
Xfor the TextRequest routine. The TextRequest routine is a little bit
Xmore complicated to use, but it allows correspondingly more
Xflexibility. It is fairly simple to modify the glue code to allow
Xstill more high level entry points to the TextRequest routine.
X
X
X This is a complete program that makes use of the SimpleRequest
Xfunction from assembler, and demonstrates a few of the features of
XFormat (which is used by SimpleRequest).
X
X;--------------------------------------------------------------------
X;-----CUT HERE---------------CUT HERE--------------------------------
X;--------------------------------------------------------------------
X
X INCLUDE "libraries/reqbase.i"
X
X public SimpleRequest
X public _ReqBase,_main
X
X;--------------------------------------------------------
X; This file should be linked with reqglue.o, for the SimpleRequest
X;function.
X;--------------------------------------------------------
X
XSYS MACRO
X XREF _LVO\1
X JSR _LVO\1(A6)
X ENDM
X
X;--------------------------------------------------------
X
X
X_main
X OpenReq
Xmystart
X
X MOVE.L A6,A5
X MOVE.L A6,_ReqBase
X
X
X PEA string
X MOVE.L #$C0FFEE,-(SP)
X MOVE.W #$1CE,-(SP)
X MOVE.W #'B',-(SP)
X MOVE.L #-12345,-(SP)
X MOVE.L SP,A1
X LEA Text,A0
X JSR SimpleRequest
X
X LEA 16(SP),SP
X
X MOVE.L A5,A1
X MOVE.L 4,A6
X SYS CloseLibrary
X
X MOVEQ #0,D0
X RTS
Xstring
X DC.B "This is a string.",0
XText
X DC.B "A long (signed) decimal is: %ld,",10
X DC.B "a character is: %c,",10
X DC.B "a 16 bit hex val might be: %x, ",10
X DC.B "a register-style format 32 bit hex: $%08lx,",10
X DC.B "and a string might read: `%s'.",0
X
X dseg
X
X_ReqBase DC.L 0 ;The SimpleRequest function in the glue code
X ;needs this variable.
X
X END
X
X;--------------------------------------------------------------------
X;-----CUT HERE---------------CUT HERE--------------------------------
X;--------------------------------------------------------------------
X
X
X
X
X;--------------------------------------------------------------------
X
X
X
XTwoGadRequest
X
XNAME
X TwoGadRequest - bring up a text requester and wait for the user to
Xacknowledge it.
X
XSYNPOSIS
X result = TwoGadRequest(string, parameterlist, , ,)
X A0 A1
X
XFUNCTION
X Bring up a requester (actually a window) containing a message to
Xthe user and wait for the user to click on either the OK or the CANCEL
Xgadget. The window automatically sizes to fit the text and printf()
Xstyle formatting can be used by TextRequest() to generate the message
Xto the user.
X
XINPUTS
X string - a null terminated string, containing printf() style
Xformatting commands if desired.
X parameterlist - the parameters corresponding to the printf() style
Xformatting commands in the string. In C these are listed after the
Xcontrol string, exactly as with printf(). In assembler, the address
Xof the list of parameters is put in A1.
X
XRESULT
X Either one or zero is returned, depending on whether the user
Xselected, respectively, the OK or the CANCEL gadget.
X
XBUGS
X See TextRequest
X
XSEE ALSO
X TextRequest
X SimpleRequest
X
X
X This function was designed to make it as easy to give messages to
Xthe user and get a response in an intuition style requester as it is
Xusing printf() and getc(). Simply replace almost any call to printf()
Xwith a call to SimpleRequest and a requester will appear and not
Xdisappear until the user responds to it (either with a keystroke or
Xwith the mouse).
X
X Example:
X if (TwoGadRequest("There have %d changes made to this file.\n"
X "O.K. to continue?",
X numchanges))
X exit(10);
X
X Please see the TextRequest documentation for further important
Xdetails. This routine is simply a few lines of assembler glue code
Xfor the TextRequest routine. The TextRequest routine is a little bit
Xmore complicated to use, but it allows correspondingly more
Xflexibility. It is fairly simple to modify the glue code to allow
Xstill more high level entry points to the TextRequest routine.
X
X
X
X-------------------------------------------------------------------
XNAME
X GetString
X
XBOOL = GetString(buffer, title, window, visiblechars, maxchars)
XD0 A0 A1 A2 D0 D1
X
XDESCRIPTION
X This routine allows you to bring up a nice intuition style string
Xrequester in its own window and get a single line of input from the
Xuser in just a one line function call.
X
X buffer points to the a buffer containing the string which will
Xappear when the string gadget first appears and it is also where the
Xresult will be put, if this routine returns TRUE.
X Title is a pointer to a null terminated string that will be used
Xfor the window title.
X Window can be used to specify what screen you would like the
Xrequester to appear on. You simply put a window pointer in it (or a
Xzero if you want the requester to appear on the workbench screen). If
Xyou have already set your pr_WindowPtr then you can simply pass a zero
Xfor the window pointer and the pr_WindowPtr value will be used.
X visiblechars specifies how many characters should actually be
Xvisible at one time.
X maxchars specifies how long the buffer is, including the
Xterminating zero.
X
XRETURNS
X This routine returns true or false, depending on whether the user
Xclicked on the cancel gadget (FALSE) or clicked on the OK gadget
X(TRUE) or clicked on the close window gadget (FALSE) or hit return in
Xthe string gadget (TRUE).
X
XBUGS
X None known.
X
X
X
X-------------------------------------------------------------------
XNAME
X GetLong
X
XBOOL = GetLong(&GetLongStruct)
XD0 A0
X
XDESCRIPTION
X This routine allows you to bring up a nice intuition style string
Xrequester in its own window and get a single signed thirty-two bit
Xnumber from the user in just a one line function call (although a few
Xfields in the structure must be initialized first).
X
X The GetLongStruct contains fields for letting you specify the
Xtitle bar message, the default value that should appear in the
Xrequester and the maximum and minimum values that the routine should
Xallow to be entered. If the routine returns TRUE (indicating
Xsuccessful entry of a number) then the result is returned in the
Xresult field of the structure.
X The window field can be used to specify what screen you would like
Xthe requester to appear on. You simply put a window pointer in it (or
Xa zero if you want the requester to appear on the workbench screen).
XIf you have already set your pr_WindowPtr then you can simply leave
Xthe window field zeor and the pr_WindowPtr value will be used.
X
XRETURNS
X This routine returns TRUE or FALSE (1 or 0) in D0 to specify
Xwhether or not the user successfully entered a number. If this
Xroutine returns TRUE then you can find the result in the result field
Xof the GetLongStruct whose address you passed to GetLong.
X
X
X
X-------------------------------------------------------------------
XRawKeyToAscii
X
XSYNOPSIS
X
X key = RawKeyToAscii(Code,Qualifier,IAddress)
X D0 D0 D1 A0
X
X UWORD Code,Qualifier;
X APTR IAddress;
X
XFUNCTION
X
X Have you ever wanted to have both RAW and COOKED keys? You can do
Xit by checking the keys for whatever raw keys you want, and then using
Xthe console.device's RawKeyConvert routine, except that it's a hassle
Xto start mucking about with the device.
X
X Well, here you go! A nice, clean way of converting from a raw key
Xto a cooked key, in a single call! All you have to do is pass the
Xcode and qualifier from your intuimessage, and the address of the
Xmessage itself, and you will get back the ASCII value of the key that
Xwas hit. This does, in fact, use the console.device's RawKeyConvert,
Xso that if you have a different keymap set, it will be used.
X
XEXAMPLE
X
X
Xstruct IntuiMessage *im;
X
X key = RawKeyToAscii(im->Code,im->Qualifier,im->IAddress);
X
END_OF_FILE
if test 60498 -ne `wc -c <'req.doc'`; then
echo shar: \"'req.doc'\" unpacked with wrong size!
fi
# end of 'req.doc'
fi
echo shar: End of archive 3 \(of 3\).
cp /dev/null ark3isdone
MISSING=""
for I in 1 2 3 ; do
if test ! -f ark${I}isdone ; then
MISSING="${MISSING} ${I}"
fi
done
if test "${MISSING}" = "" ; then
echo You have unpacked all 3 archives.
rm -f ark[1-9]isdone
else
echo You still need to unpack the following archives:
echo " " ${MISSING}
fi
## End of shell archive.
exit 0
--
Mail submissions (sources or binaries) to <amiga@uunet.uu.net>.
Mail comments to the moderator at <amiga-request@uunet.uu.net>.
Post requests for sources, and general discussion to comp.sys.amiga.