LinkMaster: Developer's Guide

Navigation

News
Documentation
Applications
Downloads, mailing lists, and bug tracking are on the SourceForge Project Page

Introduction
Link-aware Applications
Link Containers
1. Create Link
2. linkAppLaunchReturnLink

1 Introduction

Adding linking capability to your app can be a very useful feature, and in most cases can be done with very little code. This document explains what you need to do to add this capability. You should also download the LinkMaster development kit, which includes sample code you can use in your app.

2 Link-aware Applications

To enable users to link from other applications to yours, your app must be link-aware. Link-aware apps support two extra launch codes and provide one extra menu command to the user.

2.1 linkAppLaunchRequestLink

LinkMaster will send this launch code to an application when the user selects the application via the "New Link" command. No parameters will be sent. The application is not required to behave specially in response to this launch code, but may for instance open in an index mode instead of viewing the previously edited record.

For example, you might add the following code to PilotMain:

else if (cmd==linkAppLaunchRequestLink) {
	error=StartApplication();
	if (error) return error;
	FrmGotoForm(ListView);
	EventLoop();
	StopApplication();
}

2.2 Publish Link

Your application should give the user the ability to publish links. The recommended means for this is a "Publish Link" command under the "Record" menu, but you are free to substitute a different means if it is more appropriate to your app. Your app should create a LinkInfoType structure, which consists of your app's 4-byte creator id, 60 bytes of app-dependant data, and an optional null-terminated string which can be used to identify this link.

Most apps will be linking to a record in a database, in which case the LinkSimpleType structure can be used. This structure is created by the function LinkSimpleNew in linkaware.c (in the development kit).

After creating the link data, it should be sent to LinkMaster with the LinkPublish function, also in linkaware.c.

For example, this is the code used in the event handler in a link-aware version of Memo Pad:

case PublishLinkCmd:
	fld=GetObjectPtr(EditMemoField);
	LinkPublish(LinkSimpleNew(MemoDB, CurrentRecord,
                    FldGetTextPtr(fld)));
	break;

2.3 linkAppLaunchFollowLinkSubCall

This code is sent to apps when the user follows a link. The simplest way to handle this launch code is with the following snippet:

case linkAppLaunchFollowLinkSubCall: {
	DmSearchStateType searchstate;
	UInt cardno;
	LocalID dbid;

	DmGetNextDatabaseByTypeCreator(true, &searchstate, 'appl',
				       my_creator_id, true,
				       &cardno, &dbid);
	SysUIAppSwitch(cardno, dbid, linkAppLaunchFollowLink, cmdPBP);
	break;
};

This code will convert the launch code to linkAppLaunchFollowLink, which is easier to handle. This works, but is inefficient if your app is already running when the user follows the link (this is only likely to happen with the history functions). If you would like to avoid this extra overhead, you should check launchFlags&sysAppLaunchFlagSubCall. If the flag is set, you can handle it in a similar manner to sysAppLaunchCmdGoTo (e.g. post a frmGotoEvent to the queue).

2.4 linkAppLaunchFollowLink

This code is sent to applications when the user follows a link. The parameter block consist of the LinkInfoType structure that defines the link. The application should display the record indicated by the link.

If you use the LinkSimpleType structure, you can use LinkSimpleToGoToParams function to convert the LinkInfoType to GoToParams, which you should already handle in your support for the system find command. LinkSimpleToGoToParams returns NULL if the link points to a non-existant record.

For example, you might add the following code to PilotMain:

else if (cmd==linkAppLaunchFollowLink) {
	GoToParamsPtr gotoparams;
	gotoparams=LinkSimpleToGoToParams((LinkSimpleInfoPtr)cmdPBP);
	error=StartApplication();
	if (error) return error;
	if (gotoparams) {
		GoToItem(gotoparams, true);
		MemPtrFree(gotoparams);
	} else
		FrmGotoForm(ListView);
	EventLoop();
	StopApplication();
};

2.5 Link0001 resource

Link-aware applications should make themselves known to LinkMaster for the New Link dialog. This is done by including a resource with type 'Link' and number 0001 in the application. The first byte of this resource should be a letter indicating the version of the LinkMaster protocol this app supports. For this version, it should be 'a' (0x61).

This resource can be created with the GNU tools by adding the line echo -n a > Link0001.bin to your Makefile just after the call to pilrc.

2.6 History

LinkMaster maintains a global history list that lets users return to recently viewed items. To add an entry to the history list, pass a LinkInfoPtr representing the current item to LinkHistoryPush() (this pointer should be allocated with MemPtrNew). If you would like to provide back/forward buttons in your application, use LinkBack() and LinkForward(). Link{Back,Forward}Check() will return true if LinkMaster is present and there is room to move in the given direction.

3 Link Containers

Making your app a link container is more difficult than making it link-aware, as there is no simple cookbook recipe for doing so. (Note: it is legal for an app to be a link container without being link-aware. In this case, you should not use the Link0001 resource)

3.1 Create Link

Your app needs to give the user the ability to create a link, through a menu command or whatever is appropriate to the app. The app should signal LinkMaster with the LinkRequest function in linkaware.c. You must pass a LinkInfo structure which specifies the place where the link will be inserted (LinkSimpleType structures can be used here as well).

3.2 linkAppLaunchReturnLink

After the user has selected a link, LinkMaster will launch your app with this code. The parameters consist of two LinkInfoType structures - the one passed with LinkRequest and the one chosen by the user - and a string describing the link (this string will always be present). Your app should store the new link (bytes 65-128) and optionally the string for future use, in the place indicated by the first LinkInfo. When the user activates the link, pass the LinkInfo structure to the FollowLink function in linkaware.c.

Hosted by SourceForge