OKViCE Kernel Routines

These functions represents the kernel of the Visual Control Engine.


OKViCE Kernel Routines

Routine Use
OkvClearObjectList Removes all objects in a given object list, starting from last. Objects are removed with OkfRemove.
If the cleared object list is okvKernel.pWindows and all windows have been removed correctly, the kernel automatically exits the main loop and execution is returned to the application.
OkvExit Hides all windows from top most window to bottom window. Windows are hidden with OkfHide. If a window can't be hidden. The function exits.
When all windows are hidden, the kernel automatically exits the main loop and execution is returned to the application.
OkvGetControl Gets the control in a container object list from it's key.
OkvGetObjectWindow Gets the window that contains a given object.
OkvGetWindow Gets the window from it's key.
OkvHide Hides a window.

If it's not a window, error OKV_OBJECTTYPENOTALLOWED occurs.

1. If the object is not a visible window, the function exits.
2. If the window is the active window, it looks for the visible window just underneath. The window will then be deactivated with OkvDoActivateWindow. If the execution is cancelled by the user, the function exits.
3. OKV_ONHIDE event is raised. If event is cancelled by the user, the function exits.
4. If it's the last visible window, OKV_ONEXIT event is raised. If event is cancelled by the user, the function exits. The window will get the focus again in the kernel main loop.
5. The window is hidden.
6. The window underneath, if there is one, is activated and the focus is returned to the last control that had the focus on this window with OkvDoSetFocusControl.
7. If no more windows are visible, the kernel automatically exits the main loop and execution returns to the application.
OkvInitializeKernel Initializes the kernel. No operation can be done if the kernel is not initialized.
If the kernel is already initialized, error OKV_ALREADYINITIALIZED occurs.
At the end OKV_ONINITIALIZE event is raised.
OkvNewControl Creates a new control. OkvNewObject is used to create the base object and to add the control to it's container object list. Returned object is of type OKVCONTROL.

A control is a special object with some more attributes:
- It can be identified by a key assigned by the user application.
- It can have the focus.
- It can be a container for other objects. 
OkvNewObject Creates a new object and adds it to it's container object list. OkvNewObject is used to create the base object. Returned object is of type OKVOBJECT.

All items, in the engine, are objects that are contained in a container object list. okvKernel.pWindows is a special object list that can only contain objects of type OKVWINDOW.

1. If the container object list that not exist, the object list is created.
2. Memory is allocated to contain the new object.
3. The members of the object are initialized to their defaults.
4. The object is added to its container object list.
5. OKV_ONINITIALIZE event is raised.
OkvNewWindow Creates a new window. OkvNewControl is used to create the base control and to add the window the kernel window list. Returned object is of type OKVWINDOW.
At its creation a window is invisible. Use OkvShow to make it visible.

A window is a special control with some more attributes:
- It can only be contained in the okvKernel.pWindows object list.
- It can have a current control that has the focus if the window is the active window.
OkvRaiseEvent Raises an object event.
If okvKernel.enableEvents is FALSE, the event will be bypassed.
If the object points to a custom event handler, it will be used, else the default event handler pointed by okvKernel.eventHandler will be used.
okvKernel.lastProcessedEvent always contains the type of the last event processed by the application.
OkvRemove Removes an object from it's container object list.

1. If it's a visible window, it tries to hide it with OkfHide. If it can't, the function exits.
2. If it's the active control of the active window, it looses its focus. If it can't, the function exits.
3. If the object has children, it tries to clear the list with OkvClearObjectList. If it can't, the function exits.
4. OKV_ONTERMINATE event is raised.
5. The object is removed from it's container list.
6. If no more windows are visible, the kernel automatically exits the main loop and execution is returned to the application.
OkvSetFocus Gives the focus to a control. You can't use this function to give the focus to a window, instead use OkvShow.

 If it's not a control, error OKV_OBJECTTYPENOTALLOWED occurs.

When a control looses the focus, event OKV_ONLOSTFOCUS is raised. This event can be cancelled by the user. In this case the control will retain the focus.
When a control gets the focus, event OKV_ONGOTFOCUS is raised. This event cannot be cancelled.

If the control has already the focus, nothing is done.
If the control is not on a visible window, no events are raised. In fact the control is prepared in the background to get the focus as soon as the window is activated. The events will be raised at this moment.
If the control is not on the active window, the control's window is activated (if its visible), and then the control gets the focus.
If a control has the OKV_NOTABSTOP flag set, it can be focused only if the bypassNoTabStop parameter of the function is set to TRUE.
If a control has child controls that can have the focus, the first focusable child control will be focused. If neither the control or its children can be focused, nothing is done (see OkvDoSetFocusControl).
OkvSetVisibility Sets the visibility of an object.

