AmigaGuide Library - Revision history

Costel Mincea: Text replacement - "" to ""

2025-01-26T19:09:12Z

Text replacement - "<syntaxhighlight>" to "<syntaxhighlight lang="C" line>"

← Older revision		Revision as of 19:09, 26 January 2025
Line 21:		Line 21:
	Just like other AmigaOS libraries, the AmigaGuide Library must be opened and its interface obtained before use:		Just like other AmigaOS libraries, the AmigaGuide Library must be opened and its interface obtained before use:

	<syntaxhighlight>		<syntaxhighlight lang="C" line>
	struct Library *AmigaGuideBase = NULL;		struct Library *AmigaGuideBase = NULL;
	struct AmigaGuideIFace *IAmigaGuide = NULL;		struct AmigaGuideIFace *IAmigaGuide = NULL;
Line 44:		Line 44:
	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:		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:

	<syntaxhighlight>		<syntaxhighlight lang="C" line>
	int32 ShowAmigaGuide(STRPTR docName, struct Screen *scr)		int32 ShowAmigaGuide(STRPTR docName, struct Screen *scr)
	{		{

Daniel Jedlicka at 10:00, 21 February 2014

2014-02-21T10:00:46Z

← Older revision		Revision as of 10:00, 21 February 2014
Line 13:		Line 13:
	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.		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 ~~more general~~ term ''AmigaGuide ~~files~~'' ~~throughout this document~~.		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 ~~file~~ ready for display and messaging is called a ''client''. The client is displayed in a ''client window''.		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 =		= Library Opening =
Line 38:		Line 38:
	= Client Initialization and Opening =		= Client Initialization and Opening =

	A special data structure – ''struct NewAmigaGuide'' – needs to be declared and initialized to describe the ~~file~~ 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 ~~file~~, which you must keep to be able to manipulate and (later) close the client. The handle is of an opaque type ''AMIGAGUIDECONTEXT''.		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 ==		== Synchronous Use ==

	The easiest (but perhaps the least useful) way to open an AmigaGuide ~~file~~ 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 ~~file~~:		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:

	<syntaxhighlight>		<syntaxhighlight>
	int32 ~~ShowAmigaGuideFile~~(STRPTR ~~name~~, struct Screen *scr)		int32 ShowAmigaGuide(STRPTR docName, struct Screen *scr)
	{		{
	struct NewAmigaGuide nag = {NULL};		struct NewAmigaGuide nag = {NULL};
Line 53:		Line 53:

	/* Fill in the NewAmigaGuide structure. */		/* Fill in the NewAmigaGuide structure. */
	nag.nag_Name = ~~name~~; // including complete path name		nag.nag_Name = docName; // including complete path name
	nag.nag_Screen = scr; // pointer to the screen to open on, or NULL for Workbench		nag.nag_Screen = scr; // pointer to the screen to open on, or NULL for Workbench

	/* Open the AmigaGuide client */		/* Open the AmigaGuide client */

Daniel Jedlicka: Added "Naming Conventions" and "Client Initialization and Opening"

2014-02-20T23:34:55Z

Added "Naming Conventions" and "Client Initialization and Opening"

@@ Line 8: / Line 8: @@
 * internal messaging;
 * ARexx interface.
 = Library Opening =
-Just like other AmigaOS libraries, the AmigaGuide Library must be opened and its interfaces obtained before use:
+Just like other AmigaOS libraries, the AmigaGuide Library must be opened and its interface obtained before use:
 <syntaxhighlight>
@@ Line 27: / Line 35: @@
+}
 </syntaxhighlight>

Daniel Jedlicka: Created page with "= Introduction = AmigaGuide is a [http://en.wikipedia.org/wiki/Hypertext hypertext] system widely used in AmigaOS, and AmigaGuide Library provides a way for developers to add..."

2014-02-20T00:54:24Z

Created page with "= Introduction = AmigaGuide is a [http://en.wikipedia.org/wiki/Hypertext hypertext] system widely used in AmigaOS, and AmigaGuide Library provides a way for developers to add..."

New page

= Introduction =

AmigaGuide is a [http://en.wikipedia.org/wiki/Hypertext 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.

= Library Opening =

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

<syntaxhighlight>
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 */
}
</syntaxhighlight>