AmigaGuide Library

Introduction

AmigaGuide is a hypertext system widely used in AmigaOS, and AmigaGuide Library provides a way for developers to add interactive help to their applications. The library offers the following main features:

• text displayed in a synchronous or asynchronous window;
• context-dependent help;
• dynamic hosts allowing applications to incorporate context-sensitive or "live" project data within their help systems;
• internal messaging;
• ARexx interface.

Naming Conventions

At the time when AmigaGuide was devised (early 1990s), the term online help was frequently used to describe the type of help provided from within applications. However, with the emergence of the Internet the term acquired a meaning that no longer tallies with what AmigaGuide really does (AmigaGuide has no connection capability, it cannot "go online"). This is why in this documentation we use the term interactive help instead.

Files in the AmigaGuide format tended to be referred to as databases in older documentation. This is, again, a rather confusing term because there is no resemblance to "real databases" as used in SQL, Oracle etc. systems. We will, therefore, stick to the better-fitting term AmigaGuide documents here.

A successfully initialized and opened AmigaGuide document, ready for display and messaging, is called a client. The client is displayed in a client window.

Library Opening

Just like other AmigaOS libraries, the AmigaGuide Library must be opened and its interface obtained before use:

struct Library *AmigaGuideBase = NULL;
struct AmigaGuideIFace *IAmigaGuide = NULL;
 
if ( (AmigaGuideBase = IExec->OpenLibrary("amigaguide.library", 52)) )
  {
   IAmigaGuide = (struct AmigaGuideIFace *)IExec->GetInterface(AmigaGuideBase, "main", 1L, NULL);
  }
 
if ( !AmigaGuideBase || !IAmigaGuide )
{
   /* handle library opening error */
}

Client Initialization and Opening

A special data structure – struct NewAmigaGuide – needs to be declared and initialized to describe the document and the context in which it is to be displayed (such as the Intuition screen to open the client window on). A pointer to the initialized structure is then passed to one of the library's opening functions, OpenAmigaGuide() or OpenAmigaGuideAsync(). The function will return a handle to the respective document, which you must keep to be able to manipulate and (later) close the client. The handle is of an opaque type AMIGAGUIDECONTEXT.

Synchronous Use

The easiest (but perhaps the least useful) way to open an AmigaGuide document is to call the OpenAmigaGuide() function, which opens the client in synchronous ("blocking") mode. When called, OpenAmigaGuide() also opens a client window and displays the document:

int32 ShowAmigaGuide(STRPTR docName, struct Screen *scr)
{
 struct NewAmigaGuide nag = {NULL};
 AMIGAGUIDECONTEXT    agHandle = NULL;
 int32 retVal = 0L;
 
 
 /* Fill in the NewAmigaGuide structure. */
 nag.nag_Name   = docName;    // including complete path name
 nag.nag_Screen = scr;        // pointer to the screen to open on, or NULL for Workbench
 
 /* Open the AmigaGuide client */
 if ( (agHandle = IAmigaGuide->OpenAmigaGuide(&nag, NULL)) )
  {
   /* Close the AmigaGuide client */
   IAmigaGuide->CloseAmigaGuide(agHandle);
  }
 else
  {
   /* Get the reason for failure */
   retVal = IDOS->IoErr();
  }
 
 return retVal;
 
}

As you can see, the function (and the program that has called it) waits until the AmigaGuide client shuts down, which in real life means until the user (or an ARexx command) closes the client window. This is not very practical for interactive help, because a modern application should never become blocked by an opened help window. Most application programmers will, therefore, want to use AmigaGuide asynchronously.

Asynchronous Use

(to be continued)