Anyone interested in a brief example using the new scripting architecture in PR1 and PR2? I heard a few "yes's" so here it is.

For a long time developers have been asking for scripting support in the BeOS. We listened and we added such support in the PR1 release. In keeping with BeOS philosophy the goal was to add scriptability with minimal complexity. Hopefully we've achieved that goal. Let us know what you think.

For a full technical description see:

http://www.be.com/developers/may_dev_conf/transcripts/messagingandscripting .html

for a transcript of the messaging/scripting session at BeDC, or read about scripting in the Be Book:

http://www.be.com/documentation/be_book/app/scripting.html

Now I'll give a little example of how to create a class that is scriptable. Let's suppose you have a view class that can have one of three states. It also contains a rectangle that defines a hot spot inside the view. Let's suppose that you want to script those 2 properties. Here's what the class declaration might look like:

class TTriView : public BView {
      TTriView(BRect frame, int32 state, BPicture *pict)
  ...
  void  MessageReceived(BMessage *msg);
  BHandler  *ResolveSpecifier(BMessage *msg,
                int32 index,
                BMessage *specifier,
                int32 form,
                const char *property);
  ...
  void    SetState(int32 state);
  int32   State() const;
  void    SetHotSpot(BRect rect);
  BRect   HotSpot() const;
};

In the TTriView constructor you can see the 2 features of the class that we will make scriptable, its state and hot spot. The class also overrides the MessageReceived() hook function. It is in that function where the script messages will be handled.

The last overridden function is ResolveSpecifier(). This is the key function in terms of making a class scriptable. This is how a class advertises the "specifiers" that it supports. Let's start with this function:

