swGui5

This section contains concepts, ideas, and discussion, on a new GUI structure that could be added to the StudioWorks framework in the future.

Window Controller Objects

The first version of StudioWorks used Window Controller Objects. Each window instance was mapped to a window controller object class. When a window class was instantiated it would find and instantiate its own window controller object class.

Much of the code that would normally be in the window class was moved to the window controller object. The expresssion used was "keep the window class dumb, put the intelligence in the wco".

StudioWorks moved away from Window Controller Objects for a couple of reasons:

1. Instability It was very difficult (impossible?) to keep a stable object class instance in the earlier versions of Omnis Studio. Without warning you could end up with 2 instances and your carefully crafted code would go south.
2. Complexity. It was a signicant step for many developers to move from Omnis Class procedural code to Omnis Studio object-oriented programming. Adding window controller objects to the mix made it even more difficult.
3. Order of Instantiation. The window class had to be instantiated first and then it had to instantiate its Window Controller Object. A cleaner approach would have been to instantiate the Window Controller Object and let it then instantiate the window class, but due to instabiilty of object class instances it had to be done in the reverse order.

In hindsight another problem with Window Controller Objects was that responsibilities between the window class and the window controller object class were never clearly defined. You were never sure whether code would be in the window class or the window controller object.

We are now considering reintroducing Window Controller Objects in the StudioWorks framework. To maintain backwards compatabilty the swGui4 module would remain as it is, and the Window Controller Object structure would be introduced in a new module, swGui5.

The reasons for reintroducing Window Controller Objects to the StudioWorks framework are as follows:

1. Object Reference Datatype - Omnis Studio has introduced a new data type, Object Reference, which solves the instability problems we had with the Object data type.
   
   The new Object Reference datatype can instantiate an object class on its own. No need to live inside another instance. Therefore a window controller object can be instantiated and it can then instantiate and construct its window instance. The only trick with the Object Reference datatypes is that the developer must delete the instance when they are finished with them or they will continue to live in memory until you quit Omnis Studio. (However they could be situations where this could be used to our advantage.)
2. Separation of Visual and Non-Visual Code - Moving all but the basic event handling and field decoration code to Window Controller Object methods would simplify and greatly reduce the window class code. With clearly defined Window Controller Object vs. window class responsibilities we could reuse window controller object code for remote forms and ultrathin client web apps.
3. Better Class Structure - The current superclass/subclass window class structure in swGui4 is getting a bit unweildy. By the time you get 4 levels down in the superclass/subclass struture there are a lot of superclass methods, not all of which are useful to your particular window instance. The fact that they are not listed in alphabetic order doesn't help the situation. It can be quite a job debugging methods which call up 4 levels of Do inherited. The goal with introducing Window Controller Objects would be to flatten the class structure. The window controller object can contain just the methods required for a particular window instance and can call other helper object methods as needed.

WCO Responsibilities

The following is a list of ideas on the responsibilities of the window controller object classes.

1. Non-Visual Object
1. The Window Controller Object never prompts the user on its own. The Window Controller Object can have $prompt... methods, but these can only be called by window class methods.
2. The Window Controller Object never calls the error handler $promptonceLastError method. The window controller object just has to return the flag or return value.
2. Modeless Prompts - if asked to prompt the user via a $prompt... method, always use the modeless prompts so that the same code could be used for a web app. The $prompt..._continue method would be a window controller object method, not a window class method.

3. Event Handling - $event and $control methods would not be found in the Window Controller Object.

4. Event Parameters - None of the window controller object methods could directly use Omnis Studio event parameters. All parameters must be passed from the window class to the Window Controller Object.

5. Redraw - The window class methods are responsible for $redraw. Never include $redraw in the Window Controller Object code.
   

Window Class Responsibilities

; Do pContextMenu.$addMenuLine(pMnID,pbElipsis,pMenuText)

; Can we modify the schema class?
Do $cinst.$canModifyClass() Returns bCanSave
If not(bCanSave)
Calculate Text as con("Read-only: ",$cinst.iClassName," needs to be checked out of the VCS.")
Do pContextMenu.$addMenuLine($cinst,'doNothing',kFalse,Text)
Else

Do irTree.$currentnode() Returns rCurrNode
Do irTree.$getselectednodes(List)

