# 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:

- An additional options entry field
- File filtering based on bitmap formats supported by GBM.DLL
- A preview of the selected bitmap
- Basic bitmap information like size, colour depth and bitmap format

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 Version | Calling convention | API function name
--- | --- | ---
1.00 | _System | GbmFileDlg
1.31 | _System | GbmDefFileDlgProc

## 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.