Let me warn you: QuickPaint is not long on features, but it has great simplicity going for it. I think it's a good example of how much a Be app can do with very little code, and still be well-architected and extensible. The line count, including headers, is a little over a thousand.

What's interesting about it? For one thing, it demonstrates a simple yet extensible document/view architecture using BMessages. It allows you to open any number of windows onto a single bitmap "document," make modifications in any of those windows, and have all the views of that document be updated in real-time.

The idea is simple: the document keeps a list of editors, and notifies them (via BMessages) any time the bitmap changes, with data about what has changed. The editors receive the messages and update their displays. Each editor can display the data any way it wants; in this case, each editor has its own scaling.

To try this out, launch QuickPaint and select "Open new view" from the View menu. Do this as many times as you want. Put them all over the screen, and use Alt/Command-(plus) and Alt/Command-(minus) to get different scaling levels. Then chose a color and a tool from the ToolBox window and draw in one of the windows. Your interaction is scaled to match the pixels in the window you are editing in, and all the other views are updated immediately.

Other than that, you'll notice that each tool is a BHandler and the ToolBox maintains a BLooper which multiplexes between them, depending on the current tool selection. The current tool is simply the PreferredHandler of the BLooper.

Finally, there is read-only/read-write locking done on the bitmap, to make sure that nobody is blitting the bitmap while a tool is writing in it. This is necessary because messages can arrive at editors at any time, and we don't want bad updates happening. However, making it a read-only/read-write lock (i.e., many readers, one writer) means that many editors can handle updates simultaneously. Only the drawing tools need exclusive access to the bitmap.

Some exercises for the reader, for those of you who feel like playing with the code:

• Implement the Open/Save/Save As menu options. This should be very simple using the Translation Kit, and would add very little code.

• Make the tools plug-ins, using add-ons.

• Implement a Bezier tool.

• Implement a text tool.

• Right now, the tools get confused if the window moves or changes scaling while you're in the middle of using one. Make them handle this case correctly.

• Ship it!

A static query is a one-time snapshot of files on a disk that met the specified criteria at the time the query was made. Depending on other activity on the machine, the list of matching items can change by the time you receive it, and you must be prepared in case that happens. Next week we'll delve into the more complicated issue of live queries and node monitoring to make sure your list remains up to date. This week's article provides the foundation for that even more interesting discussion.

Let's examine the make-up of QueryApp, the sample code provided with this article. It can be found at:

ftp://ftp.be.com/pub/samples/storage_kit/QueryApp.zip

QueryApp is very straightforward, and somewhat limited. All the interesting work is done by the QueryWindow class. This provides an interface that allows the developer to search the drive the application is on for folders, source code, or files (non-folders) that have a certain case-sensitive string in their names. The query string that was built is displayed, along with the paths of matching entries.

The BeOS has two interfaces for creating static queries: a straight C function-based interface, and the more common (and flexible) BQuery class. QueryApp demonstrates both methods, and allows the user to choose the underlying method (to demonstrate that both provide identical results).

Let's begin by looking at the implementation from FetchC():

void
QueryWindow::FetchC()
{
   //gather the information from the views
   char query_string[1024];

   if (fFileType == FILES_TYPE) {
     sprintf(query_string,
       "((BEOS:TYPE!="application/x-vnd.Be-directory")"
       "&&(name=="*%s*"))", fNameString->Text());
   } else if (fFileType == FOLDERS_TYPE) {
     sprintf(query_string,
       "((BEOS:TYPE=="application/x-vnd.Be-directory")"
       "&&(name=="*%s*"))", fNameString->Text());
   } else if (fFileType == SOURCE_TYPE) {
     sprintf(query_string,
       "((BEOS:TYPE=="text/x-source-code")"
       "&&(name=="*%s*"))", fNameString->Text());
   }

   fQueryString->SetText(query_string);

   //find the device id of our application
   app_info info;
   be_app->GetAppInfo(&info);
   //info.ref.device is our device id

   DIR *query;
   dirent *match;

   query = fs_open_query(info.ref.device, query_string, 0);
   if (query) {
     while(match = fs_read_query(query)) {
        //create an entry ref from the dirent
        entry_ref ref;
        ref.device = match->d_pdev;
        ref.directory = match->d_pino;
        ref.set_name(match->d_name);

        BEntry entry(&ref);
        if (entry.InitCheck() == B_OK) {
          BPath path;
          entry.GetPath(&path);
          if (path.InitCheck() == B_OK) {
             BStringItem *item = new BStringItem(path.Path());
             fItemList->AddItem(item);
          }
        }
     }
     fs_close_query(query);
   }
}

