• TotalTerminal has replaced Visor
• Mac OS X Lion has been released

TotalTerminal changes up the way it launches Terminal — instead of being automatically injected via SIMBL, it manually injects the plugin into Terminal.app. Well, I wasn’t going to let this deter me.

Getting back to Nirvana after installing TotalTerminal is not all that bad. Most of the steps haven’t changed from my original post so I will only go into detail about the new steps here. Briefly, here are the steps I followed.

1. Remove TerminalColours.bundle SIMBL plugin — per the TotalTerminal FAQ, it injects its own version and having TerminalColours.bundle installed creates a conflict. (~/Library/Application\ Support/SIMBL/Plugins)
2. Fix the Home / End keys (see original post)
3. Copy Terminal.app to VisorTerminal.app (see original post)
4. Install TotalTerminal
5. Modify TotalTerminal to use VisorTerminal.app instead of Terminal.app

That’s right, there’s really only one thing to change, and it’s very simple

TotalTerminal.app has a simple, compiled AppleScript which launches Terminal and injects itself. The compiled file is located at /Applications/TotalTerminal.app/Contents/Resources/Scripts/main.scpt. But, we don’t want the compiled binary version, we want the original so we can make it use VisorTerminal.app.

Fortunately the uncompiled source file is available in the TotalTerminal repo on Github.

Only one change is necessary.

--- TotalTerminal.app/Contents/Resources/Scripts/main.applescript
+++ TotalTerminal.app/Contents/Resources/Scripts/main.applescript
@@ -1,4 +1,4 @@
-tell application "Terminal"
+tell application "VisorTerminal"
        delay 1 -- this delay is important to prevent random "Connection is Invalid -609" AppleScript errors
        try
                event BATTinit

Once that is done, you just need to compile the script and replace the one that shipped with TotalTerminal.

$ osacompile -o main.scpt main.applescript
$ mv main.scpt /Applications/TotalTerminal.app/Contents/Resources/Scripts

That’s it.

You should be good to go. Put TotalTerminal.app into your user startup applications if you wish (I do), or launch it manually by launching TotalTerminal.app.

Enjoy the restoration of terminal nirvana.

For the lazy…

My modified and compiled main.applescript is available for download.

Note 1: The method described here should also work in Mac OS X Leopard or Tiger, just get the appropriate versions of SIMBL / Visor.
Note 2: If you don’t want everything on my bullet list, just follow the steps appropriate for what you want to accomplish.
Note 3: I have provided .patch files, etc. at the bottom of the post for those who, like me, are a bit lazy.

What is Terminal Nirvana?

As a developer, Terminal is one of my best friends. Maybe you can relate. I have constantly been in search of the ultimate Terminal configuration, and it has ever eluded me… until now.

But what is Terminal Nirvana? Here are my criteria:

1. I want the Home / End keys to move the cursor to the front / end of the line. I grew up on Windows, and I like the keys to function this way. To me, it just makes sense. Unfortunately, KeyFixer doesn’t work in Terminal (but I highly recommend it for changing the behavior in most other apps!).
2. I don’t want Home / End to behave differently when I am in a screen session. I use screen all the time, and Home / End need to behave consistently.
3. I don’t want Home / End to do unexpected things in VIM – ever. Pressing Home / End in VIM should, at the very least, not do weird things like delete lines, whether I am in a screen session or not.
4. I want my terminal window available at all times. With as much as I use the terminal, opening Terminal.app all the time feels wasteful. There should be a better way. This is where SIMBL and Visor come in.
5. I don’t want it to show up in the Dock, or in my Command + Tab list. As useful as Terminal is, there are a lot of other useful applications around, and I use a lot of them. Since I always want Terminal open anyway, it is annoying to constantly avoid / ignore / tab over it when I am using Command + Tab to switch to another running application. Oh, and it should stay away from my Dock, too.
6. I want good, configurable colors in my shell. Fortunately, Visor takes care of this one by including TerminalColours as part of the package, so you get this one “for free.”

Sound like a tall order? It took me a few hours crawling around the web and experimenting to come up with a good solution, but I managed it in the end. Hopefully my experience can help save a few people some time in the future.

