Objects

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:

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:

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: 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.
int MkRadioContainer(int x, int y, int *var, int direction);

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: Return value: an identification key to the container.
See also: EndRadioContainer, AddRadioButton, AddFlip, AddCheck, AddDropDown, Direction commands for object positioning.
int AddRadioButton(const char *name);

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: Return value: an identification key to the object.
See also: MkRadioContainer, EndRadioContainer, AddButton, AddHandler, MkMenuRadio, Labels.
void EndRadioContainer(void);

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: Return value: an identification key to the object.
See also: AddButton, GetObjectPosition, Labels, CguiLoadImage.
int GetObjectPosition(int id, int *x, int *y, int *wx, int *wy);

Gives the current position (top left corner) of an object.
Parameters: 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: 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: 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: Return value: an identification key to the object.
See also: InstallKBHandler, Direction commands for object positioning, SetBlitLimit, cgui_use_vsync.
void SetBlitLimit(int x1, int y1, int x2, int y2);

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.


extern int cgui_use_vsync;

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: 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: 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.
int TabOnCR(int id);

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.
void GetEditData(int *scan, int *ascii, int *offset);

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:
See also: AddEditBox, SetEditData, AddHandler.
void SetEditData(int scan, int ascii, int offset);

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:
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: Return value: an identification key to the object.
See also: AddTextBox, AddEditBox, AddTag, Refresh, StartContainer, Direction commands for object positioning.
int AddProgressBar(int x, int y, int w, int h);

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.
int UpdateProgressValue(int id, int percent);

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: 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: 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.
int UpdateTextBoxText(int id, const char *string);

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: Return value: an identification key to the object.
See also: AddEditBox, AddStatusField.
void Refresh(int id);

Redraws a specific win-object. If the object contains (recursively) other object these will also be refreshed.


void Activate(int id);

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.
void DeActivate(int id);

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 interpretation of the reason parameter at call-back: Parameters to `SetObjectDroppable':
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:
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:


int ToolTipText(int id, const char *text);

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

Return value: 1 on sucess else 0 (i.e. `id' is not valid).


int SetView(int id, int flags);

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: 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).


void Remove(int id);

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.
void Destroy(int id);

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.
int GetPressedButton(int id);

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).


void PointerOn(int id);

Places the mouse pointer above the object.


void ModifyHeader(int id, char *newlabel);

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: Return value: 1 on sucess else 0 (i.e. `id' is not valid).
See also: GetEditData.
int SetMouseButtons(int id, int buttons);

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).


int RegisterDragFlag(int flag);

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:


int UnRegisterDragFlag(int flag);

This function unregister the flag(s). Return value: 0 if none of the bits was already registered, else the occupied bits.
Parameter:


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:
See also: Refresh, ConditionalRefresh.
void ConditionalRefresh(void *calldata, int reason);

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.
void Click(int id);

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: Return value: 1 on sucess else 0.
See also: GetSizeOffset, SetSizeOffset, continous_update_resize.
int GetSizeOffset(int id, int *x, int *y);

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.
int SetSizeOffset(int id, int x, int y);

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.
int InsertPoint(int id);

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: 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: 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.
int NotifyBrowser(int id, int step, int scrolled_area_length);

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: 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: 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.
extern int continous_update_resize;

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.

Direction commands for object positioning

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): The below ones are used by CGUI itself, and may occasionally be useful for other purposes. 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". 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).

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'.



Id-numbers of objects

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:

The functions that create containers will also return an id-number.



Format specifications of edit-boxes

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