amigaguide.datatype Reference

BOOPSI datatype class reference for amigaguide.datatype, synthesised from the AmigaOS NDK 3.2 Release 4 (Autodocs/amigaguide).

Class properties

Property Value
Display name amigaguide.datatype
Group ID GID_DOCUMENT = MAKE_ID('d','o','c','u') (document)
Superclass text.datatype
File format AmigaGuide hypertext database
Methods declared 19
Parent class page text.datatype

Description

The amigaguide.datatype is the DataTypes class for AmigaGuide databases.

Methods

Each method is declared in the autodoc METHODS block. Method implementations are inherited from the superclass unless noted otherwise in the parent's autodoc.

Method Purpose
OM_NEW Create a new AmigaGuide object.
OM_GET Obtain the value of an attribute.
OM_SET Set the values of multiple attributes.
OM_UPDATE Update the values of multiple attributes.
OM_DISPOSE Dispose of an AmigaGuide object.
GM_LAYOUT Layout the object and notify the application of the title and size.
GM_HITTEST Determine if the object has been hit with the mouse.
GM_GOACTIVE Tell the object to go active.
GM_HANDLEINPUT Handle input.
GM_RENDER Cause the AmigaGuide database to render.
DTM_GOTO Cause the AmigaGuide database to load and display document.
DTM_TRIGGER Trigger an event STM_COMMAND - Invoke an AmigaGuide command. STM_CONTENTS - Display the table of contents. STM_INDEX - Display the index. STM_HELP - Display the help file. STM_RETRACE - Retrace. STM_BROWSE_PREV - Go to the previous sequential document. STM_BROWSE_NEXT - Go to the next sequential document.
DTM_PROCLAYOUT Layout (remap) the AmigaGuide database on the application's process.
DTM_FRAMEBOX Obtain the display environment that the AmigaGuide database requires.
DTM_SELECT Select an area in the AmigaGuide database.
DTM_CLEARSELECTED Deselect the selected area of the AmigaGuide database.
DTM_COPY Copy the selected area of the text to the clipboard as FTXT. If no area is selected, then the entire text is copied.
DTM_PRINT Print the selected area of the text. If no area is selected, then the entire text is printed.
DTM_WRITE Write the selected area of the text to a file If no area is selected, then the entire text is saved.

Release history (NDK 3.2 R4)

Excerpted from ReleaseNotes/amigaguide-dt-RelNotes in the NDK 3.2 R4 distribution.

-------------------- AmigaOS 3.5/3.9 project -------------------------

amigaguide 44.1 (14.3.1999)

- A DTM_REMOVEDTOBJECT message now clears cached
  rendering data. Otherwise, amigaguide.datatype would
  crash on the next rendering call.

- The printing command now translates foreground colour #1 to
  ANSI colour #9 and background colour #0 to ANSI colour #9.
  This selects default rendering colours instead of mapping
  black text to red.

- Masked rendering operations no longer directly fiddle with
  the RastPort mask.

