UTool is a single-window application template for REALbasic 5.5.2 or later. It is designed to:

- make it quick & easy to create a polished, robust, cross-platform application
- provide a library of generically useful functionality not built into REALbasic
- illustrate good practices in REALbasic coding style and documentation

This document introduces you to the main features of this handy template. Experienced RB'ers can just hop right into the code, but if you're new to REALbasic, it's probably a good idea to at least skim this info.


GETTING STARTED (out of the box)
--------------------------------
Compile and run UTool as is. You'll see that you can drag items from the Macintosh Finder or the Windows Explorer to the main window, and the items and their content will be listed. That probably won't impress you much. But take note:

- There is also a help window, a preferences window, and an About box.
- The preferences window works "live", as you manipulate the controls.
- All windows remember their positions between sessions.
- The application quits when its main window is closed.
- You can open files or folders via the menu bar.
- The most recently-opened item is remembered.
- You can drag files, folders, and volumes to the application's main window or to its icon.
- Dragging exposes a chasing arrows control.
- Output is logged to the main window, which supports SelectAll and Copy.
- Main window contents can be printed, and Page Setup works too.
- Files that are hidden in the Finder/Explorer are not listed in the main window.
- The URL link at the bottom of the window is functional.

All of this works on Mac OS X, Mac Classic, and Windows. None of it is difficult to achieve, but in aggregate, it represents a decent amount of learning, work, and organizational thought.

That's what you can do with literally no effort. What if you're willing to invest a minute or so?


TRIVIAL CUSTOMIZATION (60 seconds)
----------------------------------
Make a copy of the project and name it whatever you like.

Open the AppStrings module and change the constant values to ones that are appropriate to an application you're thinking of creating. (Leave the methods alone.)

Open Build Settings and edit the version number fields to match what you put into AppStrings. (Leave all the "#xxx" fields alone.)

Run the project again. Note that everywhere the application name appears (in window titles, menu items, etc.), it has now changed to match your edits. Same for the version number, URL, etc.

That's how easy it is to make the application your own.


MINOR CUSTOMIZATION (5 minutes)
-------------------------------
When creating a generic template like this, one aims for a balance between having it do something useful out of the box, and keeping it easy for people to throw away that functionality and replace it with their own.

For this version of UTool, I decided that supporting drag-and-drop to process groups of files and folders would make a good starting point for many utility applications. As described above, UTool can do this out of the box -- you can drag groups of files, folders, or volumes to either the main window or the application icon, and the UTool.Process method will be invoked for each group.

The most useful kind of minor customization therefore consists of changing what is meant by "processing" a file. Doing this is simple (almost absurdly so):

1) Create a method to process groups of folderItems
2) Edit MainWindow.Process to call your replacement instead of the UTool module

What your replacement processor does is up to you. Here's an extremely simple example:

  Sub Process(items() as folderItem)
   
    // This trivial folder item array processor
    // lists each item's name in our main window.
   
    dim item as folderItem
    for each item in items
      Log item.DisplayName
      App.AddRecentlyOpenedItem item // for the Open Recent menu item
    next item
   
  End Sub

A more useful processor might list file sizes, set their types, copy to a certain folder, etc. Put your processor method in a module, in your main window, or anyplace else you like. (I use modules to keep my engine code separate from my UI code, but it's up to you.)


MAJOR CUSTOMIZATION (5 more minutes)
------------------------------------
If you don't care about UTool's major features, the minor ones can still save you a lot of time. You'll find it's pretty easy to discard what you don't want. Here are some tips for dealing with the most likely customization targets:

- Drag and drop: Look at the App.FileTypes method, read the comments, and see where it's used. This will quickly show you how drag and drop is supported in UTool, and how to modify it. Also see the App.OpenDocument event.

- Log output: The main window contains a log field that gets all the text that is sent to the global Log method (in the Diagnostics module). If you'd rather not have that, delete that field and send your Log output somewhere else -- the built-in System.Log is a good candidate (see the RB documentation). Or just delete the Diagnostics module and all calls to it.


OTHER HIGHLIGHTS
----------------
UTool's internal documentation is extensive; look for Notes in classes and modules. Browse through the various "Helpers" modules -- odds are pretty good that you'll find something new and handy in there. UTool doesn't use all these methods out of the box, but they're the ones I most often need, so I've left them in. And I've tried to make the various components self-contained, so that you can easily pull modules into other projects. Here are some items of particular interest:

- Preferences: This is a popular topic with REALbasic beginners. Search for "Prefs.Get" and "Prefs.Set" in the code to see how simple it is to use UTool's preference engine. Also, this system is easy to re-use in non-UTool projects: just drag the Preferences folder to the Macintosh Finder or the Windows Explorer, and from there into your project. You'll have to change "AppName" within the Preferences.Prefs method to something appropriate to your project (or provide an alternative definition of it), and you'll need to call Prefs.Save in your application's Close event. Otherwise, the system is completely automatic.

- Folder iteration: Look in the FolderItemHelpers module at the Files and Folders routines. These are very handy ways to get lists of files, with an easy optional filtering mechanism. The Process routines in the UTool module illustrate various ways to use these. For more involved filtering, use the GeneralFolderItemFilter, or implemement your own version of the FolderItemFilter class interface.

- Printing: This always seems to be a time sink -- but less so for UTool users, I hope, because it comes with a text-oriented printing facility, featuring multi-column layout, headers, and footers. It's all hooked up and ready to go. To customize it, start by looking at the PrintWithDialog method of the PrintHelpers module. (I hope to document this better in the near future.)

- Search for "hack" to see any parts that I think could be better, but for one reason or another aren't. (It's possible that this will be released without any hacks...wish me luck...)


KNOWN ISSUES
------------
- You can't drag external items to an EditField on Windows. This is a REALbasic limitation. The workaround is to drag to the application icon, or to the area of the main window around the EditField.

- I haven't tested any of this on Unix. If you do, please let me know how it goes.


Also let me know of any problems or errors, and tell me what you make with UTool!

Lars Jensen
April 2005
utool@ljensen.com
