Field Handler OLD

StudioWorks has a field handler object, oFieldHandler, which is responsible for field decoration, enabling and disabling fields, and type-ahead lookups.

The type-ahead lookups field handling is delegated to oFieldHandlerLookupTypeAhead and are discussed under the topic, Lookups.

The default field handling for entry fields in StudioWorks is as follows:

1. evBefore the field is given a white forecolor and a blue border to indicated that focus is on that field.
2. evAfter the field is reverted to its previous state.

Non-standard field handling is accomplished by setting the Display Properties - Decorator Type in the SQL Meta-Data Editor. The decorator types supported are:

1. displayonlyalways - grey background, use can click on the field to select and copy text to clipboard, but can not enter or paste text into the field.
2. displayonlyedit - uses displayonlyalways properties in edit mode. Default properties in new mode.
3. clickalways - cream forecolor and disabled always. User can click on the field to enable the field.
4. clickedit - uses clickalways properties in edit mode. Default properties in new mode.
5. autoexpand - field expands to multi-line entry on evBefore and returns to normal size on evAfter.
6. notes - blue forecolor and disabled. Pops opens a multi-line entry field in a small window for editing if the user clicks on the field.
7. multiline - Default properties, but uses a kMultilineEntry field instead of a kEntry field for autoconfig and developerize windows.

How the Field Handler Works

The oFieldHandler object is instantiated by the ivar ifld in the window instance which makes use of the field handler. There is one instance of oFieldHandler in each window (subwindow) instance.

When the window is instantiated at the end of the $construct method a $runtimeWinInst message is sent to oConcretizer.

Do conc.$runtimizeWinInst($cinst,iSQLClassName,iWinInstID)

One of the things the concretizer does is generate a list of the fields in the window and the properties for each field based on the SQL meta-data of the SQL class defined from that window. It is a fairly complex operation with the end result of a field properties list that is defined using sFieldProperties_listdef. The field properties list is cached in the $userinfo property of the window instance (or window class for when the window is runtimized)

The field properties list is what drives the field handling behavior.

When the window receives $_setMode message, the $_setMode method sends an $initializeFields message to oFieldHandler.

Do ifld.$initializeFields($cinst,pMode,pSQLClassName,pExtraFieldsList_opt)

The $initializeFields method gets the fields list from $userinfo, if it hasn't already been fetched for the instance, and then proceeds to set the properties of each field in the window for the specified mode.

Each $_setMode message initializes the fields for the specified mode.

When the user enters a field, Omnis Studio sends a $event message to the field. The $event message passes to the $control method of the window class where you will see code which forwards the message to the field handler.

Overrriding Field Handler Properties

You can override the field handler properties, or add fields to the field handler. This can be accomplished through the pExtraFieldsList_opt parameter.

The $_setMode methods sends an $initializeFields message to the field handler each time the mode is set.

Do ifld.$initializeFields($cinst,pMode,pSQLClassName,pExtraFieldsList_opt)

You can get an empty fields properties list from the field handler using the $:EmptyFieldPropertiesList method.

The following $_setMode method sample code adds an extra field to the field handler. The field is one from the sSecurityInfoRow_listdef schema class which has added to the wUsrEdit window class.

; Set the mode var.
Calculate $cinst.iMode as pMode

; Add extra fields from the security row.
If iExtraFieldsList.$colcount=0
   
   ; Define the field handler extra fields list.
   Do ifld.$:EmptyFieldPropertiesList Returns iExtraFieldsList
   
   ; Add the 'securitytimeoutminutes' field as a 'clickalways' field.
   Do iExtraFieldsList.$add()
   Do iExtraFieldsList.$line.$assign($ref.$linecount)
   Do $cinst.$objs.$findname('securitytimeoutminutes') Returns rObj
   Calculate iExtraFieldsList.objident as rObj.$ident
   Calculate iExtraFieldsList.objtype as rObj.$objtype
   Calculate Suffix as mid(rObj().$fullname,len($cinst().$fullname)+2)
   Calculate iExtraFieldsList.refsuffix as Suffix
   Calculate iExtraFieldsList.visible as kTrue
   Calculate iExtraFieldsList.focusfieldstyle as 'swFieldFocus'
   Calculate iExtraFieldsList.nofocusfieldstyle as 'swFieldNoFocus_click'
   Calculate iExtraFieldsList.active as kTrue
   Calculate iExtraFieldsList.click as kTrue
   Calculate iExtraFieldsList.focusfieldstyle_new as 'swFieldFocus'
   Calculate iExtraFieldsList.nofocusfieldstyle_new as 'swFieldNoFocus_click'
   Calculate iExtraFieldsList.active_new as kTrue
   Calculate iExtraFieldsList.click_new as kTrue
   Calculate iExtraFieldsList.focusfieldstyle_view as 'swFieldFocus'
   Calculate iExtraFieldsList.nofocusfieldstyle_view as 'swFieldNoFocus_click'
   Calculate iExtraFieldsList.active_view as kTrue
   Calculate iExtraFieldsList.click_view as kTrue
   
End If

; Send an $initialFields message to the field handler, to update all the field objects to the new mode.
Do ifld.$initializeFields($cinst,pMode,iExtraFieldsList) Returns FlagOK
If FlagOK
   
   ; Update the button menu bar
   Do $cinst.$updateActiveCmnds() Returns FlagOK
End If
Quit method FlagOK

The first time the $_setMode method is run it builds the iExtraFieldsList. Each subsequent time it skips directly to sending the $initializeFields message to the field handler.

You can view all of the swField... styles in the #STYLES class of swGui4.

You can view all of the extra fields list columns in the F9 Catalog > Schemas > swGui4 > sFieldHandlerProperties_listdef. Hovering of a columm gives you a tooltip with more information.

StudioWorks Documentation - Copyright 2005 Vencor Software