- The routine that tries to find a named node in a list by
  means of a case-insensitive comparison now uses
  utility.library/Stricmp rather than a `roll your own'
  comparison routine.

- Fixed a bug in the library init code.

- In word wrap mode, AmigaGuide could reference memory after freeing
  it. This would happen after merging several lines into one. Fixed.

- If the window was too small for the complete row of controller
  buttons to fit, AmigaGuide would attempt to wrap the buttons around
  and end up getting the actual size of the visible text area wrong.
  Fixed.

- Updated header files and autodocs.

- Reimplemented the AGA_Secure feature introduced with AmigaGuide V41
  back in 1996.

- Replaced the old asyncio code with a bug-fixed and shorter version.

- Replaced too many Seek(..,OFFSET_END)..Seek(..,OFFSET_BEGINNING)
  calls with ExamineFH() calls.

- Fixed a bug in the node reader which would open the file a node
  was stored in, then continue to read exactly as many bytes as
  there were in that file from the regular database file and
  finally close the node file again. It was consistently reading
  from the wrong file. Fixed. I'm curious to see what differences
  this bug fix will bring.

- Removed all dead and unused code.

- AmigaGuide now rebuilds its rendering masks whenever
  this is necessary. This should help to improve rendering
  speed.

- Switched over all file I/O done on the database to use
  async I/O calls.

- When triggered by MultiView a DTM_COPY action followed
  by DTM_CLEARSELECT no longer leaves trash in the top
  left corner of the display. I have removed the effect,
  but not the root of the problem. This still remains to
  be done...

- When loading cross reference files, the loader would always
  forget to add the last database entry in a section. Fixed.

- The cross reference database expunge code would not release
  any locks it had allocated. This only worked because the
  way the library code was called no locks were ever allocated
  and the expunge code was never called.

- Completely redid the cross reference manager code which used
  to be terribly inefficient. For every entry to go into the
  database, it would check for duplicates by doing a linear
  search. As the database would increase, the search times
  would double, then quadruple, etc. The new code uses the
  tree lists that worked so well for asl.library; this also
  has the effect of greatly increasing database search speed.

- The cross reference database now allocates all its entries
  using memory pools.

amigaguide 44.2 (15.3.1999)

- Moved over all cross reference database access routines from
  amigaguide.library. The database now uses "black box" access
  methods, at least as far as amigaguide.library is concerned.

- Changed the way the cross reference database is maintained.
  Tree nodes are no longer removed, but updated if possible.
  This removes the need to rebuild the entire tree after a
  remove operation. However, because the new code may fail
  to update an existing node due to memory shortage, the
  database may (in case of error) not be in the expected
  state.

- When expunging all cross reference databases, DeletePool()
  is now preferred over freeing the individual database
  entries. If this doesn't work because an empty replacement
  pool is not available, the code still frees the individual
  database entries.

amigaguide 44.3 (15.3.1999)

- Fixed a race condition in database access.

- Reduced the use of the data cached from the initial
  layout call. Whenever necessary, the code now uses
  data from the GadgetInfo passed to it.

- Finally found out what the "reading from the wrong file"
  bug fix did: dynamic hosts will now properly tell the
  node loader which file to read.

- The layout code could end up leaving MultiView in an
  intermediate state if allocating and sending of the
  layout message to the node host went wrong. Fixed.

amigaguide 44.4 (19.3.1999)

- The tree node search had a comparison wired the
  wrong way round. Fixed.

amigaguide 44.5 (13.4.1999)

- Added more sanity checks to avoid rendering into stale
  RastPorts.

amigaguide 44.6 (13.4.1999)

- Fixed yet another Enforcer hit in the layout code. Will
  this never end?

amigaguide 44.7 (10.5.1999)

- Changed all __aligned attributes to a different method of
  guaranteeing long word alignment.

amigaguide 44.8 (8.6.1999)

- When trying to locate a file a link was pointing to, the code
  now, as a last resort, looks into the drawer the database is
  stored in the link came from.

- No longer attempts to optimize the rendering masks for clearing
  the display with. This fixes a bug where a previously displayed
  picture would not get erased from the display.

amigaguide 44.9 (17.7.1999)

- Control buttons are now rendered without presetting the button
  label background colour.

amigaguide 44.10 (1.8.1999)

- When locating a node, the library now tries to find the file
  in question both relative to the file the link command originated
  from and in the current directory of the calling process.

amigaguide 44.11 (3.8.1999)

- Tweaked the node location code even further. The library now looks 
  into 1) the calling process' current directory, 2) the parent 
  directory of the AmigaGuide file the first link came from, 3) the 
  parent directory of the AmigaGuide file the previous link came from. 
  I found that these three cases manage to cover all link scenarios we 
  had trouble with.

  Now that this is done, I really don't want to touch this code ever,
  ever again.

- Changed altogether too many "pr_Result2 = .." references to call
  SetIoErr() instead.

amigaguide 44.12 (14.8.1999)

- Dumped all the CurrentDir(currentDir = CurrentDir(ZERO)) tricks and
  switched them over to plain Lock("",SHARED_LOCK) calls.

amigaguide 44.13 (7.11.1999)

- The "SYSTEM" command, as used in hyperlinks, now launches the 
  respective programs with the current directory set to the drawer in 
  which the root document resides. The same is attempted for the "RX" 
  and "RXS" commands, but due to their asynchronous nature, it may not 
  work reliably.

amigaguide 44.14 (22.6.2000)

- The scanner did not recognize an '@endnode' command or any other 
  command like it, unless it was terminated with a line feed. The line 
  feed is no longer necessary, the end of the file will be sufficient.

amigaguide 44.15 (17.9.2000)

- Worked around another bug in the scanner, fixing an Enforcer hit. 
  The scanner bug essentially stays the same though: link commands 
  cannot be broken into several lines.

amigaguide 45.1 (23.11.2000)

- Found and fixed the bug that could cause the scanner to forget about
  certain nodes.

amigaguide 45.2 (15.2.2001)

- The mechanism that allowed quote characters to be escaped in 
  AmigaGuide command strings worked to a certain extent only. It 
  allowed for the quotes to be escaped but failed to strip the escape 
  characters from the resulting strings. Fixed.

- Fixed altogether far too many potential buffer overruns, including 
  some extremely weird cases of strings not getting terminated 
  properly resulting in really deadly and confusing buffer overruns.

- The recursive page layout code only worked because of an astonishing
  number of random events not happening most of the time. Basically, 
  it shouldn't have worked in the first place.

- Removed the calls to 'stcgfn()', 'stcgfp()' and 'stci_d()' which 
  were absolutely redundant.

amigaguide 45.3 (17.2.2001)

- The new code to parse path and file names didn't work that well 
  after all. Fixed.

amigaguide 45.4 (21.2.2001)

- The code to render the currently active button could leave a 
  variable uninitialized, which would lateron cause the button 
  rendering code to crash violently.

amigaguide 45.5 (22.2.2001)

- Modified the code that renders links again not to assume that after
  running off the end of the link list means that the currently active
  line needs updating. This avoids lines being printed twice during
  scrolling. Neat bug, eh?.

-------------------- AmigaOS 3.1.4.(1) project -----------------------

amigaguide 45.6 (8.3.2018)

- In case a requested node cannot be found, AmigaGuide delivers now
  at least an error code instead of just staying silent.

amigaguide 45.7 (1.9.2018)

- Amigaguide uses now the RVI from rexxsyslib.library V45 and no longer
  the static version from amiga.lib.

amigaguide 45.8 (10.9.2018)

- Fixes more race conditions on LibOpen. Forgot also
  to release libraries if LibOpen failed.

amigaguide 45.9 (16.9.2018)

- Forgot to accquire a semaphore on LibClose() and hence
  still had a race here.

------------------------ AmigaOS 3.2 project -------------------------

amigaguide 45.10 (4.8.2019)

- No longer uses CheckRexxMsg from amiga.lib which is clumsy.

amigaguide 45.11 (15.9.2019)

- Unused SNPrintf proto conflicted with utility.library V47's version.

amigaguide 45.12 (04.11.2019)

- Added one pixel to the height of navigation buttons so the text fits 
  nicely

amigaguide 45.13 (20.2.2020)

- Removed dependency on #include <localestr/amigaguide.h>. No 
  functional changes otherwise, but then you may never know...

amigaguide 47.14 (07.4.2020)

- Implement support for new text command @{IMG <path> <width> 
  <height>}
  It put the image on a line of it's own.
  It is paramount that the 3 arguments are given.

- Rearrange the controls on top to be more intuitive

- Add a "Forward" button so we can go forward in history too

amigaguide 47.15 (13.4.2020)

- Fix smartwrap layout of images

- Fix small visual glitches

- Change images tag to @{IMG <path>} as width and height is now 
  fetched from image

amigaguide 47.16 (22.4.2020)

- Fix a bug in the history system, where we would end up with broken 
  links to the pages we visited

- Fix a bug that could cause endless looping if the assign/volume of 
  an image is unavailable. Now we just fail silently to load the image

amigaguide 47.17 (7.5.2020)

- For links and images "guidedir:" is now a fake assign usable when 
  specifying paths

- Fix clearing of window with images and >= windowfull of scrolling

- Make clearing more efficient generally so we don't clear more than 
  once and not until needed

amigaguide 47.18 (13.5.2020)

- change the size of if "not found" image to be 8 x8 pixels (height 
  will actually be one textline high)

- Fix a bug if openeing images lower in height than lineheight

amigaguide 47.19 (13.6.2020)

- Oops I accidentially shared a dynamic string between all instances

- Never let the denominator in the page counter be 0

amigaguide 47.20 (17.6.2020)

- The path to the "amigaguide.h" catalog string descriptor header file
  in "amigaguidebase.h" should have been "///locale/catalogs/amigaguide.h",
  not "//locale/catalogs/amigaguide.h".

- Updated "asyncio.c" to use dos.library/SendPkt() in its local
  SendPacket() function instead of using PutMsg() instead.

amigaguide 47.21 (30.7.2020)

- Fixed: it was failing to open guides containing lines >= 4096 
  characters.

amigaguide 47.22 (17.8.2020)

- Add support for scrollwheel scrolling - this effectively adds it to 
  all of help

amigaguide 47.23 (13.11.2020)

- Fix a layout issue where links could disappear in combination with wrapping

amigaguide 47.24 (31.1.2021)

- When navigating back and forth through the history, the active (i.e.
  most recently selected) hyperlink of previously visited nodes would
  be forgotten. This caused retraced nodes to always have their first
  hyperlink shown highlighted, in place of the active one. Now fixed.

- The current horizontal and vertical view offsets would be forgotten
  as well, if the user had changed them while visiting a node already
  present in the history. Now fixed.

- Reworked the rendering of button bevels; it now always makes use of
  frameiclass for visual consistency, instead of drawing 3D frames by
  hand in some special cases. Also, button labels are no longer drawn
  in JAM2 mode, as that's not needed anymore and could disrupt future
  (or third-party) "theming" of system bevels.

- DTM_REMOVEDTOBJECT will now free any loaded pictures (but not their
  cache entries) to avoid getting into trouble later in OM_DISPOSE by
  trying to release pens of a screen that may no longer exist.
  Also, this ensures the pictures are properly remapped again in case
  the object is re-added to a window belonging to a different screen.

amigaguide 47.25 (3.4.2021)

- Active hyperlinks could have their background filled with the wrong
  color if it was not BACKGROUNDPEN when drawn inactive. Now fixed.
  Not really an issue on a clean system, but potentially so for users
  of third-party GUI enhancing patches (tsk, tsk).

Cross-references

Source: AmigaOS NDK 3.2 Release 4, Autodocs/amigaguide_dtc.doc, Include_H/datatypes/datatypes.h, ReleaseNotes/amigaguide-dt-RelNotes.