; $addMenuLine(pfObserver,pMenuID,pbEllipsis,pMenuText_opt)

; Only allow new if one line selected.
If List.$linecount=1
Do pContextMenu.$addMenuLine($cinst,'newNode',kTrue,'New')
End If

; Only allow duplicate if one line selected and not a root node.
If List.$linecount=1&rCurrNode.$level<>1
Do pContextMenu.$addMenuLine($cinst,'duplicateNode',kTrue,'Duplicate')
End If

; Only delete selected if one line selected and not a root node.
If List.$linecount>0&rCurrNode.$level<>1
Do pContextMenu.$addMenuLine($cinst,'deleteSelectedNodes',kTrue,'Delete Selected')
End If

; Only allow duplicate if one line selected and not a root node.
If List.$linecount=1&rCurrNode.$level<>1
Do pContextMenu.$addMenuLine($cinst,'editNode',kTrue,'Edit')
End If

End If
End If
Quit method FlagOKThe following is a list of ideas on the responsibilities of a window class that uses a window controller object.

1. Event Handling - All event handling is the responsibility of the window class.
2. Field Decoration - Decorating fields is the responsibilty of the window class.
3. Field Properties - setting the field properties is the responsiblity of the window class.
4. Window Size - save and restore window size for each user is the responsiblity of the window class.
5. Field Sizes - save and restore list column widths, treelist widths, etc. is the responsiblity of the window class.
6. Prompt User - the decision to prompt the user for input is the responsiblity of the window class. The window class can delegate this by calling a $prompt... method in the Window Controller Object, but the decision to prompt is alway made by the window class. The sequence of code that follows the prompt which we delegate to the Window Controller Object would be the responsibility of the Window Controller Object. Problem - What if the window needs to be redrawn to show the new information? Can the Window Controller Object tell the window to redraw? This may have to be an exception to the no $redraw rule.
7. Error Prompt - If an error is logged by the Window Controller Object, the window class is reponsible to send a $promptonceLastError to the error handler.
8. Redraws - the window class is responsible for redrawing itself or specific objects.

Data Lists

Should datalists be in the window class or the Window Controller Object?

It is tempting to consider storing all the datalists in the Window Controller Object and having window objects (headed list, complex grid, etc.) reference the datalists in the Window Controller Object.

Once advantage of doing this is that it might make it simpler to have 2 different window instances (stand alone or as subwindows) with different presentations of the same data pointing to the same Window Controller Object datalist. One window might be a list, the other a graph, one might display the visible fields of the current row, the other other all of the rows but just one or two columns of the datalist.

The Window Controller Object can decide if 2 different windows under its control point to the same datalist or separate datalists.

Another possible adavantage of storing the datalist in the Window Controller Object is that you can keep a Window Controller Object instance alive even if the window instance is closed. If the window instance is reopened the same Window Controller Object instance could be used with the datalist still populated.

Referencing datalists was not always stable in the earlier versions of Omnis Studio. This has not been a problem in the later versions of Omnis Studio.

Sequence of Instantiation

What is the sequence of instantiation?

1. Is the Window Controller Object instantiated first, and then does it instantiate the window class?
2. Or is the window class instantiated first and does it then instantiate its Window Controller Object?

I am leaning towards option #1 because it may provide more flexibility. Numerous window classes in StudioWorks are completely generic and reused for many different window instances.

If we have a window controller object class for each wininstid, we would just have to instantiate the window controller object and let it instantiate the window class.

However, this will be a problem for subwindows. The $classname of the subwindow field must be assigned first and when it is assigned the window class is immediately instantiated. The work around could be to send an $openWCO message to the oWindows object.

Do wn.$openWCO(pWinInsID) Return WCOInstName

Then set the subwindow field $parameters property to include the WinInstID and the WCOInstName. The $construct method of the window instance receives the WCOInstName as an optional second parameter and if received, it sends a $retWCORef message to oWindows.

Do wn.$retWCORef(pWCOName) Returns ioWCO

The return value is a pointer to the Window Controller Object object reference instance which is stored in a list of Window Controller Object object reference instances.

If the second parameter is empty, the window's $construct methods sends the WinInstID as the parameter to oWindows.

Do wn.$retWCORef(pWinInstID) Returns ioWCO

StudioWorks Documentation - Copyright 2005 Vencor Software