/* Documentation for the API of i++ V1.20     26.05.96-tl



Hi,



I'm glad that you are interested in supporting i++ in your application(s)!



i++ already became quite "famous" in it's short time of existence and

there are some users for whom i++ support is an essential criteria for

buying further applications. So I believe that everybody - you, I and most

important: the user - will benefit from this.



I think the API described here is quite straightforward and simple to use.

But if you encounter any problems feel free to send me an email with your

question on how to include i++ support in your application.





i++ (V1.10 or better) has two different API for third party applications:

1.) Suport the extended i-menue from any popup (i.e. for a "faked" i-button)

2.) Extend the list of special actions. This enables your application to be

present in most 2.0 apps.



By supporting the extended i-menu in your application the user will be able

to open other tools (i.e. a calculator, the in/out box or the styles palette)

from within your application.



When adding special actions of your own, your application is present in most

2.0 applications. I think this is particulary useful for "New item" entries.

An example for this is AddressAccess1.50 - my replacement of the built-in

names app. It adds two new special actions: "New person card" and "New company

card". Now the user can enter a new contact from within any application that

supports i++ by using the editor of AddressAccess (but without opening the whole

application).





Just a note before we get started: The sample code and related documentation

are provided "AS IS" and without warranty of any kind. They are provided as

freeware. You expressly acknowledge and agree that use this code/documentation

is at your sole risk. 



There is only one thing I'm asking for, if you use some of this sample code.

Please include a note (i.e. in your ReadMe) that your app supports i++ by

thorsten_lange@magicvillage.de (if there is space for a second sentence stating

what i++ does it would be really great - but this is not a must ;-)





In the following documentation ipp is a variable pointing to the baseView of i++

to be used as follows:

	local ipp:=GetRoot().|i++:TAL!|;

	if ipp then

		ipp:mTLpickCancelled();







1.) Displaying the extended i-menu

----------------------------------

The baseview of i++ provides three methods that enable you to iclude the extended

list in your application.





1.1) Before you show your popup call

- ipp:mTLgenInfoAuxItems(popupList):

	popupList: Array of popup items generated by calling app

					-	Array will be modified (so clone if necessary!)

					-	if you don't have any Items pass NIL

	return	: new/modified popupList-array including i++ menu items



1.2) After the user selected an item call (in your pickActionScript before your own processing)

-	ipp:mTLdoInfoAux(popupList, index, kAppSymbol)

	popupList: same array as returned by mTLgenInfoAuxItems

	index		: index of the item in popupList selected by the user

	kAppSymbol:your application symbol (ignored in the current version)

	return	: true=the item has been handled by i++, nil=item doesn't belong to i++



1.3) If the user cancels the popup call (in your pickCancelledScript)

-	ipp:mTLpickCancelled()	to free up some temporarily used variables of i++





As an example of the usage "protoTLinfoButton" is included. This is a "faked"

i-button with the same behaviour as the "real" one of NOS2.0 (there is only

one little difference: there is no 'pickseperator between About+Pref+Help and

the aux. items. You can use this proto if you like (but remember: use it at

your sole risk).









2.) Adding special actions to i++

----------------------------------



Add special actions to i++ consist of three steps:

2.1) Tell i++ that you have special actions for it.

2.2) If i++ prefs opens it asks you for a description of your actions so

that the user can select them from the upper list.

2.3) If the user taps on one of your items in the i-menu your app has to

perform the action.





2.1)

This text file can be included in your project. It provides two functions

to be called in your install/remove scripts.

InstallScript:

- call kRegIppFunc with (kAppSymbol)

	adds your appSymbol to the list of i++ supporting apps. This information

	is stored in the i++ prefs entry in the system soup.

RemoveScript:

- call kUnRegIppFunc with (kAppSymbol)

	removes your app from the list





2.2)

If you have called kRegIppFunc then i++ will call

	GetRoot().(yourAppSymbol):mTLgetIppSpecials()

yourAppSymbol is the symbol used as parameter in kRegIppFunc

This method should return an array describing your special actions.

Each action is described by a frame with (+: required ;  -: optional)

	+	uniqueSymbol: identifies this special action - use your appSymbol to ensure uniqueness

	+	name			: Appears in the popup and in i++ Prefs

	-	appSymbol	: Message is send to GetRoot().(appSymbol) oder nil=>directly to root

	+	message		: the method to call (symbol)

	-	paramArray	: Array of parameters for the method

	-	GetText		: Symbol of a method (no paramers; sent to appSymbol (must be non-nil))

						  Method is called when the user taps the i-button 

						  return the Text to be included in the i-menu (to allow state dependend text)

						  !!! GetText is only used by i++ V1.20 or better !!!



Note: The current version of i++ calls this only when opening i++ prefs

and stores the descriptor frame of each selected special action. So it

is not possible to dynamically change the parameters.



As an example the following code is taken from AddressAccess V1.50:

AddrAccBaseView.mTLgetIppSpecials:=

func()

begin

	return [

		{	appSymbol		: 'cardFile,

			uniqueIppSymbol: '|binames:addrAccess:TAL!|,

			message			: 'Toggle,

			name				: LocObj("",'app.ipp.binames)},

		{	appSymbol		: kAppSymbol,

			uniqueIppSymbol: '|newPerson:addrAccess:TAL!|,

			message			: 'mTLeditNewCard,

			paramArray		: ['person],

			name				: LocObj("",'app.ipp.newPerson)},

		{	appSymbol		: kAppSymbol,

			uniqueIppSymbol: '|newCompany:addrAccess:TAL!|,

			message			: 'mTLeditNewCard,

			paramArray		: ['company],

			name				: LocObj("",'app.ipp.newCompany)},

	];

end



2.3)

If the user selects your action the specified method is send

to the specified view. It's up to you to act accordingly ...



Maybe there will be some cool features of your applications 

accessible via i++? If so, tell me about it, and I will include

a note in the i++ ReadMe.



Best reagrds,

  Thorsten Lange

*/







// Register your app with i++

// When i++ displays the list of available special actions

// GetRoot().(regAppSymbol):mTLgetIppSpecials will be called

//	NOTE: - works only with ROM2.0

DefConst('kRegIppFunc,

func(regAppSymbol)

begin

	TRY

		if not GetGlobals().functions.GetAppPrefs

		or not GetGlobals().functions.EntryChangeXmit		

		then return nil;

		

		local prefs:=GetAppPrefs('|I++:TAL!|, {tag: "I++:TAL!"});

		

		if prefs.addSpecials then

		begin

			SetAdd(prefs.addSpecials,regAppSymbol,true);

		end

		else

			prefs.addSpecials:=[regAppSymbol];

		

		EntryChangeXmit(prefs,regAppSymbol);

		return true

	ONEXCEPTION |evt.ex| DO

		return nil;

end); // kRegIppFunc



// if kRegIppFunc returned true you have to clean up !

DefConst('kUnRegIppFunc,

func(regAppSymbol)

begin

	TRY

		if not GetGlobals().functions.GetAppPrefs

		or not GetGlobals().functions.EntryChangeXmit		

		then return nil;

		local prefs:=GetAppPrefs('|I++:TAL!|, {tag: "I++:TAL!"});

	

		if prefs.addSpecials then

		begin

			SetRemove(prefs.addSpecials, regAppSymbol);

		end;

	

		EntryChangeXmit(prefs,regAppSymbol);

		return true

	ONEXCEPTION |evt.ex| DO

		return nil;

end); // kUnRegIppFunc