Windows

Windows are areas that are visible on the screen and they serve as containers for objects. Windows will be placed at a position decided by the windowing system itself - it will try to centre them around the current cursor position. Windows can by default be moved with the mouse (by gripping the window header). There is always one window that is "in focus" i.e. that receives mouse commands and keyboard commands. If the same hot key is defined in several windows, the event of pressing that key will go to the focused window. So hot keys defined only in windows that are not in focus will be ignored. Hot keys may however be defined globally, and these will be handled even no matter which window is in focus. By default windows works like a stack: opening a new window makes that one be the active one displayed on top of the others. Closing a window lets the previous one be the active (top) window. There are several ways to override this, see MkDialogue for details.

About requesters: This is a special type of windows, that wait until the user answers, i.e. you can use it without the "event driven" style of the code, but rather like the classical linear programming like when using scanf, getchar etc. You should however know that the event processing is still running while your function is waiting for the requester to return. So if other events like serial port, time-events etc. occur, these will be put into the event queue and will be processed in proper order while the requester is up. Processing these events can, if needed, open new windows and requesters without any problem.

See also: Objects, Containers, Menus, Listboxes, Tabwindows.
int MkDialogue(int width, int height, const char *title, int options);

Creates a new window. The window is however not completed (and not visible) until you call `DisplayWin'. In between you should add some objects to make it meaningful.
Windows can be closed by `CloseWin'.
The created window will be the child of the window that is in focus when calling `MkDialogue'. The new window will automatically be set in focus when it is created. It will also be set to be the "operating window" (i.e. the one into which objects will be put when created).
In case you need to create multiple windows there are some window behaviour that needs to be discussed: In CGUI windows are arranged in a tree relation, where there is a virtual root and the the desktop (created by `InitCgui') is tha child of that. So if the first window you create has default settings it will be the child of the desktop. The properties that acomplishes the above behavior in CGUI are controlled by some optional flags listed below.
When using which? By default the window will be a child and a child is by default "modal", (non-floating).
Parameters: Return value: an id (in the same domain as objects).
See also: DisplayWin, CloseWin, ScrMode, SetFocusOn, Req, SetWindowPosition.
void DisplayWin(void);

`DisplayWin' must be called to complete a window and to make it visible. When adding various object into an opened window, these objects can not be completed immediately (e.g. their sizes and positions can in general not be computed until all of them are there). `DisplayWin' will do this completion, and also draw the objects onto the screen.
`DisplayWin' may also be called later on to make all its object refreshed. Such a repeated call will also re-build the window, which is necessary if you remove or add objects to the window after the first call to `DisplayWin'.
The window that will be affected is the one in focus.
See also: MkDialogue, Refresh, SetFocusOn.
void CloseWin(void *dummy);

Closes an open window. The parameter will not be used, it's there just to conform to the standard event-handler form - just pass a NULL-pointer.
The window that will be affected is the one in focus.
See also: MkDialogue, DisplayWin, SetFocusOn.
void SetWindowPosition(int x, int y);

By default a window will be opened at a position that is assumed to be convenient for the user (se `MkDialogue' for details). This automatic behaviour can be overridden by calling `SetWindowPosition' with the desired position (upper x,y is the upper left corner of the window) after `MkDialogue' but before `DisplayWin'.
See also: GetWinInfo, MkDialogue, DisplayWin.
void DesktopImage(BITMAP *bmp);

Sets the desktop image (the screen background).
If bmp refers to the screen, then a copy of it will created. (This memory will be properly released when CGUI terminates.) If bmp is a memory bitmap, this function will just take a copy of the pointer, so it is your responsibility to keep it as long as CGUI is alive, and then do destroy_bitmap(bmp).
If the size of the bitmap doesn't fit to the current size of the screen, then the following will be done: The desktop is not updated until `Refresh' is called. Use ID_DESKTOP for `id' when calling `Refresh'.


int Request(const char *title, int options, int width, const char *format, ...)

Opens a requester window of the same type as 'Req', but here you can specify the width of the text and also pass a format string of 'printf' type together with the necessary variable arguments.
Parameters: Return value: as for `Req'.
See also: Req, MkDialogue.
int Req(const char *title, const char *format);

A window for prompting the user for a simple question or givin some brief information in a simple way.
Parameters: In opposit to other windows functions, this one will wait until the user has clicked one of the buttons. Before it returns it will close itself, so don't do that.
Example of simple usage:
 switch (Req("Operation request",
            "Do you really want to do this?|~Yes|~No|Confirm_each ste~p")){
 case 0:
    do_it();
    break;
 case 1:
    return;
 case 2:
    confirm();
 }
 
Return value: The push-button number that the user selected. 0 is the first button in format string, 1 is the next etc.
See also: Request, Labels.
void RedrawScreen(void);

Redraws the entire screen. All windows that are at least partly visible on the screen will be redrawn.


void GetWinInfo(int id, int *x, int *y, int *width, int *height);

Returns the coordinates and size of the specified window. The results will be given in screen coordiantes (with (0, 0) in upper left corner).
See also: SetWindowPosition.
int CurrentWindow(void);

Returns the id number for the current operating window.
See also: SetOperatingWindow, SelectContainer.
void SetOperatingWindow(int winid);

Sets a new window to be the the "operating window". Most functions that operates on objects require an id-key for reference. For your conveniance that is not necessary when creating new objects, they will be put into the most recently created container in the most recently created window. That is the "operating window". Normally the operating window is the same as the one in focus. Occasionally you may later on want to add some objects to a window that is not in focus. Then you must use `SetOperatingWindow' (and maybe also SelectContainer) before adding the objects. Just use the id-key returned when the window was created, and pass it to SetOperatingWindow.
See also: CurrentWindow, SelectContainer.
int MkProgressWindow(const char *wlabel, const char *blabel, int w);

A simple progress-bar window containing a progress bar and a status field.
Parameters: Return value is the id of the window. This can be used to update the current value by calling UpdateProgressValue'.
See also: UpdateProgressValue, AddProgressBar.

Back to contents