Windows can't be showed or hidden with this function. Instead use OkvShow or OkvHide. Else an OKV_OBJECTTYPENOTALLOWED error will occur.
OkvShow Shows and/or activates a window.

 If it's not a window, error OKV_OBJECTTYPENOTALLOWED occurs.
If the window is the active window, nothing is done.
 If the window is already visible but not active, it is activated.
1. OKV_ONSHOW event is raised if the window was invisible. If event is cancelled by the user, the function exits.
2. The window is made visible.
3. The window is activated and the focus is given to the last control that had the focus on this window with OkvDoSetFocusControl. If no control had the focus previously, the first focusable control gets the focus. If one of the events is cancelled by the user, the function exits.
OkvStart Starts the main loop of the kernel.

The first window to be shown can be passed to the function.
If NULL is passed, the first window in the okvKernel.pWindows object list is shown.
If no window is found in the list, the function exits with error OKV_WINDOWLISTISEMPTY.
If the opening of the initial window is aborted, the function exits with error OKV_NOVISIBLEWINDOW. 

The kernel's main loop ends automatically when no more windows are visible, even if there are windows in the okvKernel.pWindows object list.
The first visible window in the windows list is the bottom window on the screen. The last visible window in the windows list is the top most window on the screen. In fact, when a window is activated, the object of the window is moved to the last position in the list.

Main loop:
1. If there is not at least one visible window, exit loop.
2. If there is no active window, activate front window (the last visible window in the windows list). If the front window could not be activated, exit function with error OKV_NOACTIVEWINDOW.
3. Kernel event OKV_ONFRAMEBEGIN is raised.
4. OkvPaint is used to paint all visible windows starting from the first in the windows list.
5. Kernel event OKV_ONFRAMEEND is raised.
6. Kernel event OKV_ONGETKEYS is raised.
7. If active control asked for key preview, event OKV_ONKEYPRESS is raised for the control.
8. If active window asked for key preview, event OKV_ONKEYPRESS is raised for the window.
9. Depending on the final virtual key obtained from 6-8:
   - OKV_VK_CLICK: OKV_ONCLICK event is raised for the active control.
   - OKV_VK_NEXTCONTROL: focus is given to next control using OkvGotoNextControl.
   - ...: To be defined...
10. Loop to 1.
OkvTerminateKernel Terminates the kernel and frees all the allocated memory.

The kernel can only be terminated if there is no visible window. If at least one window is visible, error OKV_WINDOWISVISIBLE occurs.

At the end, OKV_ONTERMINATE event is raised.


OKViCE Kernel Private Routines

Routine Use
OkvDoActivateWindow Deactivates the current active window, and activates a new window.
If it's already the active window, nothing is done.
Does work only if window is already visible.

The sequence of the events can be as follows:

1. OKV_ONLOSTFOCUS is raised for the current active control. The event can be cancelled by the user. 
2. OKV_ONDEACTIVATE is raised for the current active window. The event can be cancelled by the user. 
3. OKV_ONACTIVATE is raised for the new focused window.
OkvDoSetFocusControl Deactivates the current active control and gives the focus to a new control.
Uses OkvGetRightControlToFocus to search for the right control to focus. If none is found, nothing is done.

If the control is the active control or the active window, nothing is done
If a focusable control is found, it is returned to the caller, else NULL is returned.
If the focusable control is not on the active window, the control's window will be activated with OkvDoActivateWindow.

The sequence of the events can be as follows:

1. OKV_ONLOSTFOCUS can be raised for the current active control. The event can be cancelled by the user. 
2. OKV_ONDEACTIVATE can be raised for the current active window. The event can be cancelled by the user. 
3. OKV_ONACTIVATE is raised for the new activated window.
 4. OKV_ONGOTFOCUS is raised for the new focused control.
OkvGetRightControlToFocus Given an object (any type), returns the real control that will receive the focus.
A control that has the OKV_NOTABSTOP flag set, can't get the focus unless the bypassNoTabStop parameter of the function is set to TRUE.

If the object is not visible it returns NULL.
If it's a control that has a child that can be focused, it returns the child control.
If no focusable control can be found from the given object, it returns NULL, else it returns the given object.
OkvGotoNextControl Gives the focus to the next focusable control of the active window.
The order of the controls is determined by their order of creation.
The function always takes into account the OKV_NOTABSTOP flag of the controls.
If the current control is the last focusable control on the active window, the focus is given to the first focusable control of the window.
If there is no active control, the focus is given to the first focusable control of the active window.
OkvDoSetFocusWindow is used to give the focus.
If the reverse parameter of the function is set to TRUE, the movement is made from the last to the first control of the window.
OkvPaint Raises an OKV_ONPAINT event for an object and all its visible children, if there is any.
The coordinates of an object are always relative to its container. The origin of the coordinates to use to paint the object are included in the event.


See Also

List Routines