gwenhywfar  5.11.1beta
Modules
Graphical User Interface

This module contains the definition of GWEN_GUI. More...

Modules

 GUI Implementation for the Console
 

Detailed Description

This module contains the definition of GWEN_GUI.

The concept of this module is to have a single GWEN_GUI object per application which is created at the start of your application. This GWEN_GUI object tells Gwenhywfar (and libraries using the GWEN_GUI-mechanism) how to handle user interaction.

The GWEN_GUI object contains callbacks for message display, user input, progress reports, SSL certificate checking etc.

There are implementations of GWEN_GUI based on console, QT4, QT5 and FOX.

GWEN_GUI uses flags to tell implementations what the caller needs of the GUI implementation.

Callbacks which might create windows when using graphical user interfaces like QT or FOX return GUI IDs (like GWEN_Gui_ProgressStart()). These ids can be used to create window stacks. The implementation can freely choose how to generate those ids. The only fixed definition is that a GUIID of 0 refers to the last opened context (opened by e.g. GWEN_Gui_ProgressStart()).

A simple example of how GWEN_GUI is used:

uint32_t pid;
"Progress-Title",
"This is an example progress with 2 steps",
2,
0);
"MessageBox-Title",
"This message box should appear in the context of the open progress dialog",
"Button1",
"Button2",
"Button3",
pid);
GWENHYWFAR_API uint32_t GWEN_Gui_ProgressStart(uint32_t progressFlags, const char *title, const char *text, uint64_t total, uint32_t guiid)
#define GWEN_GUI_PROGRESS_SHOW_PROGRESS
Definition: gui.h:197
#define GWEN_GUI_MSG_FLAGS_TYPE_INFO
Definition: gui.h:281
GWENHYWFAR_API int GWEN_Gui_ProgressEnd(uint32_t id)
GWENHYWFAR_API int GWEN_Gui_MessageBox(uint32_t flags, const char *title, const char *text, const char *b1, const char *b2, const char *b3, uint32_t guiid)
GWENHYWFAR_API int GWEN_Gui_ProgressAdvance(uint32_t id, uint32_t progress)

In this example a progress context is started (with the GUIID stored in the variable pid). Then in this context a message box is opened and finally the progress context is closed.

As seen in the example above the GUI ID returned by GWEN_Gui_ProgressStart() is used as argument GUIID of the function GWEN_Gui_MessageBox(). Effectively this makes the message box appear in the context of the open progress.

An implementation which uses a graphical interface (QT, FOX) will most probably use windows for GWEN_Gui_ProgressStart() and GWEN_Gui_MessageBox(). In such a case the GUI IDs shown above can be used to establish a parental relationship between those windows. In the example above the message box will have the open progress dialog as parent window.

However applications can use additional mechanisms to determine parent windows. QBankManager for example uses its own GWEN_GUI implementation based on QT3. It contains methods for maintaining a stack of parent windows. So whenever QBankManager wants GWEN_GUI user interaction to appear in a special window it calls QGui::pushParentWidget() just before calling Gwenhywfar or AqBanking functions which might need user interaction and QGui::popParentWidget() directly therafter.

This mechanism makes it unnecessary to have multiple GUI objects. In fact using multiple GWEN_GUI objects is strongly discouraged. The implementation should use the GUIID parameter of each callback instead to establish a relationship between multiple windows.