This is how I did it.

First things first

Before you go any further, make sure you have installed SIMBL and Visor. The latest versions work great in Snow Leopard with a 64-bit Terminal.app, so knock yourself out.

Home / End keys

To change the Home / End keys in Terminal.app, you are going to need to go to Terminal -> Preferences -> [Settings] -> [Keyboard]. Remember, settings are profile-specific, so you will need to make the changes to any profiles you care about. (Note: Visor uses the “Visor” profile, regardless of what you set as your default profile. What I do is rename the automatically-created “Visor” profile, configure my default profile, and then duplicate it with the name “Visor”.)

The first thing I tried was changing the keybindings to “\001″ and “\005″ per the instructions I found on Ricky Campbell’s blog. This seemed to make sense; CTRL+A and CTRL+E move the cursor to the front / end of the line in Terminal. And I thought it was working perfectly, for a few glorious moments…

Unfortunately, CTRL+A is also the key combination to start a command in screen. So when I launched screen, suddenly my home key didn’t work anymore, and I randomly started sending screen commands when I used it.

I also tried using a ~/.inputrc file and the keybindings “\033[1~” and “\033[4~” as discussed on two blogs I stumbled across while looking for an alternate solution. Now, I really thought I had the problem licked. Except, Home / End did weird things in VIM running within a screen session, and the necessity of using an additional .inputrc file was just a bit of a bummer.

Turns out Shift + Home and Shift + End  already did what I wanted, so the simplest solution of all is to just copy those keybindings already present in the Terminal settings. For good measure, I copied the “shift page up” and “shift page down” bindings to “page up” and “page down.” (Note: you can either copy-paste the existing values, or hit ESC to get the \033 value and then type the other characters manually.)

Terminal key bindings:

• home
  • Value: \033[H
• end
  • Value: \033[F
• page up
  • Value: \033[5~
• page down
  • Value: \033[6~

Fixing VIM in screen

Okay, almost there with the keybindings. If you run VIM inside a screen session, you will notice that Home deletes the current line, and using the arrow keys while in insert mode inserts A / B / C / D rather than moving the cursor. Not good.

A little tweak to your existing ~/.vimrc file will fix it right up (or, if you don’t have an existing ~/.vimrc, create it). (Note: the easiest way to get the proper escape characters is to enter insert mode, and hit CTRL+V followed by the Home or End key. This will add the ^[ escape character, as well as the [F or [H characters. Do the same thing for CTRL + O to get the ^O escape character.) By using CTRL+O on the imap lines, we make the Home / End keys work the same way in insert mode or command mode.

As an added bonus, this fixes the arrow keys while in insert mode. Though, to be honest, I have no idea why…

""" ~/.vimrc
 
""" Fix home and end keybindings for screen
map ^[[F $
imap ^[[F ^O$
map ^[[H g0
imap ^[[H ^Og0

Making Terminal always available

This one was actually pretty simple. Using SIMBL and Visor (both compatible with 64-bit Terminal at the time of this writing) you can get Terminal to dock to the top / side / bottom of your screen, and configure it to open with a keystroke you can define.

My keystroke is Command + Esc (turn off Front Row first, if you hate it as much as I do). Once Terminal has been launched for the first time (thus creating the Visor window), this keystroke gets you in from anywhere, or hides it when you are done.

Hiding the Dock icon, and removing Terminal from the Command + Tab list

This is the most involved step, but it also provides one of the biggest benefits in my mind. Most of the information here comes from a MetaSkills blog article.

In order to accomplish this, the LSUIElement key in Terminal’s Info.plist must be set to “1″. This disables the Dock icon and removes the application from the Command + Tab list. Don’t want to completely prevent Terminal from ever functioning like a normal application? The quick solution is to create new application “VisorTerminal.app” which is used for Visor, while leaving Terminal.app alone to function as normal. (This is actually a good thing, because another side-effect of setting LSUIElement : 1 is you no longer have anything change in the menubar when you are in your application… ie, you can’t click on VisorTerminal next to the Apple icon, and go into Preferences.)

Create a new VisorTerminal.app

Duplicate the existing Terminal.app.

cp -r /Applications/Utilities/Terminal.app /Applications/Utilities/VisorTerminal.app

Once you have duplicated Terminal.app, you need to change a few bundle identifiers in your new application so the two appear as distinct entities to Mac OS X. In other words, change “Terminal” to “VisorTerminal” in a few places. This is also when you add LSUIElements : 1.

<!-- /Applications/Utilities/VisorTerminal.app/Contents/Info.plist -->
...
<key>CFBundleDisplayName</key>
<string>VisorTerminal</string>
...
<key>CFBundleIdentifier</key>
<string>com.apple.VisorTerminal</string>
...
<key>CFBundleName</key>
<string>VisorTerminal</string>
...
<!-- Note: Put this right before the closing </dict></plist>
     at the end of the file -->
<key>LSUIElement</key>
<string>1</string>
...

At this point, rather than entering my preferences all over again, I elected to copy my Terminal.app preferences. Repeat this step any time you make preference changes that you want to copy over. (Note: using a symlink does not seem to work. If you make changes while in VisorTerminal, such as changing the Visor hotkey, the modified file is saved over your symlink.)

cp ~/Library/Preferences/com.apple.Terminal.plist ~/Library/Preferences/com.apple.VisorTerminal.plist

Modify Visor to use VisorTerminal.app

Once your new application is created and ready to go, you need to tell Visor to activate for that application rather than Terminal.app. Apply the following very familiar tweaks to Visor’s Info.plist:

<!-- ~/Library/Application\ Support/SIMBL/Plugins/Visor.bundle/Contents/Info.plist -->
...
<key>BundleIdentifier</key>
<string>com.apple.VisorTerminal</string>
...
<key>ExecPattern</key>
<string>*/VisorTerminal.app/Contents/MacOS/Terminal</string>
...
<key>BundleIdentifier</key>
<string>com.apple.VisorTerminal</string>
...

Once this last step is done, you are almost there. Make sure Terminal.app and VisorTerminal.app are both closed. Now, launch VisorTerminal.app and behold its wonder!

open /Applications/Utilities/VisorTerminal.app

What? It didn’t work?

Let me guess. A Terminal window opened, but Visor didn’t take effect. What gives? (You may have also noticed that you don’t have an entry in your menubar… see above.)

Turns out newer versions of SIMBL don’t activate in applications with LSUIElement : 1. Apparently this is expected behavior due to the Cocoa event mechanism. But all is not lost!

You can manually inject SIMBL into an application using Apple Script.

tell application "VisorTerminal"
	inject SIMBL into Snow Leopard
end tell

Great, but I don’t want to do something manually every time I want a Visor window. I just want it to always be there, remember?

Use the AppleScript Editor to save this snippet as an application, and then include that application in your user startup items. Voila! When you log in, the AppleScript helper executes, which launches VisorTerminal with SIMBL injected. Visor activates, your terminal automatically hides itself, yet is always there when you want it with the push of a button. It doesn’t clutter up your Dock, your application switching, and you can still use Terminal.app as usual whenever it makes sense to do so.

Final thoughts

First off, note that this tutorial was written using SIMBL 0.9.7a, Visor 2.2, and Terminal 2.1.1 (273) on Mac OS X Snow Leopard 10.6.4. YMMV.

Secondly, my thanks to all the people who are smarter than me and figured all this out. All I did was put things together.

Third, see below for patch files and my AppleScript application.

Finally, does anyone have the following issue, and know a way around it? After setting my key bindings, when I launch Terminal for the first time, they don’t take effect. Home does nothing special. If I open a new Terminal window, the home key starts working as expected, both in the new window as well as the original window. This happens to me whether I use \001 for the control character (and this without a ~/.inputrc file) or if I use the solution described above. Slightly bothersome, but since I almost always use my Visor terminal (which doesn’t exhibit the same problem… nor did it using Visor sans any modifications discussed here) I don’t notice it too often.

Patch files: http://gist.github.com/484082
AppleScript app: HiddenVisorTerminal.zip

Getting help: For a better place to ask NPAPI-related questions, check out the FireBreath Forums. Yes, there is a forum there for NPAPI plugins that don’t use FireBreath as well.

Previous posts

The purpose of this post is to cover the basics of providing an interface by which javascript can interface with an NPAPI plugin in a cross platform manner.  The primary focus of this post will be on npruntime, which is recommended by the Mozilla development team (or at least seems to be from the meager and confusing documentation available from Mozilla).  More importantly, of course, it is the framework that I recommend, which is all-important, since I’m the one writing this post. =]

Previous posts

If you are new to NPAPI plugins, you may want to go back and read part one and part two of this series, which cover the basic architecture and lifecycle of an NPAPI plugin.

What is npruntime?

I’m so glad you ask.  This confused the daylights out of me when I first got into building browser plugins; there are references to XPCOM and references to LiveConnect and references to NPRuntime, which I never did quite get straightened out until I ran into a Wikipedia article on NPAPI.  I recommend that you read it if you want further background information.

Beyond the simple question of “what is recommended?” is the consideration of practical needs.  For me, the primary considerations that led me to decide that NPRuntimeis the only mechanism that should be used on any new plugin are:

• NPRuntime allows dynamic interfaces — more on this, and why it is useful, later
• NPRuntime is the plugin scripting standard supported by Mac Plugins, Safari (even on windows), Chrome, and Opera.  My goal is always to make things as cross-platform as possible.
• Firefox 3.6 drops support for XPCOM plugins (e.g. xpt file scripting interfaces aren’t recognized)

Getting Started

Throughout this post, I will be referring to Scriptable Objects a lot.  A Scriptable Object is simply an object that can be “scripted”, or accessed and used by javascript.  In firefox, a Scriptable Object is always a NPObject:

struct NPObject {
  NPClass *_class;
  uint32_t referenceCount;
  /*
   * Additional space may be allocated here by types of NPObjects
   */
};

As you can see, a NPObject is nothing more than a reference counted object with a pointer to a NPClass.  As of the latest (as of this writing) Gecko SDK, 1.9, NPClass is defined as follows:

struct NPClass
{
  uint32_t structVersion; // Version of the structure (to determine which features may be missing)
  NPAllocateFunctionPtr allocate; // Called to create a new instance of this object
  NPDeallocateFunctionPtr deallocate; // Called to free the instance of this object
  NPInvalidateFunctionPtr invalidate; // Called on live objects that belong to a plugin instance that is being destroyed. This call is always followed by a call to the <code>deallocate</code> function, or <code>free()</code>. Any attempt to use an invalidated object will result in undefined behavior.
  NPHasMethodFunctionPtr hasMethod; // Called to query if a method exists on the NPObject
  NPInvokeFunctionPtr invoke; // Used to invoke a method on the NPObject
  NPInvokeDefaultFunctionPtr invokeDefault; // Used to invoke the NPObject as a function
  NPHasPropertyFunctionPtr hasProperty; // Called to query if a property exists on the NPObject
  NPGetPropertyFunctionPtr getProperty; // Called to get the value of a property on the NPObject
  NPSetPropertyFunctionPtr setProperty; // Called to set the value of a property on the NPObject
  NPRemovePropertyFunctionPtr removeProperty; // Called to remove/delete a property on the NPObject
  NPEnumerationFunctionPtr enumerate; // Used to get a list of properties and methods that exist on the NPObject (new in FF 3, Gecko SDK 1.9)
  NPConstructFunctionPtr construct; // Used when the new keyword is called in javascript to create a new instance of the NPObject (new in FF 3, Gecko SDK 1.9)
};

Making it Object Oriented

The Gecko SDK is intentionally written to use structs instead of objects; this allows it to work across many platforms, with many different types of compilers, and never worry about binary compatibility.  If you haven’t figured it out yet, the NPClass structure contains a list of function pointers that should be called by the browser (or anyone else) to talk to the NPObject.  These should never be called explicitly, but rather they should be called through the NPN_ functions that I briefly mentioned towards the end of part one.  When one wishes to create a new instance of an NPObject, you call the NPN_CreateObject function and give it the class that should be used.

Fortunately, since all the browser cares about is the NPClass, its function pointers, and the reference count, any class that inherits from NPObject can easily satisfy that requirement; that means that it is not difficult to make a smart NPObject; simply create static methods for each of the pointers in the NPClass struct, dereference the NPObject* that they pass in, and call a member function.

Simple class definition and implementation:

#include "npapi.h"
#include "npupp.h"
 
class MyScriptableNPObject : public NPObject
{
protected:
    // Class member functions that do the real work
    void Deallocate();
    void Invalidate();
    bool HasMethod(NPIdentifier name);
    bool Invoke(NPIdentifier name, const NPVariant *args, uint32_t argCount, NPVariant *result);
    bool InvokeDefault(const NPVariant *args, uint32_t argCount, NPVariant *result);
    bool HasProperty(NPIdentifier name);
    bool GetProperty(NPIdentifier name, NPVariant *result);
    bool SetProperty(NPIdentifier name, const NPVariant *value);
    bool RemoveProperty(NPIdentifier name);
    bool Enumerate(NPIdentifier **identifier, uint32_t *count);
    bool Construct(const NPVariant *args, uint32_t argCount, NPVariant *result);
public:
    // This is the method used to create the NPObject
    // This method should not be called explicitly
    // Instead, use NPN_CreateObject
    static NPObject* Allocate(NPP npp, NPClass *aClass) {
        return (NPObject *)new MyScriptableNPObject(npp);
    }
 
    /////////////////////////////
    // Static NPObject methods //
    /////////////////////////////
    static void _Deallocate(NPObject *npobj);
    static void _Invalidate(NPObject *npobj);
    static bool _HasMethod(NPObject *npobj, NPIdentifier name);
    static bool _Invoke(NPObject *npobj, NPIdentifier name, const NPVariant *args, uint32_t argCount, NPVariant *result);
    static bool _InvokeDefault(NPObject *npobj, const NPVariant *args, uint32_t argCount, NPVariant *result);
    static bool _HasProperty(NPObject * npobj, NPIdentifier name);
    static bool _GetProperty(NPObject *npobj, NPIdentifier name, NPVariant *result);
    static bool _SetProperty(NPObject *npobj, NPIdentifier name, const NPVariant *value);
    static bool _RemoveProperty(NPObject *npobj, NPIdentifier name);
    static bool _Enumerate(NPObject *npobj, NPIdentifier **identifier, uint32_t *count);
    static bool _Construct(NPObject *npobj, const NPVariant *args, uint32_t argCount, NPVariant *result);
 
    static NPClass _npclass;
 
protected:
    NPP m_Instance;
};

Due to code ownership issues, I’m not able to give you the actual code that I’m using, but if there are any compiler errors I’m sure they’ll be simple to straighten out.  The implementation for these static members will be pretty straightforward:

// static
void MyScriptableNPObject::_Invalidate(NPObject *obj) {
    ((MyScriptableNPObject*)obj)->Invalidate();
}
void MyScriptableNPObject::Invalidate() {
    // Invalidate the control however you wish
}
 
// static
void MyScriptableNPObject::_Deallocate(NPObject *obj) {
    ((MyScriptableNPObject*)obj)->Deallocate();
    delete ((MyScriptableNPObject*)obj);
}
void MyScriptableNPObject::Deallocate() {
    // Do any cleanup needed
}

For brevity, I’m not going to include all of the methods here; I will go into more detail on them later.  For now, suffice it to say that after you have implemented the rest of these functions, all that is left is to define the NPClass itself:

NPClass MyScriptableNPObject::_npclass = {
    NP_CLASS_STRUCT_VERSION,
    MyScriptableNPObject::Allocate,
    MyScriptableNPObject::_Deallocate,
    MyScriptableNPObject::_Invalidate,
    MyScriptableNPObject::_HasMethod,
    MyScriptableNPObject::_Invoke,
    MyScriptableNPObject::_InvokeDefault,
    MyScriptableNPObject::_HasProperty,
    MyScriptableNPObject::_GetProperty,
    MyScriptableNPObject::_SetProperty,
    MyScriptableNPObject::_RemoveProperty,
    MyScriptableNPObject::_Enumerate,
    MyScriptableNPObject::_Construct
};

Creating the NPObject

Once you have your custom NPObject created and your NPClass defined, we can cover the basics of the NPObject lifecycle.  Creating an NPObject is pretty straightforward:

NPObject *newObj = NPN_CreateObject(m_Instance, &MyScriptableNPObject::_npclass);
NPN_RetainObject(newObj);

As you can see, all that is needed is the NPP instance handler (see part two) and a pointer to the class.  Since the class is very specific to a specific NPObject, I like to create a static function to instantiate the object, like so:

static MyScriptableNPObject* NewObject(NPP npp) {
    MyScriptableNPObject* newObj = (MyScriptableNPObject*)NPN_CreateObject(npp, &_npclass);
    return newObj;
}

This is completely voluntary, of course, but it also allows you some additional control of the creation process; for example, you may want to pass in additional parameters and have them set on the object as soon as it is created.

NPObject lifecycle

As you might guess, NPN_RetainObject increments the reference count on a given NPObject.  Similarly, NPN_ReleaseObject decrements the reference count.  When the reference count hits zero, the object will be destroyed by calling the specified Deallocate function, just like the Allocate function is called by NPN_CreateObject to create the object.

When code in one DLL allocates something and it is deallocated by a different DLL, heap corruption can (and often does) occur.  For this reason, all things that belong to you will ultimately get created and destroyed in your code.  All things that belong to the browser will get created and freed in browser code.  This way everyone stays happy =]  Make sure you keep track of your Retains and Releases; just like any reference counting, this can cause you a lot of hard to track problems.

Another important thing to keep in mind about the lifecycle of a NPObject is that you don’t know exactly when it will go away; the browser will release it whenever it chooses to do so.  Therefore, you need to be able to handle things gracefully even if things are destroyed in a different order than you expect.

Giving the correct NPObject to the browser

Now that you know what an NPObject is and rougly what it does, you need to know how the browser finds out about it.  If you’ll refer back to part two and look at the plugin lifecycle, you’ll see on entry #5 that “Plugin creates a scriptable NPObject and returns a pointer to it (after calling NPN_RetainObject on it.)”  Simply put, at that point in the initialization sequence (or somewhere in there; the spec is ambiguous about the order), the Browser will call GetValue on the plugin and ask for a NPObject.  If our plugin supports NPObjects, it simply needs to create one, call NPN_RetainObject on it, and return it as a void pointer.  *NOTE: Make sure that you typecast it as a NPObject* before assigning it to the void pointer; I made that mistake once and spent a week trying to figure out why the wrong functions were getting called.

Here is an example implementation of GetValue:

NPError PluginInstance::NpapiGetValue(NPPVariable variable, void *value)
{
   NPError rv = NPERR_NO_ERROR;
   switch(variable)
   {
      case NPPVpluginNameString:
          value = *((char **)value) = STRINGS_PRODUCTNAME;
          break;
      case NPPVpluginDescriptionString:    // Plugin description
          *((char **)value) = STRINGS_FILEDESCRIPTION;
          break;
      case NPPVpluginScriptableNPObject:// Scriptable plugin interface (for accessing from javascript)
          *(NPObject **)value = this->getScriptableObject();
          break;
      case NPPVpluginWindowBool:
          *((PRBool *)value) = this->isWindowed;
          break;
      default:
          rv = NPERR_GENERIC_ERROR;
  }
  return rv;
}
 
NPObject *PluginInstance::getScriptableObject()
{
   NPObject *retval;
   if (this->npobj != NULL)
      retval = (NPObject *)this->npobj;
   else
      retval = (NPObject *)MyScriptableNPObject::NewObject(this->npp);
 
   NPN_RetainObject(retval);
 
   return retval;
}

HasMethod and HasProperty

On to the meat of the article: Say you have a javascript function like so:

var objTag = document.getElementById("myObjectTag");
alert(objTag.doSomeCoolFunction);

You may think that this looks a little strange, since “doSomeCoolFunction” sounds like a function call, but it is clearly accessed like a parameter here.  In Javascript, this is legal even if that is a function, because it can be used to determine if a function exists without calling it.  Therefore, you cannot have a method and a property on the same object with the same name.

When this call is made, the browser will call two functions on the NPObject:

1. HasMethod(NPIdentifier name);
2. HasProperty(NPIdentifier name);

The purpose of these two calls is to ascertain whether or not a property or method exists on the NPObject (as you might have guessed).  So, what is with this NPIdentifier thing?  Well, a NPIdentifier can map to either an integer or a string.  a NPIdentifier can be converted to a string (if it is a string identifier) with NPN_UTF8FromIdentifier.  To find out if it is a string identifier, use NPN_IdentifierIsString.  If it is an integer, you can use NPN_IntFromIdentifier.

Now, the purpose of integer identifiers may not be immediately apparent to everyone; it wasn’t to me at first.  Once I figured it out, however, I was thrilled.  If you are familiar with javascript, you are doubtlessly familiar with the concept that everything in javascript is an object; arrays are actually just objects with integer keys.  So, to allow array-style access, simply handle integer identifiers!

Once you have converted the identifier into something you can deal with, decide if your object has that property or method (I’ll let you figure out which goes in which function) and return true or false.

Oh, and after you get a string wtih NPN_UTF8FromIdentifier, don’t forget to release the memory with NPN_MemFree().

NPVariant

Before I go any further, I need to spend a brief paragraph or two on the NPVariant structure.

typedef struct _NPVariant {
  NPVariantType type;
  union {
    bool boolValue;
    int32_t intValue;
    double_t doubleValue;
    NPString stringValue;
    NPObject *objectValue;
  } value;
} NPVariant;

NPVariant is the datatype used by the browser to pass variables into and out of NPObjects.  From the MDC docs, the following types are valid:

Since it’s getting late and I’ve already put too much in this post (I’m over 2000 words), I’ll leave it as an excercise to the reader to read up on the macros and such for using this structure.

Properties

At this point, you should be getting a pretty good idea of how everything works.  Getting and setting properties is fairly straightforward:

    bool GetProperty(NPIdentifier name, NPVariant *result);
    bool SetProperty(NPIdentifier name, const NPVariant *value);

To get a property, simply check the name to see what you’re going to be doing and store the value to return in *result.  If the operation succeeds, you should return true.  If not, false.

To set a property, again check the name to see which property you’re working with and save the value of the NPVariant parameter however you wish.  Again, return true if success, false if failure.

Methods

Methods aren’t much more difficult.  The only real difference is that now you have parameters to worry about.  No problem!  Parameters are passed in as an array of NPVariants:

    bool Invoke(NPIdentifier name, const NPVariant *args, uint32_t argCount, NPVariant *result);
    bool InvokeDefault(const NPVariant *args, uint32_t argCount, NPVariant *result);

The difference between Invoke and InvokeDefault is that InvokeDefault does not ever have an identifier.  If you call “objTag.funcName()” Invoke gets called; if you call “objTag()”, then InvokeDefault gets called.

As with properties, store the return value in the pointer given in the last argument and handle the other arguments however you wish.

Wrapping it up

Alright, I know I haven’t covered everything, but this is already too long.  If you have specific questions, ask them in the comments and I’ll do my best to answer; the comments may determine the direction of my next post.

Since dealing with the NPIdentifiers can get to be such a pain, I recommend using a map or hashtable to store structures with function pointers to map a string name to functions to handle it; that way you don’t end up with giant if/then or case statements, and everything ends up being much cleaner.

Another idea for the adventuresome: abstract the actual logic (properties and methods) into another object that can be wrapped with your NPObject class, and then make another wrapper class that implements IDispatch so that your scriptable objects are cross platform (IDispatch objects are scriptable on Internet Explorer).

Good luck!

Building a firefox plugin – part one

Building a firefox plugin – part two

Building a firefox plugin – part three

Building a firefox plugin – part four

Getting more help

Update May 14, 2011: Many people have been asking questions in the comments; while I don’t mind that, it would probably be more useful if you ask your question on the FireBreath forums. There is a forum there for those just using NPAPI as well!