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
(pressingEnter
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.
// 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
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: