Netscape Plug-In Development on Mac OS

Why such a page ?

There are various reasons to the existence of this page :

It's not obvious to find the good links on Netscape's web site to retrieve the SDKs and the documentation.
The documentation forgets to mention or doesn't insist on certain points specific to the Mac. It's just because it's a multi-platform documentation.
The documentation doesn't deal with problems you meet when you're developing a Plug-In on Mac OS.
The documentation doesn't deal with the incompatibilities between Microsoft Internet Explorer and Netscape Communicator in the Plug-In Area.
Last, one more page on my site :-)

Which Browser supports Plug-In ?

Netscape Navigator 2.x (and later) and Netscape Communicator
Internet Explorer 3.x (and later)
iCab (Early support)

I didn't check the Hot-Java and Opera Browsers. The first one is a piece of sh.. on Mac OS, the later is not available yet.

Where can I find the Software Development Kit (SDK) and the Documentation ?

First, you must know that there are two versions of the SDK :

The 3.0 SDK :
It's the oldest. It includes projects for prehistoric CodeWarrior version (7.0 or 8.0) that can't be used with the most recent version of CodeWarrior (Pro x).
The 4.01a SDK :
It's the most recent one. It includes projects that can be converted with recent versions of CodeWarrior Pro. Yet, this SDK contains some APIs that are only compatible with the fourth versions of the Browsers (Explorer 4.0 and Communicator 4.0) If you wish to make your plug-in work with older versions, you can still use that SDK, just don't call these new APIs (they are so really so great IMHO).

To sum-up :

Download the 4.01a SDK.

Now, the documentation. Here again, we have two versions :

A HTML version
A PDF version

I strongly recommend reading the documentation, it sheds light on some completely dark points in the SDK and sample codes.

For my part, I prefer the PDF version that doesn't kill my eyes when I'm reading it.

To sum-up :

Download the PDF documentation.

Where do I start from, now ?

The easiest and nicest way is to first compile a sample project included in the SDK.

If you already have downloaded the 4.01a SDK, just open the Macintosh Simple Project. Compile it and put an alias of the Plug-In in the Netscape Communicator Plug-In folder.

Do not try to put it in Internet Explorer Plug-In folder ! If you try to use that Plug-In in Internet Explorer, Internet Explorer will crash. You do not want that to happen, do you ?

After playing for a while with this Plug-In, it's high time for you to face the bad reality of life.

To develop a Plug-In, it's a good idea to start with the MacTemplate project sources ; for two good reasons :

The source code is commented, pretty cool uh ?
This project doesn't support LiveConnect. I quickly came to the fact that getting off LiveConnect code is a boring task. Trust me when I say that you probably won't want to support LiveConnect in your Plug-In.

Some little modifications are needed to make the project compile but, well, you're a true developer, aren't you ?

Where do I put my Plug-In ?

In the Browser Plug-In folder, of course... DON'T DO THAT !

Instead, put an alias of your Plug-In the the Browser Plug-In folder. This will allow you to have only one real Plug-In for every Browsers: good bye Version Management. Evenmore, this will allow you to compile a new version of the Plug-In and not have to put it every time at the good location.

How do I draw in a Plug-In ?

If you want to create a Plug-In, it's usually to draw somthing inside the Browser Window (except for Audio Plug-In, I don't see what kind of Plug-In would draw nothing. Hum, Virus may be ?).

When it comes to drawing, you can have a look at the code in the MacShell.cpp file. Indeed, when you're drawing, you must set your drawing context and later restore the former drawing context.

If you're like me, a curious guy or a first-class life sucker, you will wonder what is inside the NP_Port and NPWindow structure.

Some hours of debugging at candles light gave me some answers that you can't find in the documentation. They are not obvious to remember (while I'm writing these lines, I have to read the code to check).

First, all drawings are clipped. This is done with the clipRect parameter of the NPWindow structure and the portx and porty parameters of the NP_Port structure.

The portx and porty datas are also used to define the new QuickDraw origin for the Plug-In.

The width and height parameters of the NPWindow structure indicate the Plug-In dimension.

What is the exact puprose of the x and y coordinates of the NPWindow structure ? They are the actual corrdinates of the top-left corner of the Plug-In.

If you want to manage an OpenGL view inside a Plug-In, be aware that it's a nightmare the first time you code it.

Another important point concerns resizing and scrolling.

You get aware of a resizement with a new call to the NPP_SetWindow function.

For scrolling, you're never informed. You will just notice that the NPWindow and NP_Por values have changed when you receive an update Event. So beware.

How do I manage Keyboard Events and the cursor ?

If you're using the SDK sample code to write your plug-in and you implement keyboard management on keydown events, surprise ! No keyboard input is taken into account. You can debug your code and you will quickly come to the point, that you're not receiving the keyDown and keyUp Events.

In fact, if you read the documentation (it's quite hard to find this part of the documentation), you will learn the following things :

On Mac OS, Mouse, Keyboard, Update Events are managed with the NPP_HandleEvent function. This function supports the majority of traditional Mac OS Events and 3 more ones :

getFocusEvent
loseFocusEvent
adjustCursorEvent

On the getFocusEvent Event, you must set the return value of NPP_HandleEvent to true to tell the Browser that your Plug-In support Keyboard focus and will manage keystrokes when it has the Focus.

For the cursor, it's a bad idea to use the qd global. Use the gQDPtr that is obtained during the Plug-In initialization.

Once your code supports these 3 events, you will be able to manage Keyboard Events and Cursor Modification.

How do I read my Plug-In resources ?

With the gResFile value, you have a local File Reference on your Plug-In Resource Fork. This data is defined in the npmac.cpp file.

Just call UseResFile with this value and here you are.

How do I debug a Plug-In ?

If you're only developing perfect code, jump to the next section. But you must know that I hate you.

With CodeWarrior, it's quite easy to debug a Plug-In (which is actually just a Shared Library). In the Project Preferences Panel, section Target, select the Runtime Settings option.

With the Choose... button, you can set-up the binary that will launch your Plug-In. So select Internet Explorer or Netscape Communicator.

What you have to do next, is to launch the debugger, and drag and drop the HTML page that calls your Plug-In in the Browser window.

Personal note : During my various attempts with iCab, I never succeeded in making this work.

Internet Explorer Incompatibilities (or every thing you wanted to know about Plug-In developement and didn't dare to ask)

You've just succeeded in compiling your insanely great Plug-In and tested it with Netscape Communicator. You are the Best, you're going to meet your manager and ask for a bonus or even become the CEO of your firm.

STOP !

Before comitting a Professional suicide, check that your plug-in works with Internet Explorer.

I'm sorry my lady, but we're living in a nasty world (I don't even speak of those satellites all around Earth disturbing the weather), Internet Explorer doesn't support all the functionalities of the SDK.

The various incompatibilites I have listed with Internet Explorer 4.5 and later :

Internet Explorer doesnt' support LiveConnect
Why ? Because Internet Explorer doesn't support JavaScript to Java communication and maybe because LiveConnect is cool.
Conclusion : If you want your Plug-In to work with Internet Explorer, forget about LiveConnect. On the NPP_GetJavaClass function, return NULL.
Internet Explorer doesn't support the StreamAsFileOnly option
Within a Plug-In you can stream datas under 3 forms. One of which is to ask to be only warmed when the stream is finished and the local file is complete
This functionality doesn't work on Internet Explorer, which instead allows you to have a normal streaming. This means that when you ask the browser to download a file, every time a portion of this file has been downloaded, you will be warmed by a call to the NPP_Write function.
Once all the file has been downloaded, the NPP_StreamAsFile is called and Internet Explorer tells you the location of the local file (This file is not in the browser cache).
Conclusion : Avoid using StreamAsFileOnly if you can. Yet if you have to, be aware that on Internet Explorer, the file will be streamed as StreamAsFile.
Internet Explorer doesn't send keyUp Event
Internet Explorer only sends you keyDown Events.
Conclusion : Design your Key management so that it only uses keyDown Events.
Differences between Internet Explorer 4.5 and 5.0
Internet Explorer 4.5 doesn't support NPP_GetURLNotify.
Internet Explorer 5.0 does.
Internet Explorer 4.5 supports one Stream a time
Apparently, Internet Explorer 4.5 doesn't support simultaneous multiple streams. If you're calling several times NPN_GetURL (since IE 4.5 doesn't support NPN_GetURLNotify), all but one stream will be destroyed immediatly.
Conclusion : Do sequential streaming with IE 4.5.

To sum-up :

Beware Internet Explorer and other Browsers. The fact that your plug-in is working with Netscape Communicator doesn't mean that it will work with other Borwsers.

Other informations

Don't use __terminate as a Termination Entry Point in the PPC Linker. This call is conflicitng with the __destroy_global_chain function when you're disposing the last instance of your plug-in.
Don't use the Thread Manager. Netscape doesn't like it.

Sample Source code

The source code MacTemplate is amodified version of the sampleCode MacTemplate.

It's a CodeWarrior Pro 5 Project.

The Plug-In draws the clipping region in Blue, the Drawing area in Red.
The Plug-In supports Keystrokes.