Using GBMDLG in your own programs

Introduction

GBMDLG has a simple and straightforward C-API consisting of 1 function only. It subclasses the OS/2 standard file dialog and provides extended functionality by using GBM.DLL:

The GBM File Dialog can also be used as modeless dialog just like the standard OS/2 file dialog. Just set the appropriate flags in the GBMFILEDLG.fild.fl.

Subclassing is supported since version 1.31 (see bldlevel gbmdlg.dll). The mechanism is the same as for the standard OS/2 file dialog. Instead of calling WinDefFileDlgProc in your subclass handler function, GbmDefFileDlgProc must be called.

There is an import library provided (gbmdlg.lib) that can be linked to the program that needs access to the GBMDLG.DLL API.


GBMDLG.DLL API function availability

The following API functions are available since the first version of GBMDLG.DLL:

GBMDLG.DLL VersionCalling conventionAPI function name
1.00_SystemGbmFileDlg
1.31_SystemGbmDefFileDlgProc

Example program

A typical usage of GBMDLG.DLL in a C/C++ program is shown below. The example program below shows the "File open..." file dialog and prints the selected filename and the options to stdout.

#define INCL_WIN
#include <os2.h>

#include <stdlib.h>
#include <stdio.h>
#include <string.h>
#include "gbmdlg.h"

/* My program */
int main(int argc, char *argv[])
{
  char message[CCHMAXPATH+50] = { 0 };

  GBMFILEDLG gbmfild;

  HAB hab = NULLHANDLE; /* Anchor-block handle  */
  HMQ hmq = NULLHANDLE; /* Message queue handle */

  /* Initialize PM */
  hab = WinInitialize(0);
  if (hab == NULLHANDLE)
  {
    return 1;
  }
  hmq = WinCreateMsgQueue(hab, 0);
  if (hmq == NULLHANDLE)
  {
    WinTerminate(hab);
    return 1;
  }

  /* Init the FILEDLG substruct and configure the dialog style. */
  memset(&(gbmfild.fild), 0, sizeof(FILEDLG));
  gbmfild.fild.cbSize = sizeof(FILEDLG);
  gbmfild.fild.fl     = (FDS_CENTER | FDS_OPEN_DIALOG);
  strcpy(gbmfild.fild.szFullFile, "");
  strcpy(gbmfild.szOptions , "");

  /* Create and show the GBM File Dialog. */
  if (GbmFileDlg(HWND_DESKTOP, HWND_DESKTOP, &gbmfild)
      == NULLHANDLE)
  {
    WinMessageBox(HWND_DESKTOP,
                  HWND_DESKTOP,
                  "Couldn't show GBM File Dialog.",
                  "My program",
                  0, MB_OK | MB_ERROR | MB_MOVEABLE);
    return 1;
  }

  /* Was OK button pressed? */
  if (gbmfild.fild.lReturn == DID_OK)
  {
    sprintf(message, "Filename: %s\nOptions: %s", gbmfild.fild.szFullFile,
                                                  gbmfild.szOptions);

    WinMessageBox(HWND_DESKTOP,
                  HWND_DESKTOP,
                  message,
                  "My program",
                  0, MB_OK | MB_INFORMATION | MB_MOVEABLE);
  }
  else
  {
    WinMessageBox(HWND_DESKTOP,
                  HWND_DESKTOP,
                  "No file selected.",
                  "My program",
                  0, MB_OK | MB_INFORMATION | MB_MOVEABLE);
  }

  WinDestroyMsgQueue(hmq);
  WinTerminate(hab);

  return 0;
}

The example program does not support the online help functionality available by the GBM File Dialog to the user (F1 or Help button). As attaching the dialog to the help manager is a bit more complicated, please have a look at the gbmv2 application or, a bit smaller, the GBM File Dialog REXX adapter library GBMDLGRX. Both implement help support.