# Dialog API 1.0

Attention!

- All Dialog API details are written with taking named unions of the FarDialogItem structure into account. For more details see the description of _FAR_NO_NAMELESS_UNIONS.

Dialog API represents an individual API beginning from FAR Manager version 1.70. What's in it for plugin developers? The main thing is higher control over the created dialog.

There're two different dialog types:

- Dialogs of so-called "About" style (FAR version 1.65 and below)
- Extended style dialogs - those using the dialog callback function.

Regardless of the style used, dialog manager v1.0 supports only so-called Modal Dialogs. This dialog represents a window which disables user interaction with any FAR Manager object outside the boundaries of the dialog. The modal dialog cuts off all keyboard/mouse events sent to other FAR Manager objects.

### "About" style

It's simple - UNCONTROLLABLE DIALOGS! Dialogs of this type are created with either Dialog or DialogEx function call with the DlgProc parameter set to NULL.

This style defines the following dialog behavior:

- any changes in control element state become known to the plugin only after dialog is closed;
- dialog is closed when user presses one of the following keys: `Esc`, `Ctrl-Enter`, `Enter` (pressing `Enter` closes the dialog regardless of which control element has the focus, with the exception of edit boxes with DIF_EDITOR flag set), or clicks a mouse button beyond the dialog bounds.
- This style is intended for simple dialogs.

### "Extended" style

This is the most interesting style. Plugin has ultimate control over the dialog.

- dialog has its own callback function which reacts to a lot of messages sent by the Dialog Manager;
- the callback function communicates with the Dialog Manager by sending messages with the SendDlgMessage function;
- the callback function can delegate control to the Dialog Manager with the DefDlgProc function;
- when user tries to interact with inaccessible FAR Manager objects, clicking mouse buttons outside the dialog, the Dialog Manager warns him/her with beeps.
- the plugin is in control of the dialog session ending.
- this style is intended for dialogs implementing complex user interaction logic.

If one simply delegates control to the kernel in a dialog callback function with the DefDlgProc function call, then one gets simple About-styled dialog:

    // dialog callback function with minimal code
    LONG_PTR WINAPI MyDlgProc(HANDLE hDlg,int Msg,int Param1,LONG_PTR Param2)
    {
      return Info.DefDlgProc(hDlg,Msg,Param1,Param2);
    }

Choosing dialog style is simple:

- to create a dialog with one InputBox choose simple About style - the lesser the code the simpler the result, reducing possibility of errors;
- to create more complex plugins (game, calculator, querying a database using ODBC, etc.) choose Extended style as it provides complex logic, dynamic controls, advanced user interaction (on which may depend sunsequent actions), etc..

Well then, the Dialog API v1.0:

Functions
Structures
Macros and types
Dialog elements
Dialog element flags
Events and Messages
Input focus
Working with lists

### Remarks

To get more familiar with the Dialog API see the `dialog.cpp` file from "Reversi" plugin sources.
See also:
Exported functions, Service functions, Structures, Archive support, Addons