As you can see, the C interface to queries is simple. A query token is returned to you through a call to fs_open_query(). You specify the volume you want to search, and a query string that defines the search parameters. Then you retrieve successive dirent pointers from the query using fs_read_query(). This represents an entry that matches the criteria.

Next you use this dirent to create an entry_ref, which you use to go through the standard progression to the path that you want. This path is then added to the list of paths. Note that we are careful checking the status of our entry. It's possible that by the time the entry is created, the resource doesn't exist there anymore.

While this is not as important in this case, where we simply want the path, it would be very important to catch a failure in the transformation process if the actual data of the entry needed to be accessed (say through a BFile or a BNodeInfo). When fs_read_query() returns NULL, there are no more matches or an error has taken place. We break from our loop and make sure to close the query with fs_close_query().

The C++ interface through the BQuery class is a little more user friendly. For starters, the class gives you two ways to define the query, through a text string like the C Interface (using BQuery::SetPredicate()) and through a postfix (Reverse Polish Notation) stack of operations. Take a look at the FetchQuery() function to see its use:

void
QueryWindow::FetchQuery()
{
   BQuery fQuery;

   //gather all of the information from the views
   char *type = NULL;
   fQuery.PushAttr("BEOS:TYPE");
   if (fFileType == SOURCE_TYPE) type = "text/x-source-code";
   else type = "application/x-vnd.Be-directory";
   fQuery.PushString(type);
   if (fFileType == FILES_TYPE) fQuery.PushOp(B_NE);
   else fQuery.PushOp(B_EQ);

   fQuery.PushAttr("name");
   fQuery.PushString(fNameString->Text());
   fQuery.PushOp(B_CONTAINS);
   fQuery.PushOp(B_AND);

   size_t len = fQuery.PredicateLength();
   char *string = (char *) malloc(len + 1);
   fQuery.GetPredicate(string, len + 1);
   fQueryString->SetText(string);
   free(string);

   /* use this application's volume */
   app_info info;
   be_app->GetAppInfo(&info);
   //use the ref of the application binary
   //use the device from this ref to create a volume
   BVolume vol(info.ref.device);
   fQuery.SetVolume(&vol);

   //fetch the query
   fQuery.Fetch();

   //Iterate through the entries
   BEntry entry;
   BPath path;
   while(fQuery.GetNextEntry(&entry) != B_ENTRY_NOT_FOUND) {
     if (entry.InitCheck() == B_OK) {
        entry.GetPath(&path);
        if (path.InitCheck() == B_OK) {
          BStringItem *item = new BStringItem(path.Path());
          fItemList->AddItem(item);
        }
     }
   }
}

The postfix notation lets you push operations on to the stack. You first specify the attribute you want to push with PushAttr(). Next you define the criteria you want to compare it against with the various PushType functions (PushString(), PushInt32(), PushFloat(), and so on. Then you define how to compare or combine those definitions with the PushOp() function. The Be Book describes this process in detail:

BQueryOverview.html

BQuerys also are more flexible in how they present matching entries to you. The C interface only allows the use of the dirent structure (through FindNextDirent()). This is fast, but requires some work before you get reasonably useful objects. Like BDirectory objects, BQuerys also let you get ready made entry_refs or BEntry objects. In this case we ask for the BEntry object we built in the C functions, and after taking appropriate safety precautions, retrieve and store each matching path.

The final bit of flexibility provided by the BQuery class is the ability to create live queries. As mentioned earlier, live queries add additional complexity to the query process. For that reason I'll continue next week with a detailed look at keeping a query list in sync with an ever-changing file system.