The dialog manager, part 1: Warm-ups


I think a lot of confusion about the dialog manager stems from not really understanding how it works. It's really not that bad. I'll start by describing how dialog boxes are created over the next few articles, then move on to the dialog message loop, and wrap up with some topics regarding navigation. There will be nine parts in all.

The first major chunk of the dialog manager has to do with reading the dialog template and creating a dialog box based on it.

All of the CreateDialogXxx functions are just front-ends to the real work that happens in CreateDialogIndirectParam. Some of them are already visible in the macros: CreateDialog is just a wrapper around CreateDialogParam, with a parameter of zero. Similarly, CreateDialogIndirect is just a wrapper around CreateDialogIndirectParam with a zero parameter.

Here's a slightly less trivial wrapper:

HWND WINAPI CreateDialogParam(HINSTANCE hinst,
    LPCTSTR pszTemplate, HWND hwndParent,
    DLGPROC lpDlgProc, LPARAM dwInitParam)
{
  HWND hdlg = NULL;
  HRSRC hrsrc = FindResource(hinst, pszTemplate,
                             RT_DIALOG);
  if (hrsrc) {
    HGLOBAL hglob = LoadResource(hinst, hrsrc);
    if (hglob) {
      LPVOID pTemplate = LockResource(hglob); // fixed 1pm
      if (pTemplate) {
        hdlg = CreateDialogIndirectParam(hinst,
                 pTemplate, hwndParent, lpDlgProc,
                 dwInitParam);
      }
      FreeResource(hglob);
    }
  }
  return hdlg;
}

All CreateDialogParam does is use the hinst/pszTemplate to locate the lpTemplate, then use that template in CreateDialogIndirectParam.

Okay, this was easy. Tomorrow, we're going to create the dialog from the template.

Comments (20)
  1. Cool, another series on dialogs! I look forward to this series, I learned several new things about dialogs from previous posts on your blog.

  2. Somebody says:

    So what happens if FreeResource(hglob) fails? ;-p

  3. GeoffE says:

    Somebody> So what happens if FreeResource(hglob) fails? ;-p

    The memory is leaked (in theory) but the function is successful. I think this is the right behavior for this kind of function since 1) the dialog was created and can be used, 2) if it returns an error there is nothing the caller can do to free the data.

    If this were in an environment where FreeResource threw an exception you’d need to wrap it in a try/catch block and eat the error.

    – Geoff

  4. someone else says:

    but is it possible for FreeResource to fail if the hglob parameter is a valid parameter (LoadResource succeeded and FreeResource has not already been used on it)

  5. ??????? says:

    The FreeResource function is obsolete and is only supported for backward compatibility with 16-bit Microsoft Windows.

    ??????

  6. Resource files are DLLs, which are statically loaded into your VMM memory. They don’t get loaded into and out of memory piecemeal, or without the support of the VMM any more. And with a 32 bit address space, they don’t get moved around in memory either. So you don’t have to worry about Free’ing them.

    The only reason you even need to Load them is for parity with the LoadIcon, LoadImage, LoadString etc. functions which Win3.0 programmers were familiar with, and because it converts the handle to a pointer.

  7. Raymond Chen says:

    I discussed the memory management of 16-bit resources earlier. http://blogs.msdn.com/oldnewthing/archive/2004/02/02/66159.aspx

  8. Somebody says:

    I’m looking at the MSDN page for LockResource (http://msdn.microsoft.com/library/default.asp?url=/library/en-us/winui/winui/windowsuserinterface/resources/introductiontoresources/resourcereference/resourcefunctions/lockresource.asp) and it specifically states:

    "Do not try to lock a resource by using the handle returned by the FindResource or FindResourceEx function. Such a handle points to random data. "

    So I’m guessing that the line:

    LPVOID pTemplate = LockResource(hrsrc);

    sould be changed to:

    LPVOID pTemplate = LockResource(hglob);

  9. Raymond Chen says:

    Thanks – fixed.

  10. I once wrote a class that would dynamically create a dialog template. Used it to redirect C++ streams to message boxes and simple input dialogs.

  11. rags says:

    Raymond – how about doing one article in your series about generating dialogs on the fly?

    Something like what VB does… Allow the user to drag and drop controls (fields) onto the dialog in some kind of a design environment, and then display the resulting dialog (form) in some kind of a runtime environment?

    Or does this come under the heading of proprietary technology?

  12. FreeResource cannot fail on a valid parameter, that is a non-NULL returned value from LoadResource. The code is correct.

    In practice, the whole thing is a leftover from the 16 bit windows days when discardable segments were used and you had to tell the memory manager that for some duration of time, a discardable segment had to be locked.

    FreeResource doesn’t do anything today and given that, it’s really also locked in the contract so that we can’t in the future start allocating something on LoadResource that has to be freed.

    Arguably, LoadResource should have allocated *something* from the heap and returned a pointer to it so that missing calls to FreeResource() would cause demonstrable leaks, but welcome to the world of a large installed base.

  13. Raymond Chen says:

    Dynamic template generation is already in the article queue for April 29th.

  14. Maxime LABELLE says:

    Wow,

    Thanks to the very cool series of articles about "the evolution of dialog templates", I have written a library that creates dialog boxes from in-memory on the fly generated dialog templates.

    I’m sure I will learn many mistakes from this very series. I Can’t wait.

  15. rags says:

    Raymond Chen >> "Dynamic template generation is already in the article queue for April 29th."

    Cool!!! cant wait for it to come out!

    wish you could have come out with it 5 years back though :(

  16. David says:

    Is the call to FreeResource necessary on Win32?

  17. Jonathan Wilson says:

    How is this stuff related to DialogBox & friends?

  18. Norman Diamond says:

    3/30/2005 5:43 PM Jonathan Wilson

    > How is this stuff related to DialogBox &

    > friends?

    Look at the base note again.

    >> FreeResource(hglob);

    "Free as in resources, not speech"

    — anonymous Linux advocate who’d been exposed to free beer

  19. Just processing messages until EndDialog.

  20. It specifies where the class name should be looked up.

Comments are closed.