# Using GBMDLGRX in your own REXX programs

## Introduction

GBMDLGRX has a simple and straightforward API consisting of 5 functions.
A typical usage in a REXX program looks like this:

    /* My REXX program */
    call RxFuncAdd 'GBMDLG_LoadFuncs', 'GBMDLGRX', 'GBMDLG_LoadFuncs'
    call GBMDLG_LoadFuncs

    /*** Show Open File Dialog ***/
    openFilename = ''
    openOptions  = ''
    button       = GBMDLG_OpenFileDlg('My File Dialog', 'openFilename', 'openOptions')
    if (button = "OK") then
    do
      say 'Opening bitmap file: 'openFilename
      say '       with options: 'openOptions
    end

    call GBMDLG_DropFuncs

## GBMDLGRX API function availability

The following API functions are available since the specified version of GBMDLGRX:

GBMDLGRX Version | API function name
--- | ---
1.00 | GBMDLG_LoadFuncs GBMDLG_DropFuncs GBMDLG_OpenFileDlg GBMDLG_SaveAsFileDlg
1.01 | GBMDLG_VersionRexx

## GBMDLGRX API Reference

    Function:  GBMDLG_LoadFuncs
    Syntax  :  call GBMDLG_LoadFuncs
    Params  :  none

    Info    :  Registers all functions and procedures of GBMDLGRX module.

    Example :

      /* Code in the procedure */
      call RxFuncAdd 'GBMDLG_LoadFuncs', 'GBMDLGRX', 'GBMDLG_LoadFuncs'
      call GBMDLG_LoadFuncs

    Function:  GBMDLG_DropFuncs
    Syntax  :  call GBMDLG_DropFuncs
    Params  :  none

    Info    :  Unregisters all functions and procedures of GBMDLGRX module.

    Example :

      /* Code in the procedure */
      call GBMDLG_DropFuncs

    Function:  GBMDLG_VersionRexx
    Syntax  :  version = GBMDLG_VersionRexx()
    Params  :  none

    Return  :  "major.minor" The version number of GBMDLGRX.DLL.

    Info    :  Query version number of GBMDLGRX module.

    Example :

      /* Code in the procedure */
      version = GBMDLG_VersionRexx()

    Function:  GBMDLG_OpenFileDlg
    Syntax  :  button = GBMDLG_OpenFileDlg('title', 'stem1', 'stem2')

    Params  :  title  in     - help window title
               stem1  in/out - filename
               stem2  in/out - options (comma separated)

    Return  :  "OK"      The OK button was selected. Filename/options
                         have been returned in stems.
               "CANCEL"  The CANCEL button was selected.
                         Filename/options are unchanged.
               "ERROR"   An error occured.
                         Filename/options are unchanged.

    Info    :  Shows the GBM Open File Dialog.

               Initially set values of stem1 and stem2 are used
               for configuring the open stateus of the dialog.

               The help window is shown when the help button
               or F1 is pressed. The help window title can be
               set to allow adapting it to the programs name.

    Example :

    /* Code in the procedure */
      openFilename = 'f:\mailtux.gif'
      openOptions  = 'index=2'
      button       = GBMDLG_OpenFileDlg('My File Dialog', 'openFilename', 'openOptions')
      say 'Open filename : 'openFilename
      say 'Open options  : 'openOptions
      say 'Button        : 'button

    /* Possible output */
      Open filename : e:\bitmap.tif
      Open options  : index=10
      Button        : OK

    Function:  GBMDLG_SaveAsFileDlg
    Syntax  :  button = GBMDLG_SaveAsFileDlg('title', 'stem1', 'stem2')

    Params  :  title  in     - help window title
               stem1  in/out - filename
               stem2  in/out - options (comma separated)

    Return  :  "OK"      The OK button was selected. Filename/options
                         have been returned in stems.
               "CANCEL"  The CANCEL button was selected.
                         Filename/options are unchanged.
               "ERROR"   An error occured.
                         Filename/options are unchanged.

    Info    :  Shows the GBM Open File Dialog.

               Initially set values of stem1 and stem2 are used
               for configuring the open stateus of the dialog.

               The help window is shown when the help button
               or F1 is pressed. The help window title can be
               set to allow adapting it to the programs name.

    Example :

    /* Code in the procedure */
      saveFilename = 'f:\my_bitmap.gif'
      saveOptions  = 'ilace'
      button       = GBMDLG_SaveAsFileDlg('My File Dialog', 'saveFilename', 'saveOptions')
      say 'Save filename : 'saveFilename
      say 'Save options  : 'saveOptions
      say 'Button        : 'button

    /* Possible output */
      Save filename : e:\bitmap.tif
      Save options  : ilace
      Button        : CANCEL