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:
- How a window is displayed relative to other windows (which
properties and states forces a window to be displayed on top of
other).
- Window "focus". Which properties and states makes it possible for
the user to alter the window beeing in focus. (Focus means that the
window receives keyboard and mouse events. The focus is normally
indicated to the user with some kind of highlighting).
- The life of a window. Since the meaning of one window may depend on
another window's existance, there may also be need for
"navel-strings" between windows (child - parent relation).
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 existense of at least one modal (non-floating) child, implies
that a window can not get the focus.
- A child is unconditionally displayed on top of its parent. This
means that even if the parent is in focus, the child will be on top.
- A floating window being in focus will be displayed on top of all
its floating sisters (and all siblings of these).
- A non-floating window beeing in focus will be displayed on top of
all its non-floating sisters (and all siblings of these).
- A floating window will at any time be displayed on top of all
its non-floating sisters (and all siblings of these).
- A child will always die when its parent dies.
The properties that acomplishes the above behavior in CGUI are controlled
by some optional flags listed below.
When using which?
- The simple (and probably most common) usage is the
deafault (i.e. a modal child), requireing that the user closes the
latest created window and thereafter finds the focus being on the
parent.
- The "floating" property of a child may be useful e.g. if you want to
create tool-palette window(s). The main window will be accessed at
any time (i.e. the user can make it in focus by a mouse click),
giving the ability to alter between picking tools from the
tool-palette and work with stuff in the main window (including
creating other palettes).
- The "sister" property may be useful e.g. to
- create a "globally floating" window to display the progress
or state of some work in the background. It may also be useful
for some kind of tool-palettes that one want to be available in
all windows. This can be achieved by making it a sister to the
desktop (floating or non-floating) or as the sister to the
first "main" window (floating).
- create a group of non-floating windows, the focus possible to
alter between them but can not move to the parent.
By default the window will be a child and a child is by default "modal",
(non-floating).
Parameters:
- width, height: specifies the dimensions of the window. These
values may be replaced by the ADAPTIVE command which will
make the window adapt its size to be large enough to show all its
objects. It may also be replaced by the FILLSCREEN command which
simply sets the size to the current desktop size. If the desktop size
is later on changed because the screen mode is changed by ScrMode,
then all windows will automatically be redrawn, and a FILLSCREEN
window will again take its size from the desktop dimensions.
- title: this is any text that will be displayed in the top bar of
the window, e.g. to explain the purpose of the window to the user.
- options: if you don't need any of the options listed below, then
just pass 0. Currently available options are listed below and can
be combined with logical or.
- W_FLOATING: The opened window will be a floating window. This means
that it will
- W_SIBLING: The opened window will be the sister of the currently
focused one. W_FLOATING and W_SIBLING can be combined. To mix
non-floating and floating sisters is allowed but not always
meaningful. The behaviour will be as stated above.
- W_NOMOVE: By default, windows allows the user to drag and drop
them on the screen. This behaviour will be disabled by the
flag W_NOMOVE.
- W_TOP: The vertical position will be at the top of the screen.
- W_BOTTOM: The vertical position will be at the bottom of the screen.
- W_LEFT: The horizontal position will be at the left side of the
screen.
- W_RIGHT: The horizontal position will be at the right side of the
screen.
- W_CENTRE_H: The horizontal position will be in the centre of the
screen.
- W_CENTRE_V: The vertical position will be in the centre of the
screen.
- W_CENTRE: The horizontal and vertical position will be in the centre
of the screen.
If no position option is specified the window will be positioned
centered around the current mouse position.
If only one of the vertical and horizontal positions is specified by
the above option flags then the other will be set to 0.
In addition to the above special position options, a window can be
placed at an arbitrary position, see `SetWindowPosition'.
Return value: an id (in the same domain as objects).
See also:
DisplayWin,
CloseWin,
ScrMode,
SetFocusOn,
Req,
SetWindowPosition.
`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.
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.
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.
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:
- If bitmap is larger: it will be scaled to the size of screen.
- If bitmap is smaller: it will be repeatedly blitted to fill screen
allowing you to draw patterns.
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:
- title: as for `Req'.
- options: the position codes as described under MkDialogue
- width: The width of the requester. A value of 0 will give the default
size (the same as for `Req')
- format: as for `Req' but in addition it can contain format info like
in the format string to the `*printf' functions.
- ...: Additional parameters corresponding to the format specifiaction
(i.e. like the `*printf' functions).
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:
- title: The text that will be displayed in the title bar of the requester
window. If you don't need a title, then pass the empty string ("").
- format: This is a string containing some special info to create the
buttons and their layout.
- Any info-text you want to be displayed, followed by:
- At least one push-button label. Each label must be separated from
the previous one (or the info-text) with the '|'-character. Each
button label may optionally contain any optional characters that a
labels in general can contain.
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.
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.
Returns the id number for the current operating window.
See also:
SetOperatingWindow,
SelectContainer.
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.
A simple progress-bar window containing a progress bar and a status
field.
Parameters:
- wlabel - A pointer to a string which will be used as informational
text in the window header. Pass an empty string if not needed.
- blabel - A pointer to a string which will be used as the label
on a button that gives the user the opportunity to close the window.
Pass an empty string if you don't want the button to be there.
- w - The width of the progress-bar.
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