Window objects may be of different types. Below is a list of the "simple"
types. You can find contaners and menus in other sections.
A window object is an object that is in a window. It is assigned a
rectangular area within this window, and it has the full responsibility
for that area. This responsibility includes:
- Drawing on it - if it does not draw anything, the content of that
area is undefined.
- Receiving messages from the mouse.
- Receiving messages from the keyboard.
These tasks are performed automatically - you don't need to bother about
_how_ to do it, but maybe you need to know that it works in this
way (in fact an object also has some more tasks that we don't talk about
for the moment).
As a consequence of the above, there will be problems if simple objects
like push buttons etc., overlap each other (which of them should draw and
which of them should receive mouse messages?). To make it easy for you
to avoid overlapping, you can use direction commands rather than
specify the coordinates of the object; see the
"Direction commands for object positioning" section.
How do you know the width and height of an object? In fact you normally
don't need to bother about this in CGUI - the objects will adapt their
size to be large enough. For example:
- A text labelled check box will be as wide as is needed to show its
label and check mark. The height will be the height necessary for the
text.
- A push-button with an image and a text label will be large enough to
show both the label and image.
Some types of objects need explicit coordinates (e.g. the width field
of edit boxes), see the specific object type for more information.
Also note that to create a nice interface you may use the container
facility to create subgroups of objects. Containers are discribed in
another section.
See also:
Containers,
Windows,
Menus,
Listboxes,
Tabwindows.
int AddButton(int x, int y, const char *label,
void (*CallBack) (void *data),
void *data);
This function creates the standard type of push button.
Parameters:
- x,y: The position of the object (or you can use "direction commands").
- label: the label text that will be displayed on top of the button,
see general text label info for details. The text labels for buttons
may contain one additional command, with the syntax "#name;" where
`name' is the name of a registered image (see `CguiLoadImage' for
details). The meaning of this is that the
image `name' will be drawn on top of the button instead of a text.
If there is both a text label and an image specified, then the label
will be drawn below the image.
The label text may also contain an underscore. This will be
recognised as as a "newline" command and the label will be drawn
in two partitions. The '_' will not be drawn.
The text will be centred.
- CallBack: A pointer to a function written by you, which will be
called when the user clicks the button.
- data: A pointer to any data you want, which will be passed along
to `CallBack' (You should of course not use local variables for
this, since they will not exist when you exit the calling function).
The default behaviour is to ignore right mouse button clicks.
Return value: an identification key to the object.
See also:
CguiLoadImage,
AddIcon,
Direction commands for object positioning,
Labels.
int AddCheck(int x, int y, const char *label, int *sel);
This is a check box which toggles between being on and being off when the
user clicks it. `sel' points to an integer, which is 1 for on and 0 for
off.
Return value: an identification key to the object.
See also:
AddRadioButton,
AddDropDown,
AddCheck,
Direction commands for object positioning,
Labels.
int AddFlip(int x, int y, const char *label,
const char *const*strs, int *sel);
This is like a check box, but displayed differently: `strs' is an array
of two strings, the first of which will be displayed when `sel=0' and the
second when `sel=1'.
Return value: an identification key to the object.
See also:
AddRadioButton,
AddDropDown,
AddCheck,
Direction commands for object positioning,
Labels.
To create a group of radio buttons, call first this function, then add
the radio buttons using `AddRadioButton', and finally call
`EndRadioContainer' to finish.
Return value: an identification key to the container.
Prameters:
- x,y: The position of the object (or you can use "direction commands").
- var: Points to an integer describing which radio button is selected.
The first button that you add is number 0, the second is 1, etc.
- direction: Specifies whether the sequence of buttons shall be placed
vertically or horizontally. Use macros R_HORIZONTAL and R_VERTICAL.
In case of R_HORIZONTAL it also recognises the optionally EQUALWIDTH.
Return value: an identification key to the container.
See also:
EndRadioContainer,
AddRadioButton,
AddFlip,
AddCheck,
AddDropDown,
Direction commands for object positioning.
Adds a radio button to a radio button sequence. The first button added
will get number 0, next 1 and so on. To start a radio button sequence,
call `MkRadioContainer'.
Return value: The id number of the button.
Parameter:
- label: The label to be displayed on the button, following the
same specification as for buttons.
Return value: an identification key to the object.
See also:
MkRadioContainer,
EndRadioContainer,
AddButton,
AddHandler,
MkMenuRadio,
Labels.
Terminates a sequence of radio buttons. If you don't terminate it,
subsequent objects will go into the same container and your window will
not look very nice.
See also:
AddRadioButton,
MkRadioContainer.
int AddIcon(int id, int x, int y, const char *iconname,
void (CallBack)(void*), void *data);
This function adds an icon object to the specified node. An icon object
is a bitmap with a caption underneath The image is specified in the label text, just like with
buttons.
Icons can be placed on any window. Icons are not draggable by default!
You can obtain the current position of the icon by calling
`GetObjectPosition' (this can be useful e.g. if you want the program to
arrange the icons in the same way next time you start it).
Return value: The id number of the icon.
Parmeters:
- id: The node to put the icon into
- x,y: The position of the icon.
- label: The syntax and meaning of the string is the same as for
`AddButton'.
- CallBack: A pointer to your function. It will be called when the
user made a successful click on the icon.
- data: A pointer to any data. It will be passed to your function when
called.
Return value: an identification key to the object.
See also:
AddButton,
GetObjectPosition,
Labels,
CguiLoadImage.
Gives the current position (top left corner) of an object.
Parameters:
- id: The object asked for
- x, y: The coordinates (relative to the container it exists in).
- wx, wy: The coordinates related to window it exists in.
Return value: 1 if ok 0 if error (i.e. invalid id).
See also:
AddIcon,
GetWinInfo.
int AddDropDown(int x, int y, int width, const char *label, int *sel,
const void *data, int n,
void (*CallBack) (const void *data, int i, char *s));
Drop down boxes can be used for the same purpose as radio buttons, i.e.
let the user make a selection from several alternatives. The selection
will be reflected in the program as one of the values in the range
[0..n-1] The DropDownBox uses another way for presentation of the
alternatives. The DropDownBox requires less space in the dialogue window
than the radio-buttons. On the ohter hand it is required one extra
command to make the different alternatives visible (dropped down).
If there are lots of alternatives or if there are lots of controls in the
dialogue window, the DropDownBox is to prefer.
To achieve the result of a selection - just examine your value pointed to
by sel. This can typically be done when the dialogue window is closed.
Optionally this may be done by an additional call-back function, which
will be called after each selection made by the user. See AddHandler
If the DropDownBox shall be used just to display a certain state or
setting, rather than to provide a control to the user: use `DeActivate'
Parameters:
- x,y: The position of the object (or you can use "direction commands").
- width: the width in pixels of the display field (the width of the
label is not included). If width is set to 0, a width enough to
display any of the alternatives without clipping, will be
calculated.
- label: an optional text-label for the box
- sel: a pointer to the variable that controls the selection (and that
will be updated when a new selection is made by user).
- data: pointer to any of your data to create the list of text
alternatives from
- n: the number of alternatives
- CallBack: a pointer to a function that you must write. This function
will always be passed "data" as its first parameter when called. The
second parameter will be a number in [0..n-1]. The function shall
use the two first parameters to create a string "s", which after
return will be the text associated with number i.
Return value: an identification key to the object.
See also:
AddDropDownS,
Activate,
DeActivate,
AddHandler,
Direction commands for object positioning,
Labels.
int AddSlider(int x, int y, int length, int *ctrl, int start, int end,
int option, int id);
The default direction of a slider is horizontal.
Parameters:
- x,y: The position of the object (or you can use "direction commands").
- length: the length of the slider (this is the actual sliding length,
the size of the entire object may be larger than this).
- ctrl: a pointer to some variable of your program which value
controls the position of the slider handle, and that is affected by
the user actions.
- start: the min-value of `ctrl'
- end: the max-value of `ctrl'
- option: either of:
SL_SCALE - A scale will be drawn. The slider will use `length' and
(end - start) to decide how to draw the scale.
SL_LABEL - Numbers (start and end) will label the slider.
SL_STYLE1 - The slider will be drawn in an alternative style (diamond)
SL_STYLE2 - The slider will be drawn in an alternative style (slide-rule)
SL_STYLE3 - The slider direction will be vertical (the specified
`length' will be the height rather than the width of the sliding).
- id: an optional reference to some other object, that will be
updated during sliding. This can be used to display the exact value
in e.g. an editbox.
Return value: an identification key to the object.
int AddDropDownS(int x, int y, int width, const char *label,
int *sel, const char * const *strs, int n);
This is a simplified version of AddDropDown. I can be used only if your
text-alternatives happens to be an array of pointers to strings.
In other respects it is equivalent to AddDropDown.
Return value: an identification key to the object.
See also:
AddDropDown,
Direction commands for object positioning.
int MkCanvas(int x, int y, int width, int height,
void (*CallBack)(BITMAP *bmp, int x, int y, void *data),
void *data);
This function will create a canvas on which your function `CallBack' may
draw whatever it want. It will be called each time the mouse generates an
event, i.e. when the position or button state has changed. The current
co-ordinates will be passed to the call-back together with
the private data. If you will also examine all key-presses, you can
install a new KeyBoard handler.
Parmeters:
- x,y: The position of the object (or you can use "direction commands").
- width, height: the size of the canvas
- CallBack: A pointer to your function. It will be called each time
there is some change in the mouse state or position. It will also be
called when a refresh is requested (initially by DisplayWin and any
call to Refresh with id or with the id of any predecessors of `id').
`CallBack' can get the mouse-button state from the Allegro variable
mouse_b.
If `CallBack' make som drawing on bmp, these will not be visible on
the screen until Refresh has been called.
Parameters to `CallBack':
- x,y: the current position of the mouse in local co-ordinates of
the bitmap `bmp'. When called because of initialisation the
function will be passed -1 as value for `y'. The first call is
guaranteed to come before any mouse event. Your function must be
prepared to receive an initialisation call also later (CGUI may
need to do this whenever the window or any container containing
the canvas are re-built).
Subsequent calls because of a `Refresh'-call will pass -1 as
`x'-value.
- data: the pointer data is passed
- data: A pointer to any data. It will be passed to your acll-backi
function when called.
Return value: an identification key to the object.
See also:
InstallKBHandler,
Direction commands for object positioning,
SetBlitLimit,
cgui_use_vsync.
This function may be used to reduce the area of an object that CGUI blits
to screen. It must be called prior to the call to Refresh, and has effect
only during that call (you must call it each time). The coordinates shall
be related to the object and are inclusive. The function is only
meaningful to call for canvas object blitting.
The call to SetBlitLimit is not identical to a call to set_clip.
A global variable that may be used to switch off vsync in CGUI (it is
set to 1 by default). CGUI uses vsync when Refresh or DisplayWin is
called directly or when these functions are indirectly called.
int AddTag(int x, int y, const char *tag);
Tag is simple text object with the default grey background and it
doesn't handle any events, and it is not outlined in any way.
Parameters:
- x,y: The position of the object (or you can use "direction commands").
- tag: the text to display
Return value: an identification key to the object.
See also:
AddStatusField,
AddTextBox,
Direction commands for object positioning.
int AddEditBox(int x, int y, int width, const char *label, int format,
int maxchar, void *data);
This function creates an edit box, which lets the user edit the text
"data", and is formatted according to "format".
Return value: id number of the edit box.
Parameters:
- x,y: The position of the object (or you can use "direction commands").
- width: the width of the edit field of the edit box (not counting
the label)
- label: text label placed to the left of the edit-field
- format: the type of the data
- nochar: maximum number of characters (applicable if format is
FSTRING)
- data: the text to be edited, i.e. a char*.
Return value: an identification key to the object.
See also:
Format specifications of edit-boxes,
AddHandler,
GetEditData,
SetEditData,
TabOnCR,
SetFocusOn,
AddStatusField,
AddTextBox,
Direction commands for object positioning,
Labels.
Makes the carriage returns work like tabs in an edit-box, i.e. focus
moves to next object in the tab-chain. Useful if you have a number of
edit-boxes in a dialogue window, and the user are supposed to enter a
large amout of data.
Returns 0 if it fails (i.e. id is invalid) else non-0.
See also:
AddEditBox.
If you adds an optional callback to an edit-box (with a call to
AddHandler) you may be interested in the current keypress, or maybe of
the current position in the string. Maybe you are also interested in
changing these values. Use GetEditData and SetEditData functions for
this.
Parameters:
- scan,ascii: the memory location pointed to by scan/ascii will be
updated with the current key-press. NOTE! if editing is in progress
and the user terminates the editing by some action that forces the
editing to be terminated, the ascii value will be as for "enter",
i.e. '\r' but the scan value will be set to TERMINATE_EDIT
- offset: a pointer to the position within the string.
See also:
AddEditBox,
SetEditData,
AddHandler.
If you adds an optional callback to an edit-box (with a call to
AddHandler) you may be interested in the current keypress, or maybe of
the current position in the string. Maybe you are also interested in
changing these values. Use GetEditData and SetEditData functions for
this. Note! You are only allowed to call these function from within the
callback function. If not, the calls will be ignored.
Parameters:
- scan,ascii: the previously pressed keys will be replaced with the
passed values, and the current position will be updated to curpos
(before processing the keys)
- offset: a new print position within the string.
See also:
AddEditBox,
GetEditData,
AddHandler.
int AddStatusField(int x, int y, int width,
void (*FormatFunc)(void *data, char *string),
void *data);
This function creates an object in which a single row-text may be
displayed. The field reserved for text is of fixed width and height (the
height is enough to display one row of text) and is outlined by a frame.
The text will be right aligned and clipped if necessary.
The text will be produced by the function `FormatFunc', which is a
function that you must write. `data' is a pointer to any of your data,
and it will be passed to `FormatFunc' whenever called.
The difference to `AddTag' is that the status-field may change the text
from time to time. A typical use is to display some value or text that
will change from time to time.
Save the id-number and when, for some reason data changes, just call
Refresh(id);
The status field will be put into the current node. It may be a good idea
to create a specific container using `StartContainer' e.g. at the bottom
of a window, for this purpose.
Parameters:
- x,y: The position of the object (or you can use "direction commands").
- width: the width of the text-field
- FormatFunc: a call-back function called when text is to be drawn
- data: a pointer to some data
Return value: an identification key to the object.
See also:
AddTextBox,
AddEditBox,
AddTag,
Refresh,
StartContainer,
Direction commands for object positioning.
Adds a progress bar. The current value can be updated by a call to
`UpdateProgressValue'.
Return value: an identification key to the object.
See also:
UpdateProgressValue,
MkProgressWindow.
Updates the value of the progress bar `id'.
Returns 1 on sucess, 0 if `id' does not exist or does not refer
to a progress object.
See also:
AddProgressBar,
MkProgressWindow.
int AddTextBox(int x, int y, const char *string, int width, int nrows,
int options);
Creates a simple multi-row text-box. This can be used for various
purposes, typically:
- To display a brief info-text in a dialogue, where you always want
the entire text to be shown and don't want to fiddle with the
height needed.
- To display a not too long info-text (or a text which exact length is
not known at compile time, but known to be not to long) in a
dialogue, where you always want the entire text to be shown and
don't want to fiddle with the height needed. The box is able to
adapt its size to the contained text.
- To display a text which length you know nothing about. You can then
put a limit on the hight of the box (e.g. so that it doesn't get
a size much larger then the screen), in which case it automatically
gets a browsing object.
The default behaviour (if `nrows' and `options' are set to 0) is to
automatically control the line-feeds. The text will be broken into rows
to fit the specified width. Sequences of more than one whitespace will be
displayed as one single space. The line-feeds will be inserted at
whitespace positions (if possible). The height of the box will be the
height that is required to display the text. This behaviour can be
overridden, see details below
A copy of the text pointed to by `string' is used.
Parameters:
- x,y: The position of the object (or you can use "direction commands").
- string: the text to display
- width: the text width in pixels (the frame will occupy some more
pixels).
- nrows: If non-zero forces a browsing object to be attached to the
text-box, and the box will be of the fixed height that is required
to contain `nrows' number of rows using the current font. If the
text is longer than `nrows' the browsing object will
be active. A combination with the `TB_PREFORMAT' option usually
makes it more useful.
- options: Just pass 0 if you need none of them, or:
- TB_FRAMERAISE will outline the text with a raised frame.
- TB_FRAMESINK will outline the text with a sunked frame.
- TB_PREFORMAT will handle each whitespace character
individually. Line-feed characters will force newlines
whenever they occure. Multiple spaces in sequence will be
drawn as they are defined in the font in use. The default tab
width is 8. If you want some other setting, just att that number
to the option flags. Lines that are too long to fit into the
current width of the text-box, will be truncated.
- TB_LINEFEED_ If you don't use the option `TB_PREFORMAT', i.e.
let the box do automatic line feeds to fit the text into the
specified width, you may still want to force new lines. You can
do that useing this option. Use the character '_' (underscore)
to indicate where to force line fieeds. (The '_' conforms to the
`mktext' utility, see the tools directory of CGUI). If you need
to draw an '_' just use two in sequence so to insert multiple
linefeeds in sequence, you have to put a space between
the underscores, like "_ _". This option can not be combined
with `TB_PREFORMAT'.
- TB_FIXFONT will use CGUI's built-in fix-font.
- TB_WHITE will set the text background to white instead of the
default grey.
- TB_TEXTFILE The `string' parameter will be used as the name
of a file. That file will be loaded and the contents of it will
be displayed.
- TB_FOCUS_END This has only meaning if the textbox has fixed
height (i.e. nerows is non-zero), and the effect will be that the
last line of text to disply will be shown (if more than one
page to view than the top part will be scrolled out). If you
change the content of the box it will be browsed to the end again.
Use `UpdateTextBoxText' if you need to change the displayed text.
Return value: an identification key to the object.
See also:
AddStatusField,
AddTag,
AddEditBox,
Direction commands for object positioning,
MakeStretchable,
UpdateTextBoxText.
Changes the current text of the textbox `id' to the string pointed to
by `string'. A copy of the text is made.
Returns 1 on sucess, 0 if `id' is not valid or does not refer
to a text object.
See also:
AddTextBox.
int HookSpinButtons(int id, int *var, int delta1, int delta2,
int minv, int maxv);
Creates a pair of spin-buttons. These let the user change the value of
the integer variable pointed to by `var'. The value will be increased
by a mouse-press on the up-arrow, and decreased by a press on the down-
arrow.
Return value is the id of the conainer that will be created for the
spin-buttons.
Parameters:
- id: The spin-buttons will be put immediately to the right of the
object refered to by `id'. After a user click and during a "scroll"
the object `id' will be refreshed in order to maintain a correct
displayed value. Typically `id' may refer to an edit-box, but in
some cases a status-field will be better (rarely a drop-down would
be prefered). There are no restrictions on the type of object of
`id'.
- var: A pointer to the variable which value will be uppdated by
the spin-buttons. The memory must of course be allocated while
processing.
- delta1: the steps of increment/decrement at low value of `var'
- delta2: the steps of increment/decrement at high value of `var', use
same value as for delta1 if you want it to be constant for the
entire interval. If delta1 and delta2 differs the currently used
delta will change linear over the value-interval.
- minv: the lower limit of the value of the variabel pointed to by
`var'
- maxv: the upper limit of the value of the variabel pointed to by
`var'
Return value: an identification key to the object.
See also:
AddEditBox,
AddStatusField.
Redraws a specific win-object. If the object contains (recursively) other
object these will also be refreshed.
This function activates an inactive object. An object must be active to
take notice about events like mouse-clicks and hot-keys. Some object
types reflects their `active state' by the colour of its text label.
To make a change visible it is necessary to call Refresh(id);
The default state of an object after its creation is active.
See also:
Refresh,
DeActivate.
The function makes an object inactive, i.e. the object will not take
notice about events like mouse-clicks and hot-keys. Some object
types reflects their `active state' by the colour of its text label.
To make a change visible it is necessary to call Refresh(id);
An inactive object may be re-activated by a call to the function
`Activate'.
See also:
Refresh,
Activate.
void SetObjectGrippable(int id,
void *(*Grip)(void *src, int id, int reason),
int flags, int buttons, void *data);
Set the specified object as grip-able, which means that the user may grip
the object by use of mouse-button (with the intention to later on drop it
somewhere else).
NOTE! An object can't be both "slidable" and "grippable".
This means that objects that by default has the slidable propery
set, will loose that when beeing set to "grippable". For the moment this
will probably only affect edit-boxes, which may loose the ability to get
text marked by use of the mouse if they are set "grippable" with use of
left mouse button (i.e. mouse down and moving will be interpreted as a
drag-drop in stead of as marking text in that case, since there are
obviously no way to ditinguish between the two operations).
You must be aware that the drag-drop mechanism can be used very
dynamically, and carefully handle your pointers. Several disjunct or
overlapping drag-drop channels may be used in parallel (use the flags to
distinguish the data objects dropped). The hot-key handler is in work
during the drag-drop operation, so the user can e.g. close
the window from where the object was gripped, implying that the object
returned by grip must not rely on its window being open.
Parameters:
See also:
SetObjectDroppable,
SetObjectSlidable,
SetListDroppable,
RegisterDragFlag,
UnRegisterDragFlag.
void SetObjectDroppable(int id,
int (*Drop)(void *dest, int id, void *src, int reason, int flags),
int flags, void *data);
Set the specified object as drop-able by installing the call-back
function `Drop'. "Drop-able" means that the user may drop an object
(previously gripped by use of the mouse) on it.
`Drop' will always be called by CGUI at least 3 times for each
drag-and-drop action that is completed by the user. The parameter reason
in the call-back informs which type of call that is concerned. The
`Drop'-function will only be invoked if the following conditions are
fulfilled:
- The destination is active (this is the default state which may be
changed by Activate/DeActivate).
- The destination has at least one drop-flag that matches the source
(i.e. AND-ing them results in non-zero).
- Some gripped object is either:
- over the destination or
- is not over the destination now, but was previously
The interpretation of the reason parameter at call-back:
- DD_OVER_DROP tells that some object has been gripped, and is being
dragged over `dest' object and that the flags of the source and
the destination object is matching
- DD_END_OVER_DROP tells that there is no longer an object over
The DD_OVER_DROP and DD_END_OVER_DROP calls may of course be
repeated any number of times depending on the actions by the user.
If one object has received DD_OVER_DROP and the cursor moves
directly to another object, the DD_END_OVER_DROP will come to the
first one before DD_OVER_DROP comes to the new one.
NB! A pair of DD_OVER_DROP and DROP_OVER_END doesn't indicate a
successful drop. These calls are only intended to give your
call-back function the opportunity to e.g. highlight the
destination object to indicate for the user that it is drop-able.
- DD_SUCCESS tells that the source object has been dropped on the
destination object. This call will be issued after the
DD_SUCCESS-call to the Grip-function of the gripped object.
Parameters to `SetObjectDroppable':
- id: the id-key of the object concerned
- Drop: a call-back function written by you.
Parameters of the call-back function "Drop":
- dest: the address of the actual object (the parameter object in
the call to SetObjectDroppable is transparently transmitted)
- id: the id of the drop-object
- src: the address of the actual source object that is gripped (the
parameter object in the call to SetObjectGrippable is
transparently transmitted).
- reason:any of the DD_* flags listed above
- flags: resulting value of the flags of the gripped object and the
object dropped on. If no special Drop-handling is required, Drop
may be set to NULL.
- flags: function of flags see SetObjectGrippable. The drop-flags will
be stored separately from the grip-flags, they don't need to be the
same for a certain object.
- data: Any data transparently passed to Drop in all calls.
See also:
Activate,
DeActivate,
SetObjectGrippable,
SetObjectSlidable,
SetListDroppable.
void SetObjectSlidable(int id,
int (*Slider)(int x, int y, void *data, int id, int reason),
int buttons, void *data);
This function is used by CGUI internally and is exported just for
completeness, for the moment I can't see and use for it in an application
program.
NOTE! An object can't be both "slidable" and "grippable".
`SetObjectSlidable' set the specified object as slidable, which means
that the user may grip the "hot" area of the object by use of
mouse-button (with the intention to slide the hot area (or maybe a part
of it like a handle) to another part of the object, within the visible
area).
Parameters to SetObjectSlidable:
- id: the id-key of the object concerned
- Slider: a call-back-function defined in your program that will be
called by CGUI, first when gripped, then for each movement.
Parameters to `Slider':
- x,y: the current coordinates (within object)
- data: a pointer to some data
- id: the id of the object
- reason: the reason why Slider was called, this may be either of:
- SL_OVER mouse cursor is over
- SL_OVER_END mouse cursor is not over but was previously
- SL_STARTED dragging did just start (mouse button is now down)
- SL_PROGRESS dragging is in progress
- SL_STOPPED mouse button released
- buttons: The mouse buttons for which "sliding" shall be allowed. The
slide event-type can not co-exist with the "grip" event-type.
If you e.g. assign "slide" to the left button it will be impossible
to grip the object with the left button, but click and double-click
will be OK.
- data: pointer to the data that later on (when the events occurs)
will be passed to "Slider"
See also:
SetObjectDroppable,
SetObjectGrippable.
void SetObjectDouble(int id, void (*DoubleCall)(void *),
void *data, int button);
Makes an object being double-clickable. "DoubleCall" will be called after
a successful double-click.
Assigning double-click e.g. to the left button allows the left button
to be used for single clicks to on the same object (the single click is
not issued until the "doubleclick" delay has expired). In addition the
same object may be either possible to slide or to grip with the same
button (the click and double-click events will not be launched until
"slidedelay" or "gripdelay" respectively time has expired)
Parameters:
- id: the id-key of the object concerned
- DoubleCall: The call-back function. It will be passed the "data"
pointer.
- data: the data to be passed to "DoubleCall"
- buttons: The double-click event can co-exist with all other event
types
Applies the text `text' to the object `id' to be used as a tool-tip text.
If `text' contains `_' characters these will be interpreted as new lines.
About tool tips: These are messages popping up to the user when moving
the cursor over an object. This can be needed for 2 purposes
- The object has only an icon, and maybe the user don't understand
what command it represents.
- The object has a text label, with or without an icon, but there are
needed som more information that will not fit into a label.
Return value: 1 on sucess else 0 (i.e. `id' is not valid).
Specifies how the object `id' will be viewed. If you switch any of the
two first flags you need to call `DisplayWin' ance again if that has
already been done.
Also the tool tip viewing can be controlled by 'SetView'.
Parameters:
- id: The id-key of the object concerned.
- flags: Any of the following option may be used in any combination:
- SV_HIDE_LABEL: If `id' has both an icon and a label then only the
icon will be shown.
- SV_HIDE_ICON: If `id' has both an icon and a label then only the
label will be shown.
- SV_NO_TOOLTIP: Deactivates the drawing of tool tips.
- SV_PREFERE_BRIEF: Ignored if `SV_NO_TOOLTIP' is set. If the
object has both a tool tip text and a label text then the label
text will be viewed as tool tip. Viewing tool tips will
be skipped either if none of texts are present or if there is
only a label text and it is already visible as label.
I.e. briefly: "show tool tips when possible without repeating
info, prefere brief info if there is a choice".
- SV_PREFERE_LONG: Ignored if `SV_NO_TOOLTIP' is set. If the
object has both a tool tip text and a label text then the tool
tip text will be viewed as tool tip.
I.e. briefly: "show tool tips when possible without repeating
info, prefere long info if there is a choice".
- SV_ONLY_BRIEF: Ignored if `SV_NO_TOOLTIP' is set. If the
object has a label text then the label text will be viewed as
tool tip if it is not already used as label.
I.e. briefly: "show tool tips when possible without repeating
info and there exists a brief text".
- SV_ONLY_LONG: Ignored if `SV_NO_TOOLTIP' is set. Only if the
object has a tool tip text there pop up a tool tip.
If an object has both a label and an icon and none of the flags
SV_HIDE_LABEL and SV_HIDE_ICON are specified (the default case) then
both of them will be drawn as a part of the object.
Only one of the flags SV_PREFERE_BRIEF, SV_PREFERE_LONG, SV_ONLY_BRIEF
and SV_ONLY_LONG can be specified. The default setting is SV_PREFERE_LONG.
If `id' is some container rather than a simple object this command will
affect also all the descendants of `id'.
Return value: 1 on sucess else 0 (i.e. `id' is not valid).
This function will call `Destroy' but it will also clean up the screen
from the object(s), i.e. the background of the containing node will be
drawn on the area of the former object. The containing node will however
not be rebuild, i.e. all the remaining objects will keep their
positions.
You don't need to call `Destroy' when you want to close a window,
`CloseWin' will take care of all objects in it.
In general the userinterface will be better if you avoid to remove
single objects. If your program goes into a state such that some
object(s) will be redundat or constitue illegal selecteion(s), then it
is better to deactivate them.
See also:
Destroy,
CloseWin,
DeActivate,
Activate.
This function frees all memory associated with the specified object `id'.
If the object contains other objects, like e.g. containers and
tab-windows do, all the sub-objects will be removed too (recursively).
The screen will remain unchanged.
See also:
Remove,
DisplayWin.
Returns the mouse button (left or right) that was latest pressed on the
specified win-object.
Return value: 1 on sucess else 0 (i.e. `id' is not valid).
Places the mouse pointer above the object.
Modifies the window-header text with the text of "newlabel". An
additional call to refresh is necessary to make the changes visible.
int AddHandler(int id, void (*Handler)(void *data), void *data);
Installs the application call-back function "Handler" and "data" into a
window object.
Objects like check-boxes, radio-buttons etc. normally doesn't need any
call-back, so when creating these you don't need to specify any call-back
function. In some cases it may however be convenient to get a call-back
for user events to these object types. E.g. if your program needs to
activate/deactivate other objects directly when the state of an check-box
is changed. In these case "AddHandler" may be used for installing such an
optional handler.
Not all type of objects support this facility. Return value 0 tells that
the installation failed. Currently the following object types supports
the optional Callback to be installed: edit-boxes, radio-buttons,
check-boxes, drop-down boxes, sliders and flip-objects.
In case of an edit-box, you are probably interested in getting some
information about the editing that is in progress (maybe you want to
distinguish between a letter-key-press and a carriage-return key-press).
Call for GetEditData to get available info. For edit-boxes your call-back
will be invoked before handling the event (the pressed key), in case of
other object types the event will be processed first.
Parameters:
- id: the id-key of the object concerned
- Handler: a pointer to a function written by you. It will be called
in case of user event, and the pointer data will be transparently
passed
- data: a pointer to any of your data
Return value: 1 on sucess else 0 (i.e. `id' is not valid).
See also:
GetEditData.
Mouse button alternatives: LEFT_MOUSE, RIGHT_MOUSE
Thid function changes the specified objects sensibility for clicks to
the specified mouse button(s). (default is the left mouse button)
Return value: 1 on sucess else 0 (i.e. `id' is not valid).
This is for the "drag-and-drop" facility. Some part of your application
may use some flag(s) for some object(s). If there is a risk that the same
flags may used for different purposes (e.g. the printer-monitoring
function uses bit 31), you should register the flags before using them.
Return value: 0 if none of the bits was already registered, else the
occupied bits.
Use the return value to determine if it is safe to activate the
drag-and-drop.
NOTE! Dropping of unexpected objects will _in best case!!_ crash your
program!
Parameter:
- flag: The integer containing the bit(s) (not the bit-number). The
bit(s) will be registered unconditionally.
This function unregister the flag(s).
Return value: 0 if none of the bits was already registered, else the
occupied bits.
Parameter:
- flag: The integer containing the bit(s) (not the bit-number). The
bit(s) will be unregistered unconditionally.
void RegisterRefresh(int id,
void (*AppUpd)(int id, void *data, void *calldata, int reason),
void *data);
Will register a callback-function, that will be called, whenever your
program calls `ConditionalRefresh'
This function really don't do very much, you would have made a list
of your own instead. The point is that you don't need to warry about
refering to dead objects since the registering will be buried with the
object (e.g. when CloseWin is called).
The callback is not limited to just do refresh, however this
seems to be the most useful purpose.
If you register several "refreshers" and not all of them needs to be
involved each time, you can let the function calling `ConditionalRefresh'
make a directed "message" by passing different `reason' parameters and
let the AppUpd functions examine it when called.
If several AppUpd functions will call `Refresh' for different or maybe
even the same object, that would have lead to a sequence of blits to
screen. However during the `ConditionalRefresh' call the blitting is
temporary tyrned off, and a final blit is issued at end of the call (a
minimal area will then be blitted)
Parameters:
- id: The identifier key to the object to hook
- AppUpd: the callback function.
Parameters to AppUpd:
- id: The id of hooked object
- data: the registered data
- calldata: the data passed by the caller (via ConditionalRefresh)
- reason: the reason parameter passed by the caller (via
ConditionalRefresh)
- data: the data that will be passed to AppUpd as second parameter.
See also:
Refresh,
ConditionalRefresh.
Will distribute a call to all objects in the system that has an AppUpd
hook.
ConditionalRefresh will boost blitting (all blits will be saved to one
screen-blit)
See also:
Refresh.
This function simulates a single mouse click (left) on the object `id'
int MakeStretchable(int id, void (*Notify)(void*), void *data,
int options);
This function creates a "handle" on the right and bottom edges of the
object, and a "handle" at the right bottom corner of it.
This makes it possible for the user to adjust the width and height of the
object. The handle in the corner makes it possible to stretch both width
and height at the same time.
The "handles" are invisible, but the mouse cursor will change its shape
when moving it over them.
All objects are allowed to be stretchable, but not all will notify the
stretching, e.g. a container that have an ADAPTIVE size, will after the
re-sizing operation immediately return to its previous size calculated as
the minimum to show all its contents (i.e. ADAPTIVE overrides
stretching).
Parameters:
- listid: the id of the list to be stretchable
- Notify: an optional call-back function that will be notified when
the the size of the object has been changed. The new size
(difference from the size initially calculated by CGUI) may be
achieved by a call to GetSizeOffset, and may later be stored by
your program to make it possible to start the program next time
with the size of the object that the user likes. Pass NULL if you
don't need the call-back.
- data: a pointer to some data that will be passed to `Notify' when
called by the object. Pass NULL if not used.
- options: may be used to inhibit bottom or right side handle (and
only want it to be stretchable in one direction). Macros:
NO_HORIZONTAL and NO_VERTICAL
Return value: 1 on sucess else 0.
See also:
GetSizeOffset,
SetSizeOffset,
continous_update_resize.
This function may be used to get the changes in size of an object. A
change of the size may only occur if it is stretchable (or if the size
has been adjusted with SetSizeOffset).
Return value: 1 on sucess else 0 (i.e. `id' is not valid).
See also:
SetSizeOffset,
MakeStretchable.
This function may be used to adjust the size of an object. A default size
of an object is always calculated at creation time (normally this is the
size enough to carry its label or icon). This size may be changed by this
function. Typically it is used in conjunction with GetSizeOffset to
restore the size of objects modified by user after a window has been
closed and re-opened.
Note: If justification commands like FILLSPACE are used in conjunction
with the relative positioning of an object (like DOWNLEFT etc) this may
override the offset setting.
The function must be called before the call to 'DisplayWin' to have
effect.
Return value: 1 on sucess else 0 (i.e. `id' is not valid).
See also:
DisplayWin,
GetSizeOffset,
MakeStretchable.
Moves the "logical insertion point" where new objects will be added
to after the `id' object. Any new objects that you add after calling
this function will be positioned as if they were added right after
`id' was added.
This can sometimes be meaningful when you make changes in a container
that already has object positioned with "direction commands".
The new "logical insertion point" is local to the container where `id'
lives.
Changes that are made in a window after it has been made visible (by
a call to `DisplayWin') will not be visible until `Refresh' is called
for appropriate part of the window. If "direction commands" are used,
the appropriate parts, which is normallay the entire window, of the
window also needs to be re-built (by a call to `ReBuildContainer') before
the refresh. Both will be done for the entire window if you call
`DisplyWin' again.
Returns 1 if id referes to an existing object, otherwise 0.
See also:
Objects,
SetOperatingWindow,
SelectContainer,
Direction commands for object positioning.
int MkVerticalBrowser(int x, int y,
void (*CallBack) (void *data), void *data, int *viewpos);
Creates a vertical "browsing object" consisting of one bar with a slider
handle for browsing and scrolling, and two scroll buttons.
The usage is quite staight forward, and the easiest way to unserstand is
to look into the browse example in the `examples' directory of CGUI.
For a detailed description the following naming convention is
introduced:
- "browsing object" - this object (the user can use it to browse and
scroll in another object, the "browsed object").
- "browsed object" - this can be any other object which displays
something that possibly is to large to be shown all at once.
- "view port" - is the area on the screen where the user can see
(possibly a part of) the "scrolled area". The "view port" may be
the same as the area of the "scrolled object", but also less (if
the "scrolled object" e.g. has some kind of frame).
- "scolled area" - the area to show in the "view port"
(if longer than the "view port" the user will be able to scroll or
browse it to be able to see other parts of it).
- "scrolling resolution" - for certain useges is quite enough for the
user if the "scrolling area" jumps ahead more than one pixel at a
time. A lower resolution (more pixels of jump) will speed up the
scrolling. The least scrolling resolution is 1.
The "browsing object" performs all calculations needed and call a
function of yours (see below) when the user interacts with the "browsing
object".
At some point your program may want "scrolled area" to move within
the "view port". It can then inform the "browsing object" about the new
state, see `NotifyBrowser'.
The size of the "scrolled area" may for some reason change during the
program execution. This will be the case e.g. if the thing to display is
an image and you provide the user with a tool to zoom the image or to
change to some (different sized) image. Also in such cases you need to use
`NotifyBrowser' to tell the "browsing object" about the new size.
During program execution the size of the "view port" may change (as
well as the prefered size of the "browsing object") in which case you
can use `SetBrowserSize' to inform the "browsing object" about it. (A
change of the "view port" size typically can occure if the "browsed
object" is possible to re-size by the user.
Parameters:
- x,y: The position of the "browsing object" (you can use "direction
commands" as well as numeric coordinates). Probably you want this
to be to the RIGHT of the "browsed object".
- CallBack: A function written by you. It will be called any time when
the user has used any of the scroll buttons or the slider handle.
The main purpose of this function is to update the area within
"view port".
Parameters:
- data: The data pointer you passed to `MkBrowser'.
- data: A pointer to any data that you want to be passed to `CallBack'.
- viewpos: A pointer to a variable of yours that specifies the start
position of the "scrolled area" in the "view port" (number of
pixels). The browser will both read and update the value of that
variable.
If the current "scrolled area" is smaller than the size of
the "view port" (set by `SetBrowserSize') then the "browsing object" will
deactivate itself.
The sliding handle will change its length as expected if the the
"scrolled area", "view port" or "browsing object" changes its size.
Return value: 1 on sucess else 0.
See also:
NotifyBrowser,
SetBrowserSize,
Direction commands for object positioning.
int MkHorizontalBrowser(int x, int y,
void (*CallBack) (void *data), void *data, int *viewpos);
Creates a horizontal "browsing object". See `MkVerticalBrowser' for
details.
See also:
MkVerticalBrowser.
Forces the "browsing object" `id' to update its status according to the
parameters. NOTE! You also need to call `NotifyBrowser' if you change the
value of the variable pointed to by `viewpos' (see `MkVerticalBrowser')
so the "browsing object" can make necessary re-calculations according to
the new position.
Parameters:
- id: The id of the "browsing object".
- step: The "scrolling resolution" in pixels.
- scrolled_area_length: The length of the "scrolled area" in pixels.
- viewpos: The start position of the "scrolled area" that currently
is to be viewed in the "view port" (in pixels).
Return value: 1 on sucess else 0.
This function makes no update of the screen.
See also:
MkVerticalBrowser,
SetBrowserSize.
int SetBrowserSize(int id, int view_port_length, int browsing_length);
Specifies the dimensions for a browsing object.
Parameters:
- id: The id of the "browsing object".
- view_port_length: The length of the "view port" ("length" means
either width or height depending on if it is a horisontal or
vertical browser).
- browsing_length: The desired length of the "browsing object" itself.
("length" means either width or height depending on if it is a
horisontal or vertical browser).
Returns 1 if sucess else 0.
This function makes no update of the screen. It can be useful if the
browsed object is re-sized (see `MakeStretchable').
See also:
MkVerticalBrowser,
NotifyBrowser,
MakeStretchable.
This is a global variable that controls the updating behaviour of an
object when stretched by the user.
If continous_update_resize is set to 0 (default), then the object that is
stretched by the user will not show its new size until the user releases
the mouse button that gripped the stretch-handle.
If continous_update_resize is set to 1, then the object that is
stretched by the user will continously show the current size.
See also:
MakeStretchable.
In CGUI you can specify the position of object using co-ordinates
explicitly, like
AddButton(13, 132, "Cancel", my_func, my_dataptr);
However, you will probably re-design your window a number of times during
development, and each time you will probably need to re-calculate the
position of the "Cancel".
In order to make the development process more convenient for you, CGUI
provides the "Direction command" facility. This means that you
just need to tell the direction of the object related to the recent ones.
The call will instead look like e.g.:
AddButton(DOWNLEFT, "Cancel", my_func, my_dataptr);
The position fo the "Cancel" button will be calculated in run-time and it
will adapt to the contents above as well as the run-time calculated size
of other objects. It's highly recommended that you use the "direction
commands" instead of explicit co-ordinates. It's also highly recommended
that you combine this with the 'ADAPTIVE' feature of windows and
containers to make your life easier.
The following 3 "direction commands" are the most "easy to use" ones,
when using them think of adding object like when typing text (from left
to right, from top to bottom):
- TOPLEFT will put the object in the top left corner of the container
(or window).
- RIGHT will put the object on the right side of the previously
created object, and the top edges of the two will be aligned.
- DOWNLEFT will put the object at the beginning of a "new row", i.e.
at the left edge of the container (or window) and below the bottom
edge of the prevous "object row".
The below ones are used by CGUI itself, and may occasionally be useful
for other purposes.
- DOWN puts the object below the previous one (aligned left edges).
- LEFT will put the object on the left side of the previous object,
withe aligned top edges. (i.e. it is meaningful to issue a 'LEFT'
object only after a RIGHT|ALIGNRIGHT or DOWN)
The following additional fill flags may be combined with a direction
command. The main point is create rows or columns with nice looking
object groups. Normally you should set the same flag to all objects in
such an "object row" or "object column".
- FILLSPACE: The objects in the "object row" or "object column" will
fill all available space in the container (or window), or to be more
precise:
All space found between a "sequence of n objects", before the
left one and after the right one will first be summed. The space
needed for the current distance will be subtracted from that.
The rest will be divided into n equal sized pieces. Each object will
the get its auto calculated size extended with that amount of pixels.
The "sequence of objects" is defined as some consecutive objects
with identical "additional commands" and the same top co-ordinates.
By default the space-filling will be horizontally. If you want
vertical filling the add the VERTICAL flag.
Optionally you may also specify both VERTICAL and HORIZINTAL to make
it fill up in both directions.
- EQUALHEIGHT: All objects in an "object row" will get the same
height as the one that requries the biggest height.
- EQUALWIDTH: All objects in an "object column" will get the same
width as the one that reqiures the biggest width.
- VERTICAL: This will only be notified as an specification to
FILLSPACE.
You are allowed to use the flags above to fill the space around any
sequence of objects, including other sub containers. However the result
will not always be as expected if their sizes are 'ADAPTIVE' since the
size of such containers are calculated after the positions of the entire
object tree has been calculated.
The "align"-flags will align the object to an edge of the container (or
window).
Both flags may be applied to the same object.
If you use ALIGNRIGHT for more than one object on the same "object row",
these will overlap (there is an analogous problem with
ALIGNBOTTOM).
- ALIGNRIGHT This flag will align the object to the right of a
container (or window).
- ALIGNBOTTOM This flag will align the object to the bottom of a
container (or window).
- ALIGNCENTRE This flag will centre in x-direction. Other object on the
same y-level will make objects messed up. May be combined with
ALIGNBOTTOM.
The "insertion point" of a new object will normally be after the
previously added one in the same container. You can modify the insertion
point using the function `InsertPoint'.
Functions that creates visible objects returns an id-number. This number
is unique.
For simple usage of the GUI you don't need this id. For advanced usage
there may sometimes be necessary to later on (when the window creation
has already been finished by a DisplayWin-call) refer to an object. In
these cases you have to save the id-number returned by the
object-creating function, and make use of it when you are about to call
the CGUI-function that reqiures the id-number.
Typical CGUI-functions that needs the id-number are Activate, DeActivate,
Refresh, Remove, Destroy.
Since the id-number is unique for the entire application you can as well
access objects in an "old" window (not the top one). Specially the
`Refresh' may be useful in this case.
Some of the CGUI-functions will apply to an entire group of objects if
you refer to a node object like a container, a list, a window etc.
If the specified id-number is not found the operation is ignored.
Note! Removing a single object will not give you any problem (i.e. CGUI
will not give you any), but it is not intuitive for the user -
deactivation is better than removing. Adding objects to an already
existing ADAPTIVE window may raise the problem for your program to
determine where it may be free space in the window to avoid overlapping
(remember that the direction command will refer to the "previous object"
object).
Some objects are of "container type". That is an object that contains
other objects. Examples of containers:
- Container
- Tab-window
- List-box
- Radio-group
- The menu-bar
The functions that create containers will also return an id-number.
Format specifications of edit-boxes
The information is used by the edit-box to make a correct type conversion
to and from void* pointers.
Back to contents