BHandler *TTriView::ResolveSpecifier(
          BMessage *msg,
          int32 index,
          BMessage *specifier,
          int32 form,
          const char *property)
{
  BHandler  *target = NULL;

  if ((strcmp(property, "State") == 0) {
    if (form == B_DIRECT_SPECIFIER)
      target = this;
  } else if ((strcmp(property, "HotSpot") == 0) {
    if (form == B_DIRECT_SPECIFIER)
      target = this;
  }

  if (!target) {
    target = BView::ResolveSpecifier(msg, index, specifier,
                                     form, prop);
  }

  return target;
}

Let me explain a little of what's going on in the ResolveSpecifier() function. The class is declaring that it understands 2 properties, "State" and "HotSpot". For each of these properties it can handle DIRECT specifiers only. There are more kinds of specifiers, see the documentation in the Be Book for more details.

If the object can handle the message it should return itself (the this pointer). This tells the system that the scripting message should be handled by this object. Otherwise it is very important to call the inherited version of ResolveSpecifier() because some inherited class might actually understand the message, even if the derived class doesn't.

After getting directed to the correct object, a scripting message will be passed to the MessageReceived function. It is in this function that the message is actually processed:

void TTriView::MessageReceived(BMessage *msg)
{
  bool      handled = false;
  BMessage  reply(B_REPLY);
  status_t  err;

  switch (msg->what) {
    case B_GET_PROPERTY:
    case B_SET_PROPERTY:
    {
      BMessage  specifier;
      int32     form;
      const char *prop;
      int32      cur;
      err = msg->GetCurrentSpecifier(&cur, &specifier, &form,
        &prop);

      if (!err && (strcmp(prop, "State") == 0)) {
        if (msg->what == B_GET_PROPERTY) {
          reply.AddInt32("result", State());
          handled = true;
        } else {
          int32 new_state;
          err = msg->FindInt32("data", &new_state);
          if (!err) {
            SetState(new_state);
            reply.AddInt32("error", B_OK);
            handled = true;
          }
        }
      } else if (!err && (strcmp(prop, "HotSpot") == 0)) {
        if (msg->what == B_GET_PROPERTY) {
          reply.AddRect("result", HotSpot());
          handled = true;
        } else {
          BRect  new_spot;
          err = msg->FindRect("data", &new_spot);
          if (!err) {
            SetHotSpot(new_spot);
            reply.AddInt32("error", B_OK);
            handled = true;
          }
        }
      }
      break;
    }
    ...    // other 'cases' go here
  }

  if (handled)
    msg->SendReply(&reply);
  else
    BView::MessageReceived(msg);
}}

In the above code you can see that the class supports either GETing or SETing the 2 scriptable properties of TTriView. These properties can't be created or deleted (i.e. B_CREATE_PROPERTY or B_DELETE_PROPERTY). More complex classes will support these and other options.

When getting or setting the State of the view, the data being dealt with is an integer. For this reason the code uses FindInt32() and AddInt32() in the SET and GET cases respectively. In the HotSpot case the corresponding FindRect() and AddRect() functions are used.

Note that when setting an attribute, the data should always be found in an entry named "data":

  err = msg->FindRect("data", &new_spot);
  // —or --
  err = msg->FindInt32("data", &new_state);

When handling a GET message, the data being returned should always be placed in a entry called "result":

  reply.AddInt32("result", State());
  // —or --
  reply.AddRect("result", HotSpot());

Placing an error code in the entry "error" is another scripting convention worth noting.

The final step is to send a reply to the scripting message. Notice that a reply is sent whether the message is setting or getting data. In the GET case it is obvious that a reply is needed, because the requested data must be returned. In the SET case the class still returns a message to indicate the success or failure of the SET.

That's all there is to this simple scripting example. As always, if there are any questions just post them to BeDevTalk or send me a message.Content-Type: application/x-be_attribute; name="scripting.article"

Did you get the message? I'm sure I sent it, why haven't you responded? If you've been using BMessageFilters, then your brain cells can probably recognize this pattern of thought.

As written previously, BMessageFilters are wonderful things. They make dynamic extension using BLoopers and BHandlers relatively easy in the BeOS. I've gone over how you can use a filter to capture things like keydowns, mouse movements, and any other messages that are normally headed for your classes. Now I want to talk about some of the mechanics for using them in particular situations.

Did you know that after you use BLooper::AddCommonFilter(), your message filter is added to the bottom of a list. When a new message comes in to be processed, this list of filters is traversed from the top to the bottom. That is First in First Processed. This is an implementation detail, but it's necessary to know in order to achieve certain behaviors in message processing.

Here's a task. You want to create a user interface test harness. You need to capture and playback all keystrokes and mouse movement. You want to be able to create a script that will saves these events in some way for later playback. How can you do such a thing? With BMessageFilters, of course.

First of all, write a capture filter. All it has to do is get every message, examine it to see if it's a mouse or key message, and capture it if it is. It will not actually interfere with the processing of messages, it will just examine and capture the appropriate ones.

CaptureFilter::CaptureFilter()
  : BMessageFilter()
{}

filter_result
CaptureFilter::Filter(BMessage *msg, BHandler **target)
{
  switch (value)
  {
     case B_KEY_DOWN:
       // capture keydown
       break;
     case B_MOUSE_DOWN:
       // capture mouse down
       break;
  }

  return B_DISPATCH_MESSAGE;
}

Simply put, this filter will examine all messages, and capture for later playback all the ones that are either keydown, or mousedown. Simple enough. You can embellish it with the actual capture code. To use this filter, you can simply call AddCommonFilter on whatever window object whose events you want to capture. Easy enough.

Now let's say you want to do something a little bit more fancy, before messages are actually captured, you want to filter them out to eliminate excessive mouse movement, or you want to modify the events in some way before they are captured.

Well, you can simply call AddCommonFilter again and your filter is in the chain...but not in the right order. Remember, they are processed in first-in, first-processed order. We need to be able to change this processing order. The only really good way to do this is to sub-class the BLooper, or BHandler, and add the appropriate message filter list processing code yourself.

What we want to achieve is the reversal of ordering in the message list. There is no real easy way for you to change the processing order, so you need to change the order in which the items are added to the list.

virtual void AddCommonFilter(BMessageFilter *filter);

We can achieve what we want by implementing this single method. Reading the comments of this code will give you the flavor of what is going on.

void
MessageLooper::AddCommonFilter(BMessageFilter *filter)
{
  // Check for locking. We have to be locked before we
  // can proceed or multiple threads could be trying to
  // create the filter list at the same time.

  BLooper *loop = Looper();

  if (loop && !loop->IsLocked())
  {
    debugger("MessageLooper::AddCommonFilter - Owning Looper
              must be locked before calling
              AddCommonFilter");
    return;
  }

  // BLooper::RemoveCommonFilter doesn't reset the looper to
  // NULL when the filter is removed, so this check is not
  // valid after the filter is removed. This is a bug and
  // will be fixed in future releases. Until then, you might
  // want to disable the check.

  //if (filter->Looper() != NULL)
  //{
  //  debugger("A MessageFilter can only be used once.");
  //  return;
  //}

  BList *newList = CommonFilterList();
  if (0 == newList)
  {
    newList = new BList();
    SetCommonFilterList(newList);
  }

  // Most important line, this makes sure the items
  // are added to the top of the list instead of the
  // bottom.

  newList->AddItem(filter, 0);
}

Once you use this new AddCommonFilter, your filter list will act as a stack, with last-in, first-out processing. So you can add a filter that captures all messages, and doesn't send them on to the Looper until it has sent them out to the network and back, or whatever else you want to have happen. The main benefit of having your filters processed in this order is that you can layer on and supersede functionality, which you can't do with the default processing order.

It's only one method to implement, and you benefit from it tremendously in certain situations. I have found it to be quite useful, and my code is more flexible and dynamic for it.

As this newsletter approaches its 100th issue, there will be more authors participating than ever, bringing you more details of the BeOS to help you write that tractor driving killer app. I'll see you at the front.

That's how I felt the morning after writing last week's column discussing the little contractual misunderstanding between Sun and Microsoft. A few hours after our newsletter hit the Net, Sun and Microsoft posted the text of their Java licensing agreement on the Web.

As my e-mail correspondents vigorously suggested, I read the contract, and I read it again, and I read it again. And I decided to wait for the Agenda conference held in Phoenix, Arizona, on October 20-21. Scott McNealy, Bill Gates, Stewart Alsop, Bob Metcalfe, John Doerr, Andy Grove and other luminaries were bound to help me understand the finer points of this dispute.

Right at the end of the Monday morning coffee break, I went back to the big ballroom, looking forward to Eric Schmidt's "Java as a soap opera" presentation for enlightenment—and entertainment. As I settled down, the conference organizers were playing one of the satirical videos customarily used to fill idle times.

On the big screen, Janet Reno was being ribbed for her ineffectual DOJ anti-trust pursuits and her political tin ear—I thought, until I realized it was a genuine real-time CNN feed and our Attorney General was taking on Microsoft again.

This time, Janet alleges, Microsoft is in breach of the 1995 consent decree overseeing the practice of bundling software products, forcing, I'm sorry, "incentivizing" customers to buy more Microsoft products together and crowding the competition out. Specifically, the DOJ alleges Microsoft uses its dominant market position to "force" manufacturers and consumers to buy the Explorer browser together with the Windows operating system in violation of the 1995 consent decree. Further, the DOJ complains, Microsoft uses non-disclosure agreements to compel their business partners to give them advance warning of government inquiries and to prevent them from volunteering information to the DOJ.

Burned by my poor timing last week, I'll wait. So far, Wall Street seems to be shrugging the complaint off: This morning Microsoft's stock is up and Netscape's is down—whatever that means.

Returning to Java, Eric Schmidt gave a very clever presentation, taking turns at all sides in the issue, Sun's, Microsoft's, and the rest of us. Later, we heard directly, very, from Scott McNealy as well as his mother, a rather assertive and golden-hearted individual who makes her son blush. And we were treated to a fireside chat with the Chairman. And the result is...more confusion.

Regarding the contract, listening to one side or the other is more instructive on issues of motive than on fact. Legal eagles are more helpful: Most of the ones not affiliated with either side seem to agree Microsoft is, or can easily put itself in at least narrow compliance with the agreement by posting missing bits, classes somewhere on their site without necessarily bundling them with their product. An irony at a time when Microsoft is sued for bundling other bits. But let's move from contractual Talmud to marketplace Kriegspiel. What are the possible moves?

Microsoft could decide to pick up its marbles and not offer a Java implementation at all. With 95% of desktop PCs, would this kill Java? Not necessarily, Sun or others can offer a Java VM for Windows and, voilà, Pure Java programs run on Windows, Java-powered Web pages work. This would allow Sun and its ally to proceed with their game plan: Expand the Java definition, and the underlying Java VM to the point of making Windows unnecessary and irrelevant. Java would morph into Java OS, sporting a myriad of applications, an alternative to Windows or, even better, its successor, more in tune with the new world of hardware-blind distributed computing applications.

This assumes much passivity from Microsoft. Developing a Microsoft-unfriendly platform by starting on top of Windows isn't an easy proposition. All sorts of technical glitches could "develop" along the way and lawyers salivate today when they fantasize about this direction. As in the old IBM days, the Java camp would need to force full disclosure of all internal Windows APIs. This could take a long time.

Another direction for Microsoft would be to abandon the Java label, call their "dialect" J++ and happily continue on their merry way having "embraced and extended" the language as advertised all along. Once the outcry dies, the Java consortium can offer a competing "Pure Java" VM and pursue the course outlined above. This is probably an even more difficult challenge: Imagine a J++ engine and a Java VM sitting on the same system. How would most customers feel about this? Which engine would the developers pick if they want to make money—as opposed to making a statement?

There are a few more options left. Microsoft could capitulate and tell Sun "I've sinned against you," Pure Java would run everywhere and progressively make Windows passé and hardware irrelevant. Possible in another universe, but not likely in this one.

What is perhaps a little more likely is some kind of muddy compromise. Sun is hinting darkly they don't want to settle for Microsoft to just pay the contractual $35 million in liquidated damages and go home. Suns wants Microsoft to be compelled by the courts to fully honor the licensing agreement, or, if I read correctly, pay much bigger damages for the harm allegedly done to the industry. Or settle for less in a mealy-mouthed compromise.

In the mean time, Sun is already reminding us that Java is much more important to new, emerging genres of computing devices such as appliances, network computers, smart cards, mobile communicators and rings opening doors, ski lifts and ATMs. This is, after all, a return to the original premise of First Person and Oak, respectively the originator and original name of Java. Please remember, I promised confusion.

One thread says Java is a way to re-open the market by creating a new computing platform capable of making Windows less of a toll gate. Another line of discourse states desktop computers matter a lot less than the many new genres of computing devices enabled by semiconductor technology and the communications infrastructure—and, above all, desired by consumers.

Which one will work? Your guess is better than mine.

BeDevTalk is an unmonitored discussion group in which technical information is shared by Be developers and interested parties. In this column, we summarize some of the active threads, listed by their subject lines as they appear, verbatim, in the mail.

To subscribe to BeDevTalk, visit the mailing list page on our web site: http://www.be.com/aboutbe/mailinglists.html.