New-ish REALbasic features (Part One)

Welcome to the start of a multi-post topic on some rather new features to REALbasic. I happened to come across a user who was attempting to do some fairly complex Win32 declares, and in the course of trying to tackle the problem myself, I realized that I was making use of some new language features that would be nice to share with others.

Before we jump right into all of the goodies, you're going to need a bit of background information on what we're trying to accomplish. We're going to work on a low-level API for creating dialog boxes in memory and then displaying them. We're only going to be making use of Win32 APIs for doing this (but it's obviously much easier to just use REALbasic to solve this problem) because this is a technology experiment.

Let's start off by looking at the APIs involved. We're going to start with the DialogBoxIndirect API, which is the main attraction. This API is what constructs the modal dialog and displays it. Because the dialog is modal, the API will not return control back to the caller until the dialog box is dismissed. However, if you read the description of the API, you'll notice that this is going to be a fun one. One of the parameters it takes is a dynamic structure that has several different structures internal to it.

So what's the game plan for working with the API? It's easy -- we're going to make a dialog template header for the dialog box itself, and a series of dialog item templates for any of the controls we want to display. But we're going to do it using two new (sorta) REALbasic language constructs: Ptr and structures.

At this point, you may be wondering why we aren't using a MemoryBlock. Well, aside from the fact that it wouldn't be much fun (couldn't use named fields, for instance), there's a key piece of information blocking us from doing that. The very astute reader will notice in the API documentation a certain phrase: "Pointer to a global memory object that contains the template..." It's the "global memory" that should catch your attention. When you see a designator like "global memory" or "local memory" or "virtual memory", etc, then that's telling you what APIs are needed to create that memory. In this case, we need to have memory allocated via GlobalAlloc. You cannot use a MemoryBlock because you cannot make any assumptions about how the memory is created or where it comes from. When the declare is specific, you must be specific as well (especially since the MemoryBlock memory allocator can change on a whim).

Let's recap! We're going to need some Win32 APIs, which are: GlobalAlloc, GlobalLock, GlobalFree, DialogBoxIndirect, and MultiByteToWideChar. We're also going to be using Ptr and Structure datatypes to work with the template items. Finally, we're going to be using a Shared method to make the dialog box's callback procedure work.

This should be fun, eh!