Club Amiga de Montreal - CAM/CAM_CD_1.iso/files/326.lha/requester.library_v1.3/BasicUsers

Text File | 1989-12-30 | 6KB | 132 lines

                         FOR BASIC PROGRAMMERS

  The file requester operates on a structure which I've called a FileIO struct.
A structure is one block of memory which contains various "fields". A field
is simply a portion (some bytes) of that block of memory. The FileIO struct-
ure takes up 264 bytes of memory. These 264 bytes contain 29 fields. Some
fields only take up 1 byte, others are 2 bytes wide (a WORD), or 4 bytes
wide (a LONG). Certain other fields can be any number of bytes wide. These
are STRINGS. Each field of a structure contains values (numbers). Sometimes
these numbers form the address of some other structure. An address takes up
4 bytes (just like a LONG), but we'll call it APTR.
  Unfortunately, AmigaBasic has no facility for manipulating structures as
such. You cannot say, "Set the PenA field of my FileIO to the value 1." You
must treat the FileIO as one block of memory, and its various fields as
offsets from the beginning of that block of memory. The library routine
GetFileIO() returns the start address of the FileIO memory block. This is
what it looks like in memory.

  Field Name      Field Size       Offset from start
 ------------    -------------    -------------------

The FileIO starts here:
  LibFlags         1 BYTE                 0
  Flags            1 BYTE                 1
  FileName        30 BYTES (STRING)       2
  DrawerName     132 BYTES (STRING)      32
  DiskName        30 BYTES (STRING)     164
  DOS lock         4 BYTES (APTR)       194
  NameCount        2 BYTES (WORD)       198
  NameStart        2 BYTES (WORD)       200
  CurrentPick      2 BYTES (WORD)       202
  FileKey          4 BYTES (APTR)       204
  FileIOText       4 BYTES (APTR)       208
  FileIORoutine    4 BYTES (APTR)       212
 the next 2 fields are for WB pattern match (i.e. Icon files displayed only)
  DiskObjectType   2 BYTES (WORD)       216
  ToolTypes        4 BYTES (LONG)       218
 the next 2 fields are for extention match
  ExtStringAddr    4 BYTES (APTR)       222
  ExtStringLen     2 BYTES (WORD)       226
  CustomHandler    4 BYTES (APTR)       228
 the next 2 fields are the XY where the requester will open up in the window
  ReqXposition     2 BYTES (WORD)       232
  ReqYposition     2 BYTES (WORD)       234
  FreeDiskSpace    4 BYTES (LONG)       236
  FileSize         4 BYTES (LONG)       240
  WindowTitle      4 BYTES (APTR)       244
  BufferAddress    4 BYTES (APTR)       248
  RawkeyCode       4 BYTES (APTR)       252
  OriginalLock     4 BYTES (APTR)       256
  Error number     1 BYTE               260
  DrawMode         1 BYTE               261
  PenA             1 BYTE               262
  PenB             1 BYTE               263

  If you add up the sizes of all 29 fields, you should get 264 bytes.

  Now, let's say that we called GetFileIO() as demonstrated in the example
program, BasicFileIO. We stored the returned address in a variable called
FileIO.
  There are two AmigaBASIC commands that are used with structures, PEEK and
POKE. If you want to change a field of the FileIO, you must POKE a value to
it. If you want to know what value is already stored in a FileIO field, then
you PEEK that field. For example, if we want to know what the FileIO's PenA
field is, we PEEK that field as follows.

  VALUE = PEEK(FileIO+262)

  I had to add 262 to FileIO because the PenA field's offset is 262 (see
above chart). Now VALUE is the number that was in the PenA field. If we want
to change the number in the PenA field to 2, we must POKE the field like this:

  POKE  FileIO+262,2

  PEEK and POKE are used for fields that are only 1 BYTE in size (like the
PenA, PenB, Flags, etc). For fields that are 2 BYTES (WORD) in size, you
must use POKEW and PEEKW. For example, to change the ReqXposition to 50:

  POKEW FileIO+232,50

  Notice how I added the ReqXposition field's offset to FileIO.

  For LONG and APTR fields (4 BYTES in size), you must use PEEKL and POKEL.
An APTR field is tricky because you can only put an address there. There are
two BASIC commands for finding addresses of variables. If the variable is a
string, use SADD. For all other types of variables, use VARPTR. For example,
let's say we declared the following string.

  Title$ = "Hello"

  Now, let's set the FileIO's WindowTitle field to the address of our string.
As you can see from the chart, the FileIO's WindowTitle field is APTR. In
fact, this field holds the address of the title that is displayed in the
window when the requester opens. Notice that this field's offset is 244.

  POKEL FileIO+244,SADD(Title$)

  For STRINGS (like the FileIO's Diskname), you must use PEEK or POKE to
examine or alter EVERY SINGLE BYTE of the string. The Diskname is 30 BYTES
and has an offset of 164 from the FileIO base. To copy the diskname to a
a BASIC string, you must declare a string of 30 chars in length,

  DIM DiskName$(30)

  and PEEK all 30 bytes (starting at an offset of 164) to this BASIC string.
See the example program for details.

  There is much more to be said about this topic. Please examine the commented
code of the enclosed BASIC example. If the code seems completely alien to you,
then you should buy a book on advanced AmigaBASIC programming. I can't recom-
mend one as I didn't read any. Being an assembly programmer, I was able to
ascertain how to use these BASIC commands by studying an example on the EXTRAS
disk.

  There is one FileIO field that the example only briefly covers, the Flags
field. Here are the values you should POKE to enable the following features.
To enable several features simultaneously, just add up the value for each.

NO_CARE_REDRAW   = 1
USE_DEVICE_NAMES = 2
EXTENSION_MATCH  = 4
DOUBLECLICK_OFF  = 8
WBENCH_MATCH     = 16
MATCH_OBJECTTYPE = 32
MATCH_TOOLTYPE   = 64
INFO_SUPPRESS    = 128

  Of course, read the enclosed Manual fully for a complete understanding of
the library functions.

          Jeff Glatt