1. Forms support an IMAGE sub-object which is used to specify their background image.
2. Forms support a MENU sub-object as an interface to the form’s menu bar (if present).

The WINDOW object supports the following properties in addition to the Common GUI Object and Container Object properties, except where noted below:

The following Common GUI Object properties are not supported:

• ALLPAGES
• AUTOSCALE
• AUTOSIZEHEIGHT
• AUTOSIZEWIDTH
• BOTTOMANCHOR
• COLUMN
• CONV
• DEFPROP
• DEFPROPPOS
• DEFPOSPROPID
• DEFPROPRAW
• DEFVALUE
• DESIGNSELECTED
• ECHO
• EDGESTYLE
• FORECOLOR
• GOTFOCUSVALUE
• IMAGELIST
• INVALUE
• NEXT
• ORIGARRAY
• ORIGLABEL
• ORIGLIST
• ORIGVALUE
• PAGENUMBER
• PART
• POS
• PREVIOUS
• REQUIRED
• RIGHTANCHOR
• VALID
• VALIDMSG

Gets or sets the name of a different form (with a menu) to redirect menu accelerator keystrokes to when they are detected on the current form.

This is string value containing the name of a running form instance. When an accelerator keystroke is detected for the current form it is sent to the other nominated form instance for processing.

This property is useful for owned/child forms (e.g. dialog boxes) which traditionally do not have their own menu. Rather than creating and duplicating a hidden menu themselves (for common functions like Help and Options) they can simply redirect the accelerator keystrokes to their parent for processing instead.

     
 // Example - in the CREATE event of a dialog box redirect the accelerator //
 // keystrokes to the parent form.//
 
 ParentForm = Get_Property( CtrlEntID, "PARENT" )
 Call Set_Property_Only( CtrlEntID, "ACCELERATORFORM", ParentForm )
 

MENU object.

Specifies if the form is active – i.e. if it is the top-level form that the user is currently working with.

This is a boolean value. It returns TRUE$ if the form is the active form, or FALSE$ otherwise.

This property is updated during the WM_ACTIVATE window message processing. Please see the Microsoft website for more information on this message and on the topic of Keyboard Focus and Activation.

     
 // Example – Determine if the current form is the active form.//
 
 IsActive = Get_Property( @Window, "ACTIVE" ) 
 

SYSTEM FOCUS property, WINDOW ACTIVATED event, WINDOW INACTIVATED event.

Specifies if a data-bound form ignores locks placed on the same row if it is loaded into other forms in the same PS instance at the same time.

This is a boolean value. It returns TRUE$ if the form ignores "self-locks", or FALSE$ otherwise.

When a row is read into a form the system checks to see if it can place an exclusive lock on it first. If it cannot, the default behavior is to display a message to the user, warning them that they can view a read-only version of a row or abort the read attempt.

If the ALLOWSELFLOCKS property is TRUE$ and the exclusive lock attempt fails, then no warning will be shown if the lock is held by another form in the current PS instance – in this case the row will be loaded and editing allowed as normal.

This facility is intended to allow forms to edit different parts of the same row at the same time without a locking conflict. For this activity to be safe forms that use this property must ensure that their controls do not bind to the same columns on different forms, otherwise this may result in unexpected data integrity issues due to the possibility of overwriting updates from other forms containing the same row.

     
 // Example – Determine if the current form is allowing self-locks//
 
 AllowSelfLocks = Get_Property( @Window, "ALLOWSELFLOCKS" )   
 

WINDOW IOOPTIONS property, WINDOW READROW method, WINDOW READ event.

Specifies if a form triggers the FORMSTATECHANGED and MDICHILDSTATECHANGED events.

This is a boolean value. It returns TRUE$ if the form triggers the events, or FALSE$ otherwise.

This property is FALSE$ for existing forms and must be enabled "manually" to preserve backwards compatibility. It is set to TRUE$ by default for new forms.

     
 // Example – Determine if the current form is allowing "FormState" events//
 
 AllowFormStateEvents = Get_Property( @Window, "ALLOWFORMSTATEEVENTS" )   
 

WINDOW IOOPTIONS property, WINDOW FORMSTATECHANGED event WINDOW MDICHILDSTATECHANGED event.

Specifies if the user can reset the sequential key counter for a data-bound form by entering a "=" character in the control bound to the key column.

This is a boolean value. It returns TRUE$ if the user is allowed to reset the sequential key counter, or FALSE$ otherwise.

This property only applies to forms bound to a single table with a numeric single part key. When a user enters a "=" character in the control bound to the key column they are presented with the option of setting the sequential key counter for the table to a new value.

By default the sequential key it stored in the “%SK%” record in the dictionary table, but a different record may be chosen via the DEFVALUE property.

If the sequential key has not been initialized before it defaults to a value of “1”.

     
 // Example – Determine if the current form is allowing a sequential key reset//
 
 AllowSeqKeyReset = Get_Property( @Window, "ALLOWFSEQKEYRESET" )   
 

Common GUI DEFVALUE property, WINDOW IOOPTIONS property.

Specifies if an MDI Frame form automatically arranges its minimized MDI child forms. It does not affect MDI child forms that are not minimized.

This is a boolean value. Set to TRUE$ to if an MDI Frame automatically arranges its minimized MDI child forms, or FALSE$ otherwise.

In Windows 3.1 minimized MDI Child forms were represented as icons in the MDI client area. From Windows 95 onwards they appear as small caption bars instead, but the term "icons" is till used to refer to them in this context.

Minimized MDI child forms are auto-arranged under the following circumstances:

• When the MDI Frame is resized.
• When an MDI child is activated or resized.
• When this property is first set to TRUE$.

This property uses the WM_MDIICONARRANGE window message internally. Please see the Microsoft website for more information on this message and on the topic of Windows MDI programming.

     
 // Example – Set the current form to auto arrange its MDI child icons.//
 
 PrevVal = Set_Property( @Window, "ARRANGEICONS", TRUE$ )
 

WINDOW MDIICONARRANGE method, WINDOW ARRANGEICONS event, Appendix E – MDI Programming.

Gets or sets data associated with the primary table of a data-bound form and updates data-bound controls.

When getting the property, the data is extracted directly from the controls on the form and merged with a cached version of the data row that was read from disk during the READ event (i.e. the RECORD property).

When setting the ATRECORD property, the passed data row is set as per the form's RECORD property and then the data-bound controls are automatically populated from this. The SAVEWARN property is also set to TRUE$.

This property is a dynamic array that represents a database row for the primary table bound to the form. Its structure is determined by dictionary of the table.

By default the WRITE event of a form only updates the columns in the database table that are bound directly to controls on the form – any data columns that are not bound to a control are ignored by the write processor. This means that you cannot update these non-control columns using ATRECORD unless the form's WRITEMODE property is set to "WriteEntireRow" - in this case the entire data row held in the RECORD property is updated with the contents of the bound controls and is then written to disk.

The intent behind the default of only updating bound controls is to prevent data corruption in cases where different forms load different columns from the same row at runtime. If each form updated the non-bound columns during the write process it would be possible to overwrite new data with stale data. The WRITEMODE property allows this safety feature to be circumvented, but it expects to be used with forms that do not use different columns with the same data row.

(Note: This property was designed to emulate the functionality of setting the @Record variable for a data-bound form in an Advanced Revelation application which would automatically populate the data-bound prompts on screen.)

This property is considered deprecated in favor of the ROW property. New applications should use ROW to work with the cached version of the data row for more consistent and expected results when using a "single form – single row" model.

     
 // Example - a table has five columns://
 ////
 //   CUST_ID        (key)//
 //   TITLE          <1>//
 //   FORENAME       <2>//
 //   SURNAME        <3>//
 //   DATE_OF_BIRTH  <4>//
 ////
 // It is bound to a form that has the following three controls://
 ////
 //   EDL_CUST_ID    -> CUST_ID (key)//
 //   EDL_FORENAME   -> FORENAME//
 //   EDL_SURNAME    -> SURNAME//
 ////
 // The form is loaded with record "C1234" which has the following data://
 // //
 // <1> MR//
 // <2> REN//
 // <3> HOEK//
 // <4> 65478//
 ////
 // Enter "STIMPSON J" in EDL_FORENAME//
 
 AtRecord = Get_Property( @Window, "ATRECORD" )
 
 // AtRecord contains://
 // <1> MR//
 // <2> STIMPSON J//
 // <3> HOEK//
 // <4> 65478//
 
 AtRecord<1> = "SIR"
 AtRecord<3> = "CAT"
 
 Call Set_Property_Only( @Window, "ATRECORD", AtRecord )
 Call Exec_Method( @Window, "WRITEROW" )
 
 // If we were to look at the record stored in the table we would now see this://
 ////
 // <1> MR                  <-- Not "SIR"!//
 // <2> STIMPSON J//
 // <3> CAT//
 // <4> 65478//
 ////
 // Because the TITLE column (field <1>) is not bound to a control on the form//
 // the value set by ATRECORD in field <1> ("SIR") does NOT get written unless//
 // the WRITEATRECORD property is set to TRUE$.//
 

WINDOW RECORD property, WINDOW ROW property, WINDOW SAVEWARN property, WINDOW WRITEATRECORD property, WINDOW WRITEENTIREROW property, WINDOW READROW method, WINDOW WRITEROW method, WINDOW READ event, WINDOW WRITE event.

Specifies if the form uses system double-buffering during sizing operations to achieve smoother rendering.

This is a boolean value. When set to TRUE$ the WS_EX_COMPOSITED extended window style is applied to the form during a resize operation and then removed afterwards,

Results of using this property may vary depending on whether Windows is using the Desktop Window Manger (DWM) for rendering. If the DWM is active (i.e. on Windows Vista/7 running full Aero, or Windows 8 onwards) then using this property may actually degrade the rendering operation.

     
 // Example – set AUTOCOMPOSITED for the current form.//
 
 Call Set_Property_Only( @Window, "AUTOCOMPOSITED", TRUE$ ) 
 

Common GUI COMPOSITED property.

Returns a list of attached labelled commons. These commons are freed by the form when it is destroyed.

This is an @fm-delimited array of labelled common names.

N/a.

     
 // Example – get the list of attached labelled common areas//
 
 CommonList = Get_Property( @Window, "COMMONLIST" )
    

WINDOW ATTACHCOMMON method, WINDOW DETACHCOMMON method, End_Window Stored Procedure.

Returns the name of a stored procedure that contains event handling code for the form.

This is a string value containing the name of a valid stored procedure (Note this is not a fully qualified STPROCEXE repository ID).

The contents of this property are used by the QuickEvent processor to call a stored procedure to pass the event parameters onto at runtime. The QuickEvent processor replaces the token "@COMMUTER" in the event handler definition with the stored procedure name and then invokes it:

     
 // Example – get the name of the current form's commuter module//
 
 CommuterModule = Get_Property( @Window, "COMMUTERMODULE" )
    

Appendix XXX – Event processing.

Returns a list of controls hosted by the specified form.

This an @Fm-delimited array of fully-qualified control names.

The list returned by this control is the list that is compiled into the form template by the Form Designer, and subsequently used to create the form at runtime.

If controls are later added to the form at runtime by using the SYSTEM CREATE method this list will not be updated. It can be updated "manually" by a developer by manipulating the form's "Window Common Area" if desired.

If a control is destroyed using the SYSTEM DESTROY method there is an optional flag that will remove the control from this list.

The list is held in the form's Window Common Area in the ControlMap@ variable which can be accessed by using the OIWIN_COMM_INIT insert record.

     
 // Example – get the list of controls for the current form//  
  
 CtrlMap = Get_Property( CtrlEntID, "CTRLMAP" )
 

SYSTEM CREATE method, SYSTEM DESTROY method, SYSTEM OBJECTLIST method, OIWIN_COMM_INIT insert record.

Specifies if the form is flagged for destruction during QUERYEND processing.

This is a boolean value. When TRUE$ this means that the form has been marked for destruction during a QUERYEND process.

When the SYSTEM QUERYEND property returns TRUE$, forms that are destroyed will have DESTROYFLAG set, but the forms themselves will not be destroyed.

Often, the HANDLE property is used to test if a form still exists, but if a form is closed (by using End_Window for example) when QUERYEND is true, the HANDLE will still exist but DESTROYFLAG will be set.

In earlier versions of OpenInsight this property was called DESTROY_FLAG. This name is deprecated but can still be used.

     
 // Test to see if the current form is flagged for destruction//
 
 IsFlagged = Get_Property( @Window, "DESTROYFLAG" )   
 

Common GUI HANDLE property, SYSTEM QUERYEND property.

Returns the current DPI (dots-per-inch) settings for the specified form.

This property is an @Fm-delimited array containing the DPI values:

<1> X (horizontal) DPI

<2> Y (vertical) DPI

This property returns the DPI for the monitor that the top-level parent form is currently displayed on, or that the majority of the form is displayed on if using more than one monitor. Beginning with Windows 8.1 individual monitors can have their own DPI settings - prior to this the form DPI is always the same as the SYSTEM DPI property.

The form DPI is combined with its SCALEFACTOR property when calculating scaling attributes.

 
 // Get the DPI settings for the current control//
 
 CtrlDPI = Get_Property( ctrlEntID, "DPI" )
 

Common GUI DPI property, SYSTEM DPI property, WINDOW SCALEFACTOR property, WINDOW SCALED event, Appendix K – High-DPI Programming.

Specifies if the form uses Desktop Window Manager (DWM) animations when being displayed.

This is a boolean property. If TRUE$ then DWM animations are enabled, or FALSE$ if they are disabled.

This property is only effective when Windows is using the DWM for rendering, i.e. on Windows Vista/7 running full Aero, or Windows 8 onwards.

The property implements the DWMWA_TRANSITIONS_FORCEDISABLED attribute of the DwmGetWindowAttribute and DwmSetWindowAttribute Windows API functions. Please see the Microsoft website for further information on these functions.

     
 // Example –turn off DWM animations for the current window.//
 
 Call Set_Property_Only( @Window, "DWMANIMATION", FALSE$ )   
 

N/a.

Returns the name of the first control that receives the input focus when the specified form is created.

This is a string value containing the fully qualified name of a control, or null if no controls on the form could accept the input focus.

When a form is created the Presentation Server scans through its controls in tab-order looking for the first control that can accept the input focus. This property returns the name of that control.

     
 // Example – get the first control for the current form.//
 
 FocusCtrl = Get_Property( @Window, "FIRSTFOCUS" )
 

Common GUI FOCUS property, SYSTEM FOCUS property, WINDOW GOTFOCUSCONTROL property, WINDOW INITIALFOCUS property.

Gets or sets the border style of the form.

This in integer value that specifies the appearance and behavior of a form's border. It can be one of the following:

Note that the "Tool" styles also have the following restrictions:

• Minimize, maximize and help buttons are not allowed.
• Tool-style forms do not appear on the Windows taskbar.
• Tool-style forms will not display an icon.

The descriptions of the various border styles given above can vary depending on the current Windows visual style. For example, on Windows 10 all borders are a single pixel wide and the Tool form styles have the same caption bar height as the other styles. The differences in earlier versions of Windows were more pronounced.

Equated constants for this property can be found in the PS_WINDOW_EQUATES insert record.

     
 // Example – set current form's border style to "none".//
 $Insert PS_Window_Equates
 
 PrevStyle = Set_Property( @Window, "FORMBORDERSTYLE", PS_FORMBORDERSTYLE_NONE$ )
 

WINDOW HELPBUTTON property, WINDOW ICON property, WINDOW MAXIMIZEBUTTON property, WINDOW MINIMIZEBUTTON property, WINDOW SHOWCAPTION property, WINDOW SIZINGMODE property, WINDOW SYSTEMMENU property, WINDOW TASKBARID property.

Returns the last control on the form with a GOTFOCUS event handler that had the input focus.

This is a string value containing the fully qualified name of a control, or null if no controls on the form with a GOTFOCUS event handler have had the input focus yet.

N/a.

     
 // Example – get the last control on the current form with a GOTFOCUS handler that//
 // had the input focus//

 GotFocusCtrl = Get_Property( @Window, "GOTFOCUSCONTROL" )
 

Common GUI FOCUS property, SYSTEM FOCUS property, WINDOW FIRSTFOCUS, WINDOW INITIALFOCUS property.

Specifies if a help button is displayed on the form's caption bar.

This is a boolean value. It returns TRUE$ if a button should be displayed, or FALSE$ otherwise.

When the help button is clicked the cursor changes to an arrow with a question mark. Clicking on an object with this cursor will trigger a HELP event for the object.

A help button can only be displayed if the follow criteria are met:

• The form has a caption bar.
• The form does not have a minimize or maximize button in its caption bar.
• The form does not have one of the "tool" styles set for its FORMBORDERSTYLE property.

This property implements the WS_EX_CONTEXTHELP extended window style. Please see the Microsoft website for more details.

Example – Show a help button on the form's caption bar

 
 Call Set_Property_Only( @Window, "HELPBUTTON", TRUE$ )   
 

WINDOW FORMBORDERSTYLE property, WINDOW MAXIMIZEBUTTON property, WINDOW MINIMIZEBUTTON property, WINDOW SHOWCAPTION property, Common GUI HELP event.

Gets or sets the animation used with the HIDE method for the specified form.

This is an integer value that can be one of the following:

This property does not apply when used with an MDI Child form.

Equated constants for the HIDEEFFECT property value can be found in the PS_WINDOW_EQUATES insert record.

     
 // Example - set the HIDEEFFECT to "Slide Up" and hide the form//
 $Insert PS_Window_Equates
 
 Call Set_Property_Only( @Window, "HIDEEFFECT", PS_SHE_SLIDE_UP$ )
 Call Exec_Method( @Window, "HIDE" )
 

WINDOW SHOWEFFECT property, WINDOW TRANSLUCENCY property, WINDOW VISIBLE property, WINDOW HIDE method, WINDOW SHOW method.

Specifies the name of the icon displayed in the form's caption bar, and if appropriate, the Windows TaskBar. The icon is also used to access the form's System Menu.

This can be one of three formats:

• A path and file name of an icon (.ico) file.
• A path and file name to a resource file (such as a DLL) containing the icon, along with its resource ID. The latter component is separated from the file name by a “#” character.

E.g.

.\res\MyAppRes.Dll#192

.\res\MyAppRes.Dll#MYICON

• The name of a Windows system Icon:
  • "APPLICATION"
  • "ERROR"
  • "INFORMATION"
  • "QUESTION"
  • "WARNING"
  • "SHIELD"

A form must have a System Menu if it wants to display an icon on the caption bar.

Equated constants for using System Icons can be found the PS_SYSICON_EQUATES insert record.

 
 Declare Function Repository
 $Insert PS_SysIcon_Equates
 
 // Example 1 – setting an ICON property with a normal filename//
 IcoFile = ".\icons\rti_ide.res\rti_test_dummy.ico"
 Call Set_Property_Only( @Window, "ICON", IcoFile )
 
 // Example 2 – setting an ICON property with a resource from a DLL.//
 // (the icon with an ID of "1" from Oengine.dll)//
 
 IcoFile = "oengine.dll#1"
 Call Set_Property_Only( @Window, "ICON", IcoFile )
    
 // Example 3 – setting an ICON property with a System Icon//
 IcoFile = "WARNING"
 Call Set_Property_Only( @Window, "ICON", IcoFile )
 
 // Example 4 – setting an ICON property using a repository ID//
 // //
 // IMAGE entities always return the filename in field 1//
 IcoFile = Repository( "ACCESS", PS_REP_SYSICON_QUESTION$ )<1>
 Call Set_Property_Only( @Window, "ICON", IcoFile )
    

WINDOW SHOWCAPTION property, WINDOW SYSTEMMENU property, WINDOW TASKBARBUTTON property, WINDOW TASKBARID property, Appendix J – System Icons.

Returns the current row key associated with the primary table data row in a data-bound form.

This property is string value containing the data row key if a row is loaded into the form and it is successfully locked by the form. If the form has not locked the row (i.e. it is in "View-Only" mode) then the ID property returns a null string instead.

This property does not return the keys associated with secondary tables in a multi-table form.

     
 // Example - assume the current form has loaded a row from the database with a key//
 // of "UK007" and the row has been locked successfully by the form.//
 
 RowID = Get_Property( @Window, "ID" )  
 
 // RowID contains "UK007"//
 
 // Example - assume the current form has loaded a row from the database with a key//
 // of "UK007" and the row has NOT been locked successfully by the form.//
 
 RowID = Get_Property( @Window, "ID" )  
 
 // RowID now contains ""//
 

WINDOW ATRECORD property, WINDOW ROW property, WINDOW RECORD property, WINDOW TABLE property, WINDOW READROW method, WINDOW READ event.

Specifies the control that receives the input focus when a form is activated.

This is a string value containing the fully qualified name of a control, or null if no controls on the form could accept the input focus.

This property is set when a control receives the input focus and is constantly updated as the user moves between controls on a form. This is to ensure that a user who switches to another form is returned to the same control when the first form is activated once more.

(Contrast this with the FIRSTFOCUS property which is only set when the form is first created and remains constant.)

     
 // Example – get the "initial-focus" control for the current form.//
 
 FocusCtrl = Get_Property( @Window, "INITIALFOCUS" )
 

Common GUI FOCUS property, SYSTEM FOCUS property, WINDOW GOTFOCUSCONTROL property, WINDOW FIRSTFOCUS property.

Specifies the starting location of the specified form.

This is an integer value that can be one of the following:

This property does not apply when used with an MDI Child form.

Equated constants for the INITIALPOSITION property value can be found in the PS_WINDOW_EQUATES insert record.

     
 // Get the current form's INITIALPOSITION setting//     
 
 InitPos = Get_Property( @Window, "INITIALPOSITION" )  
 

Common GUI SIZE property, Common GUI SYSTEMSIZE property, Common GUI RECT property, Common GUI LEFT property, Common GUI TOP property, WINDOW CENTER method.

Specifies the data-binding options for the form.

This value is an @Fm-delimited array of data-binding options. See each individually named property for more information.

This property is available for backwards compatibility with earlier versions of OpenInsight and has been deprecated. From version 10 onwards each of the options above is exposed by its own individual property and these should be used in preference to the IOOPTIONS property.

Equates constants for the IOOPTIONS property can be found in the OIWIN_EQUATES insert record.

     
 // Example - set the  "RequireOnWrite" option for the current form//
 $Insert OIWin_Equates
 
 Options = Get_Property( @Window, "IOOPTIONS" )
 
 Options<FIO_REQONWRITEONLY$> = TRUE$
 
 Call Set_Property_Only( @Window, "IOOPTIONS", Options )
 

WINDOW ALLOWSELFLOCKS property, WINDOW ALLOWFORMSTATECHANGEDEVENTS, WINDOW LOADPREVALWAYS property, WINDOW LOCKCOORDINATION property, WINDOW LOCKLEVEL property, WINDOW LOCKMODE property, WINDOW NOCLEARONWRITE property, WINDOW NUMERICCOMPARE property, WINDOW QBFREADMODE property, WINDOW REQUIREONWRITE property, WINDOW SUPPRESSSAVEWARN property, WINDOW WRITEMODE property.

Specifies if the form's PREVROWVAL (previous data row) property is updated during a read operation as well as a write operation.

This is boolean value – if TRUE$ then PREVROWVAL is updated during a read operation otherwise it is only updated during a write operation. The default is FALSE$.

When a row is written the system keeps a cached version of the data that was updated in a property called PREVROWVAL. This data is then used with subsequent calls to the READPREVROW method to populate data-bound controls with data from the previous row. By default, the PREVROWVAL is only updated from a write operation, but setting this property to TRUE$ ensures that it is updated from a read operation too.

     
 // Example – Set the current form's LOADPREVALWAYS property.//
 
 Call Set_Property_Only( CtrlEntID, "LOADPREVALWAYS", TRUE$ )
 

WINDOW IOOPTIONS property, WINDOW PREVROWVAL property, WINDOW READPREVROW method, WINDOW READ event, WINDOW WRITE event.

Specifies if table-lock coordination is used by a form in conjunction with record locking.

This is an integer value that can be one of the following:

Equated constants for use with the LOCKCOORDINATION property may be found in the PS_WINDOW_EQUATES insert record.

     
 // Example - set the LOCKCOORDINATON property to use table locks.//
 $Insert PS_Window_Equates
 
 PrevVal = Set_Property( @Window, "LOCKCOORDINATION", PS_LKCOORD_WITHTABLE$ )
 

WINDOW IOOPTIONS property, WINDOW LOCKLEVEL property.

Specifies the type of row locking used by a form.

This is an integer value that can be one of the following:

Equated constants for use with the LOCKTYPE property may be found in the PS_WINDOW_EQUATES insert record.

     
 // Example - set the LOCKTYPE property to use No Locking.//
 $Insert PS_Window_Equates
 
 PrevVal = Set_Property( @Window, "LOCKTYPE", PS_LKCOORD_WITHTABLE$ )
 

WINDOW IOOPTIONS property, WINDOW LOCKCOORDINATION property.

Specifies if a maximize button is displayed on the form's caption bar.

This is a boolean value. It returns TRUE$ if a button should be displayed, or FALSE$ otherwise.

Clicking this button maximizes the form. When this form is maximized this button changes to a "restore" button – clicking this returns the form to its pre-maximized size.

A maximize button can only be displayed if the follow criteria are met:

• The form has a caption bar.
• The form does not have a help button in its caption bar.
• The form does not have one of the "tool" styles set for its FORMBORDERSTYLE property.

This property implements the WS_MAXMIZEBUTTON window style. Please see the Microsoft website for more details.

A minimize button is always displayed with a maximize button, even if the former is disabled (i.e. the form's MINIMIZEBUTTON property is set to FALSE$).

Example – Show a maximize button on the form's caption bar

 
 Call Set_Property_Only( @Window, "MAXIMIZEBUTTON", TRUE$ )   
 

WINDOW FORMBORDERSTYLE property, WINDOW HELPBUTTON property, WINDOW MINIMIZEBUTTON property, WINDOW SHOWCAPTION property, WINDOW VISIBLE property.

Activates an MDI child form or returns the name of the currently active MDI child form for the specified MDI frame form.

This is a string value containing the fully qualified name of an active MDI child form. If an MDI frame form contains no MDI child forms this property returns a null string.

This property applies to MDI frame forms only.

 // Example - activate the CUSTOMERS MDI child form in the current MDI//
 // frame form//
 
 PrevActiveID = Set_Property( @Window, "MDIACTIVE", "CUSTOMERS" )
 

WINDOW MDIFRAME property, WINDOW STARTMDICHILDFORM method, Start_MDIChild stored procedure.

Returns the name of the parent MDI frame form for the specified MDI child form.

This is a string value containing the fully qualified name of an MDI frame form. If used with a non-MDI child form it returns a null string.

This property mainly applies to MDI child forms. If used on an MDI frame form it returns its own name, while if used on a non-MDI form it returns a null string.

 // Example - get the MDI frame form for the current MDI child form//
 
 MDIFrame = Get_Property( @Window, "MDIFRAME" )
 

WINDOW MDIACTIVE property, WINDOW STARTMDICHILDFORM method, Start_MDIChild stored procedure.

Specifies if a minimize button is displayed on the form's caption bar.

This is a boolean value. It returns TRUE$ if a button should be displayed, or FALSE$ otherwise.

Clicking this button minimize the form.

A minimize button can only be displayed if the follow criteria are met:

• The form has a caption bar.
• The form does not have a help button in its caption bar.
• The form does not have one of the "tool" styles set for its FORMBORDERSTYLE property.

This property implements the WS_MINIMIZEBUTTON window style. Please see the Microsoft website for more details.

A maximize button is always displayed with a minimize button, even if the former is disabled (i.e. the form's MAXIMIZEBUTTON property is set to FALSE$).

Example – Show a minimize button on the form's caption bar

 
 Call Set_Property_Only( @Window, "MINIMIZEBUTTON", TRUE$ )   
 

WINDOW FORMBORDERSTYLE property, WINDOW HELPBUTTON property, WINDOW MAXIMIZEBUTTON property, WINDOW SHOWCAPTION property, WINDOW VISIBLE property.

Specifies if multiple instances of the same form may be executed in the same session at runtime.

This is a boolean value. It returns TRUE$ if the multiple instances are allowed, or FALSE$ otherwise.

N/a.

     
 // Example – Determine if the current form is multi-instance.//
 
 IsMulti = Get_Property( @Window, "MULTIINSTANCE" ) 
 

WINDOW STARTFORM method, WINDOW STARTMDICHILDFORM method.

Returns TRUE$ if the specified data-bound form has loaded a new (blank) data row.

This is a boolean value. It returns TRUE$ if the form has loaded a new row, or FALSE$ otherwise.

N/a.

     
 // Example – Determine if the current form is working with a new data row://
 
 IsNewRow = Get_Property( @Window, "NEWROW" ) 
 

WINDOW ID property, WINDOW ROW property, WINDOW READROW method, WINDOW READ event.

Specifies if a data bound form clears its contents after a successful write operation.

This is a boolean value. It returns TRUE$ if the form keeps its contents after a successful write operation, or FALSE$ (the default) if it clears them,

N/a.

     
 // Example – Determine if the current form is set to clear after a write//
 
 IsClearForm = Not( Get_Property( @Window, "NOCLEARONWRITE" ) )   
 

WINDOW IOOPTIONS property, WINDOW WRITEROW method, WINDOW CLEAR event, WINDOW WRITE event.

Specifies if a top-level form does not become the foreground window when the user clicks on it (i.e. it is prevented from “activating”).

This property is a boolean value. If the form is prevented from activating this property returns TRUE$, otherwise it returns FALSE$ (the default).

A top-level form with NOACTIVATE set to TRUE$ exhibits the following behaviour:

• It does not become the foreground window when the user clicks it.
• It does not become the foreground window when created.
• The system does not bring this window to the foreground when the user minimizes or closes the foreground window.
• The form does not appear on the taskbar.

Note however that clicking a control on the form that does accept the focus will activate it.

For more information on this property please refer to the Windows documentation regarding the WS_ WS_EX_NOACTIVATE window style on the Microsoft Website.

 
 // Determine if the current window has the WS_EX_NOACTIVATE style set.//
 
 bNoActivate = Get_Property( @Window, "NOACTIVATE" )
 

Common GUI FOCUS property, SYSTEM FOCUS property, WINDOW FIRSTFOCUS property, WINDOW VISIBLE property, WINDOW STARTFORM method, WINDOW ACTIVATED event, WINDOW INACTIVATED event.

Specifies the type of comparison the form write operation uses to determine if a column needs updating.

This is a boolean value. It returns FALSE$ (the default) if the form always uses a string comparison operation when scanning for changed columns, or TRUE$ if it can use a numeric one where appropriate.

When a form executes a write operation it compares the data in each column bound to a control with the version currently on disk to see if an update is required. In early versions of OpenInsight this was performed as a simple equality test which could lead to some issues if the value "0" was compared to a null value (they would appear equal to the simple logical test, which is probably not the right answer). Later versions of OpenInsight switched to forcing a full string comparison instead so that the tests were more accurate. As a result of this the NUMERICCOMPARE property was introduced to allow for backwards compatibility.

     
 // Example – Set the current form to use the simple numeric compare//
 
 Call Set_Property_Only( @Window, "NUMERICCOMPARE", TRUE$ )   
 

WINDOW IOOPTIONS property, WINDOW WRITEROW method, WINDOW WRITE event.

Specifies a small icon that may be used to overlay the normal icon on a form's taskbar button.

This is string value containing the name and path of an icon file.

If you wish to use an icon stored in the OpenInsight repository then use the Repository stored procedure along with the ACCESS method to return the icon details. The file and path name for the icon file is specified in the first field.

Note that an overlay icon may only be set once Windows has created a taskbar button for the form, so it is necessary to check if the TASKBARBUTTON property returns TRUE$ first.

     
 // Example - set an overlay icon for the current form using the //
 // file name and path from a repository entity//
 Declare Function Repository
 
 IconRec  = Repository( "ACCESS", @AppID : "*IMAGE*ICO*OI10" )
 IconFile = IconRec<1>
 
 Call Set_Property_Only( @Window, "OVERLAYICON", IconFile )
 

WINDOW ICON property, WINDOW TASKBARBUTTON property, WINDOW TASKBARID property.

Gets or sets the owner of the specified form.

This is string value containing the name of a running top-level form.

When a form is created one of the parameters passed is the name of a parent form, which becomes the "owner" of the new form. When a form is owned by another form it exhibits the following characteristics:

• An owned form is always above its owner in the z-order.
• The system automatically destroys an owned form when its owner is destroyed.
• An owned form is hidden when its owner is minimized.
• An owned form does not have a button on the taskbar.

With Get_Property the OWNER and the PARENT property usually return the same value. However, it is not possible to change a form's owner with the PARENT property or the SETPARENT method because that will make it a child object which means it will no longer be a top-level form. Only the OWNER property can change a form's owner while maintaining its top-level state.

     
 // Example - Set the owner of a the current form to MAIN_APP_FORM//
 
 Call Set_Property_Only( @Window, "OWNER", "MAIN_APP_FORM" )
 

Common GUI CHILDOBJECT property, Common GUI PARENT property, Common GUI SETPARENT method, WINDOW STARTFORM method, WINDOW SHOWDIALOG method, WINDOW SHOWMESSAGE method, WINDOW SHOWPOPUP method.

Gets or sets the show state and the restored, minimized, and maximized positions of the specified form.

This value is an @Fm-delmited array of placement information:

\\    <0,1> Left\\    <0,2> Top\\    <0,3> Width\\    <0,4> Height\\ 

\\    <0,1> Left\\    <0,2> Top\\ 

\\    <0,1> Left\\    <0,2> Top\\ 

If the form is a top-level form that does not have a "Tool"-style FORMBORDERSTYLE property, then the coordinates in the structure above are in workspace coordinates, otherwise these are in screen coordinates. Therefore these coordinates should only be used with the PLACEMENTDATA property and not with the normal SIZE property.

(Workspace coordinates differ from screen coordinates in that they take the locations and sizes of application toolbars (including the taskbar) into account. Workspace coordinate (0,0) is the upper-left corner of the workspace area, the area of the screen not being used by application toolbars).

For more information on this property please refer to the Windows documentation regarding the GetWindowPlacement and SetWindowPlacement on the Microsoft website.

Equates constants for the PLACEMENTDATA property can be found in the PS_WINDOW_EQUATES insert record.

     
 // Example - set the  "RequireOnWrite" option for the current form//
 $Insert OIWin_Equates
 
 Options = Get_Property( @Window, "IOOPTIONS" )
 
 Options<FIO_REQONWRITEONLY$> = TRUE$
 
 Call Set_Property_Only( @Window, "IOOPTIONS", Options )
 

Common GUI MONITOR property, Common GUI RECT property, Common GUI SIZE property, SYSTEM MONITORLIST property, WINDOW VISIBLE property.

Returns the values that were held in the specified form's controls for a previously loaded data row.

This property is a dynamic array that contains the data extracted from the form's controls from a previously loaded row (The format of the array is determined by the "row-map" which is a structure built by the form compiler at design-time).

By default, when data is saved in a form, a copy of the data from the data-bound controls is cached and exposed via the PREVROWVAL property. This data may later be loaded back into the controls by using the form's READPREVROW method, thereby allowing easy duplication of previously entered values into the form's current data row.

If the form's LOADPREVALWAYS property is set to TRUE$ then the PREVROWVAL is set when a row is read into the form as well as when it has been saved.

(Note: This property was designed to emulate the "Alt-C" functionality for a data-bound form as found in Advanced Revelation applications - this feature would automatically populate the data-bound prompts on screen from previously loaded data).

Example - get the current form's previously saved data in "row-map" format.

 
 PrevRow = Get_Property( @Window, "PREVROWVAL" )
 

WINDOW LOADPREVALWAYS property, WINDOW READPREVROW method, WINDOW READROW method, WINDOW WRITEROW method, WINDOW READ event, WINDOW WRITE event.

Sets the state of the current progress information on the specified form's taskbar button.

This is an integer value that can be one of the following:

If the form does not have its own taskbar button and is grouped with other forms, the taskbar button for the group displays the progress information.

     
 // Example - simple loop to show progress information on the taskbar //
 $Insert PS_Window_Equates
 
 XCount = 100
 For X = 1 To XCount
 
    // Update the Progress value//
    Call Set_Property_Only( @Window, "PROGRESSVALUE", X : @Fm : XCount )
    
    // Call a function//
    Call SomeFunction()
    
    // If there's an error then set the progress state to an error state//
    If Get_Status( ErrorText ) Then
       Call Set_Property_Only( @Window, "PROGRESSSTATE", PS_PGS_ERROR$ )
       
       // Handle Error and assume fixed so set the state back to normal//
       Call Set_Property_Only( @Window, "PROGRESSSTATE", PS_PGS_NORMAL$ )
        
    End
 
 Next
 
 // Remove the progress information//
 Call Set_Property_Only( @Window, "PROGRESSVALUE", 0 : @fm : 0 )
 

PROGRESSBAR SYNCTASKBAR property, WINDOW PROGRESSVALUE property, WINDOW TASKBARBUTTON property, WINDOW TASKBARID property.

Displays progress information on the specified form's taskbar button.

This is an @Fm delimited array containing progress information:

Setting the CurrentValue and MaximumValue fields to 0 removes the progress information from the taskbar button.

If the form does not have its own taskbar button and is grouped with other forms, the taskbar button for the group displays the progress information.

     
 // Example - simple loop to show progress information on the taskbar //
 $Insert PS_Window_Equates
 
 XCount = 100
 For X = 1 To XCount
 
    // Update the Progress value//
    Call Set_Property_Only( @Window, "PROGRESSVALUE", X : @Fm : XCount )
    
    // Call a function//
    Call SomeFunction()
    
    // If there's an error then set the progress state to an error state//
    If Get_Status( ErrorText ) Then
       Call Set_Property_Only( @Window, "PROGRESSSTATE", PS_PGS_ERROR$ )
       
       // Handle Error and assume fixed so set the state back to normal//
       Call Set_Property_Only( @Window, "PROGRESSSTATE", PS_PGS_NORMAL$ )
        
    End
 
 Next
 
 // Remove the progress information//
 Call Set_Property_Only( @Window, "PROGRESSVALUE", 0 : @fm : 0 )
 

PROGRESSBAR SYNCTASKBAR property, WINDOW PROGRESSSTATE property, WINDOW TASKBARBUTTON property, WINDOW TASKBARID property.

Gets or sets the QBF result list, i.e. the array of data keys used by the current QBF (Query-By-Form) session for the specified form

This is an @Fm-delimited list of keys to use with the current QBF session.

When setting the QBFLIST property the first key in the list is automatically loaded into the form via the SHOWQBFFIRST method. If the QBF session has not been initialized via the QBFINITSESSION method, this is called internally first.

Setting an empty list will close the QBF session via the QBFCLOSESESSION method.

     
 // Example - select data from a table and load the list of keys as a QBFLIST//
 $Insert RList_Equates
 
 Call RList( "SELECT CUSTOMERS WITH STATE EQ 'CA'", TARGET_ACTIVELIST$, "", "", "" )
 
 QBFKeys = ""
 Eof     = FALSE$
 Loop
    ReadNext Key Else Eof = TRUE$
 Until Eof
    QBFKeys := Key : @fm
 Repeat
 QBFKeys[-1,1] = ""
    
 Call Set_Property_Only( @Window, "QBFLIST", QBFList )   
 

WINDOW QBFSHOWFIRST method, WINDOW QBFCLOSESESSION method, WINDOW QBFSHOWTABLE method, WINDOW QBFFIRST event, WINDOW QBFCLOSE event.

Gets or sets the index of the row to display when the specified form has a valid QBF result list (QBFLIST property) loaded.

This is an integer value that must contain a valid position index for the list of keys in the QBFLIST property.

Setting this property triggers the form's QBFABS event.

     
 // Example - Assume we have been given a key that is in the QBFLIST//
 //           and we wish to load it into the form.//
 
 QBFList = Get_Property( @Window, "QBFLIST" )
 
 Locate CustKey In QBFLIst Using @Fm Setting Pos Then
    Call Set_Property_Only( @Window, "QBFPOS", Pos )
 End
 

WINDOW QBFSHOWFIRST method, QBFSHOWLAST method, WINDOW QBFSHOWNEXT method, WINDOW QBFSHOWPREV method, WINDOW QBFSHOWTABLE method, WINDOW QBFABS event.

Returns the status of the QBF session for the specified form.

This is an integer value that can be one of the following:

Equated constants for the QBF status values can be found in the RTI_QBF_EQUATES insert record.

     
 // Example - Get the QBFSTATUS so we have set the UI controls accordingly//
 $Insert RTI_QBF_Equates
 
 QBFStatus = Get_Property( @Window, "QBFSTATUS" )
 
 Begin Case
    Case ( QBFStatus = QBFSTAT_OFF$ )
       // Disable all QBF buttons except the QBF init session//
       
    Case ( QBFStatus = QBFSTAT_INIT$ )
       // Use is entering a query - enable the QBF close session and //
       // run query buttons, but all other QBF buttons are disabled.//
       
    Case ( QBFStatus == QBFSTAT_ACTIVE$ )
       // A QBFLIST has been loaded - enable all QBF buttons except //
       // the  QBF init session and run query //
      
 End Case
 

WINDOW QBFCLOSESESSION method, WINDOW QBFINITSESSION method, WINDOW QBFRUNQUERY method, WINDOW QBFCLOSE event, WINDOW QBFINIT event, WINDOW QBFRUN event.

Specifies if and how a form triggers the READ event when loading data during QBF processing.

This is an integer value that can be one of the following:

By default (and to preserve backwards compatibility) the QBF events that load data into controls (QBFFIRST, QBFNEXT, QBFPREV, QBFLAST, QBFABS) do not use the normal READ event handler to accomplish this because they have their own internal methods (see the OnlyQBF option above). This means that any custom READ event processing required by the form when loading data will not be executed.

In previous versions of OpenInsight it was possible to set a flag in the form's IOOPTIONS property to trigger a READ event after the QBF load (this is exposed as the QBFThenRead option above), but this not an optimal solution because the data in the form will be loaded twice: once in the QBF event, and once in the READ event which, of course, is not very efficient.

This version of OpenInsight introduces the OnlyRead option instead, which means that the QBF processor uses the standard READ process to load data records, thereby ensuring that any custom pre/post READ event processing will executed. This is the preferred option and should be adopted where possible.

     
 // Example – Determine if the current form is set to trigger a READ event after QBF//     
 // Loading.//
 
 QBFReadMode = Get_Property( @Window, "QBFREADMODE" )   
 

WINDOW IOOPTIONS property, WINDOW QBFABS event, WINDOW QBFFIRST event, WINDOW QBFNEXT event, WINDOW QBFPREV event, WINDOW QBFLAST event, WINDOW READ event.

Gets or sets the cached copy of the data row associated with the specified form.

This property is a dynamic array that represents a database row for the primary table bound to the form. Its structure is determined by dictionary of the table.

When the data for the form's primary table is read at runtime a cached copy is stored in memory. This cached copy is updated from the controls as the user interacts with the form (usually during LOSTFOCUS and POSCHANGED events). The cached copy is then used to populate the @Record global variable before any CALCULATE events are executed on the controls in the form.

Setting this property (and therefore the cached copy) will not refresh the data held in the data-bound controls, nor will it allow an update of any non-control bound columns when the form's WRITE event is executed. The ROW property should be used for this purpose instead.

This property is considered deprecated in favor of the ROW property. New applications should use ROW to work with the cached version of the data row for more consistent and expected results when using a "single form – single row" model.

     
// RECORD example - update the cached version of the data row – note this will only//
// affect subsequent CALCULATE events - consider using the ROW property instead to   //
// see changes in the controls and updates written to disk.//

MyRecord<1> = "Mr"
PrevVal = Set_Property( @Window, "RECORD". MyRecord ) 
 

WINDOW ATRECORD property, WINDOW ROW property, WINDOW WRITEMODE property.

Specifies when a form performs "required data" checks.

This is a boolean value. When set to TRUE$ the form only performs "required data" checks just prior to a write operation and blocks the write if any controls have missing data. When set to FALSE$ (the default) the checks are performed as the user moves between controls on the form (via the LOSTFOCUS and POSCHANGED events).

N/a.

     
 // Example – Determine if the current form is set to check for missing data//

just before a write operation

 
 IsRequiredOnWrite = Get_Property( @Window, "REQUIREONWRITE" )   
 

Common GUI REQUIRED property, WINDOW IOOPTIONS property, WINDOW WRITEROW method, WINDOW WRITE event.

Returns the position and size of the specified form in its non-maximized/minimized state.

This property value is an @Fm-delimited array of integer coordinates in DIPs (Device Independent Pixels):

<1> Left

<2> Top

<3> Width

<4> Height

Each form keeps a copy of the "restore size", which is its position and size before it was maximized or minimized.

This value is updated when the form is resized or moved when not minimizing or maximizing.

This value is always returned as Device Independent Pixels (DIPs).

 
 // Get the RESTORESIZE of the current form//
 
 RestoreSize = Get_Property( @Window, "RESTORESIZE" )
 

Common GUI RECT property, Common GUI SIZE property, WINDOW VISIBLE property, WINDOW SIZE event.

Gets or sets data associated with the primary table for the specified data-bound form and updates its data-bound controls.

When getting the property, the data is extracted directly from the controls on the form and merged with a cached version of the data row that was read from disk during the READ event.

When setting the ROW property, the cached copy of the form's data row is replaced and then the data-bound controls are automatically populated from that. The form's WRITEMODE property is automatically set to "WriteEntireRow" and the SAVEWARN property is also set to TRUE$.

This property is a dynamic array that represents a database row for the primary table bound to the form. Its structure is determined by dictionary of the table.

By default the WRITE event of a form only updates the columns in the database table that are bound directly to controls on the form – any data columns that are not bound to a control are ignored by the write processor. The intent behind this default behavior is to prevent data corruption in cases where different forms load different columns from the same row at runtime. If each form updated the non-bound columns during the write process it would be possible to overwrite new data with stale data.

However, this "multiple forms per single row" model is not as common as a "single form – single row" model, and there is an expectation that when setting the contents of the entire row at runtime the following is true:

• Any data-bound controls are updated from the contents of the new row.
• Any columns not bound to controls will still be written back to disk.

The ROW property fulfills both expectations in a single operation, whereas previous versions of OpenInsight would need to use the ATRECORD property and the WRITEATRECORD properties together.

(This emulates the functionality of setting the @Record variable for a data-bound form in an Advanced Revelation application which would automatically populate the data-bound prompts on screen.)

     
 // Example - a table has five columns://
 ////
 //   CUST_ID        (key)//
 //   TITLE          <1>//
 //   FORENAME       <2>//
 //   SURNAME        <3>//
 //   DATE_OF_BIRTH  <4>//
 ////
 // It is bound to a form that has the following three controls://
 ////
 //   EDL_CUST_ID    -> CUST_ID (key)//
 //   EDL_FORENAME   -> FORENAME//
 //   EDL_SURNAME    -> SURNAME//
 ////
 // The form is loaded with record "C1234" which has the following data://
 // //
 // <1> MR//
 // <2> REN//
 // <3> HOEK//
 // <4> 65478//
 ////
 // Enter "STIMPSON J" in EDL_FORENAME//
 
 Row = Get_Property( @Window, "ROW" )
 
 // Row contains://
 // <1> MR//
 // <2> STIMPSON J//
 // <3> HOEK//
 // <4> 65478//
 
 Row<1> = "SIR"
 Row<3> = "CAT"
 
 Call Set_Property_Only( @Window, "ROW", Row )
 Call Exec_Method( @Window, "WRITEROW" )
 
 // If we were to look at the record stored in the table we would now see this://
 ////
 // <1> SIR            <-- Not bound to a control but still updated//
 // <2> STIMPSON J//
 // <3> CAT//
 // <4> 65478//
 ////
 // Because the ROW property automatically sets the WRITEMODE property to//
 // "WriteEntireRow" the TITLE column (field <1>) is written back even though//
 // it is not bound to a control on the form.//
 

WINDOW ATRECORD property, WINDOW RECORD property, WINDOW SAVEWARN property, WINDOW WRITEMODE property, WINDOW READROW method, WINDOW WRITEROW method, WINDOW READ event, WINDOW WRITE event.

Returns TRUE$ if the specified data-bound form has loaded a data row and has locked it for update.

This is a boolean value. It returns TRUE$ if the form has locked a data row for update, or FALSE$ otherwise.

N/a.

     
 // Example – Determine if the current form has a locked row//
 
 IsLocked = Get_Property( @Window, "ROWLOCKED" ) 
 

WINDOW ID property, WINDOW LOCKCOORDINATION property, WINDOW LOCKTYPE property, WINDOW ROW property, WINDOW READROW method, WINDOW READ event.

Specifies if a data-bound form contains changed data that has not been saved. This property is checked by the form's default CLEAR and CLOSE event handlers to decide if a warning message should be displayed to the user that changes will be lost unless the data is saved first.

This is a boolean value. It is set to TRUE$ when data contained in the form has been changed from when it was originally loaded. It returns FALSE$ if no changes have been made.

By default, the SAVEWARN property is updated during the following events:

• It is set to FALSE$ after data has been read and loaded into the form's controls.
• It is set to TRUE$ during a data-bound control's LOSTFOCUS event when the user has changed data in the control.
• It is set to TRUE$ during a data-bound EditTable control's POSCHANGED event when the user has changed data in the control.
• It is set to TRUE$ when the DEFPROP property is used to change data in a data-bound control.

To ensure that the SAVEWARN property is updated properly, both the form's CLEAR and CLOSE events trigger a LOSTFOCUS event on the current control before they decide if a warning message needs to be shown to the user.

Setting the SAVEWARN property triggers the form's SYSMSG event with a "SAVEWARNINFO" code (21) to allow applications to track when this has been set.

The SetDebugger stored procedure may also be used as a debugging tool to track when SAVEWARN is set.

     
 // Example – Determine if data in the current form has changed//
 
 IsChanged = Get_Property( @Window, "SAVEWARN" )   
 

Common GUI DEFPROP property, WINDOW SUPPRESSSAVEWARN property, Common GUI LOSTFOCUS event, EDITTABLE POSCHANGED event, WINDOW CLEAR event, WINDOW CLOSE event, WINDOW SYSMSG event, SetDebugger stored procedure.

Specifies a custom scaling value for a form, allowing it to appear larger or smaller than normal.

This value is an @Fm-delimited array of scale factor attributes:

The ScaleFactor is applied after any scaling is applied for the monitor DPI. For example, if the form runs on a 144 DPI monitor (150%) and has a ScaleFactor of 2 applied the actual scaling factor used is 3.0 (1.5 x 2.0).

Note that the minimum and maximum sizes that a form can be rescaled to is restricted by the minimum and maximum form sizes as defined by Windows. As a general rule this size is usually slightly larger than the size of the entire desktop across all monitors (See the GetSystemMetrics() Windows API function on the Microsoft website for more details, specifically with reference to the SM_CXMAXTRACK, SM_CXMINTRACK, SM_CYMAXTRACK, and SM_CYMINTRACK indexes). This restriction can, however, override this behaviour if the TRACKINGSIZE property is adjusted for the form, specifying values large enough to handle the desired scaling range.

Equates constants for the SCALEFACTOR property can be found in the PS_WINDOW_EQUATES insert record.

     
 // Example - Set the scaling factor of the current form - the min/max/inc//
 // members can be ignored if they are unchanged.//
 
 Call Set_Property_Only( @Window, "SCALEFACTOR", 2 )
 
 // Example - Turn on mouse-wheel/pinch-zoom scaling for the current form //
 $Insert PS_Window_Equates
 
 ScaleFactor = Get_Property( @Window, "SCALEFACTOR" )
 ScaleFactor<PS_SCF_POS_INCREMENT$> = 0.1
 Call Set_Property_Only( @Window, "SCALEFACTOR", ScaleFactor )
 

SYSTEM DPI property, WINDOW DPI property, WINDOW TRACKINGSIZE property, WINDOW SCALED event, Appendix K – High-DPI Programming.

Specifies how size and position coordinates are interpreted by a form. The scale units are a setting that determines how coordinates used in properties, methods and events are interpreted – either as DIPs (Device Independent Pixels) or as actual pixels.

This property is a numeric value representing the current scale units used for getting and setting scaled properties for the object. It can be one of the following values:

All child controls on a form use the same SCALEUNITS value.

Equated constants for use with the SCALEUNITS property can be found in the PS_EQUATES insert record.

 
 // Example - Set the current form's SCALEUNITS to pixels while it is//
 // positioned and reset them afterwards//
 $Insert Ps_Equates
 
 OrigScaleUnits = Set_Property( @Window, "SCALEUNITS", PS_SCU_PIXELS$ )
 
 Call Set_Property_Only( @Window, "SIZE", NewSizeInPixels )
 
 Call Set_Property_Only( @Window, "SCALEUNITS", OrigScaleUnits )
 

All properties marked as "Scaled", Common GUI SCALEUNITS property, Appendix K – High-DPI Programming.

Specifies if a form displays a caption bar.

This is a boolean value. It returns TRUE$ if the caption bar should be displayed, or FALSE$ otherwise.

This property implements the WS_CAPTION window style. Please see the Microsoft website for more details.

Example – Remove the current form's caption bar

 
 Call Set_Property_Only( @Window, "SHOWCAPTION", FALSE$ )   
 

WINDOW FORMBORDERSTYLE property, WINDOW HELPBUTTON property, WINDOW MAXIMIZEBUTTON property, WINDOW MINIMIZEBUTTON property, WINDOW VISIBLE property.

Gets or sets the animation used with the SHOW method for the specified form.

This is an integer value that can be one of the following:

This property does not apply when used with an MDI Child form.

Equated constants for the SHOWEFFECT property value can be found in the PS_WINDOW_EQUATES insert record.

     
 // Example - set the SHOWEFFECT to "Slide Down" and show the current form//
 $Insert PS_Window_Equates
 
 Call Set_Property_Only( @Window, "SHOWEFFECT", PS_SHE_SLIDE_DOWN$ )
 Call Exec_Method( @Window, "SHOW" )
 

WINDOW HIDEEFFECT property, WINDOW TRANSLUCENCY property, WINDOW VISIBLE property, WINDOW HIDE method, WINDOW SHOW method.

Specifies if a form can be resized with the mouse. Usually the FORMBORDERSTYLE property determines if the mouse can be used to resize a form. The SIZINGMODE property may be used to override this behaviour.

This in integer value that may be one of the following values:

Equated constants for this property can be found in the PS_WINDOW_EQUATES insert record.

     
 // Example – set current form's SIZINGMODE property to "Never".//
 $Insert PS_Window_Equates
 
 PrevVal = Set_Property( @Window, "SIZINGMODE", PS_SIZINGMODE_NEVER$ )
 

WINDOW FORMBORDERSTYLE property.

Identifies the control that receives "status" messages from stored procedures when the specified form is active. Status messages are text strings sent to the Presentation Server via the Send_Info stored procedure when code is executed in event context.

This is string value containing the name of a valid control instance. The control's TEXT property is updated with the status message.

When processing a status message the Presentation Server first attempts to use the nominated STATUSLINE control on the active form. If this is not possible it then attempts to use the last valid STATUSLINE control from a previously active form. If no STATUSLINE control is available the message is sent to the results text box in the System Monitor instead.

     
 // Example set the current form's TXT_STATUS STATIC control to receive status//
 // messages from the Send_info stored procedure.//
 
 Call Set_Property_Only( @Window, "STATUSLINE", @Window : ".TXT_STATUS" )
 

Common GUI TEXT property, SYSTEM RECEIVER property, System Monitor chapter, Send_Info stored procedure.

Specifies the name of a form to use as a "styling template" when adding controls to a form at design-time.

When a new control is added to a form at design time the stylesheet form is scanned to see if it contains a control with the same type. If so, the following properties are duplicated for the new control:

• BACKCOLOR
• FORECOLOR
• FONT
• HEIGHT
• WIDTH

This is string value containing the name of a valid form.

N/a.

N/a.

N/a.

Specifies if a data-bound form checks the SAVEWARN property to see if data has changed before clearing its contents or closing.

This is a boolean value. When set to TRUE$ the form will not warn the user about unsaved changes in data-bound controls when it is cleared or closed. When set the FALSE$ (the default) then the SAVEWARN property will be processed as normal.

Setting this property to TRUE$ allows a form to be closed unconditionally.

     
 // Example – Determine if the current form is set to check for unsaved changes//

just before its contents are cleared or it is closed.

 
 NoSaveWarning = Get_Property( @Window, "SUPPRESSSAVEWARN" )   
 

WINDOW IOOPTIONS property, WINDOW SAVEWARN property, WINDOW CLEAR event, WINDOW CLOSE event, WINDOW SYSMSG event.

Specifies if a "System Menu" is allowed for the specified form. A System Menu is the default menu normally added to a form to allow some basic windowing operations:

This is a boolean value. It returns TRUE$ if the System Menu should be allowed, or FALSE$ otherwise.

A form must have a System Menu if it wants to display an icon on the caption bar.

At runtime the System Menu can be activated by clicking the form's icon on the left side of the caption bar. If the form does not have a caption bar or an icon the System Menu may still be activated by using the "Alt+Space" hot-key combination.

This property implements the WS_SYSTEMMENU window style. Please see the Microsoft website for more details.

Example – Ensure that the current form has a System Menu

 
 Call Set_Property_Only( @Window, "SYSTEMMENU", TRUE$ )   
 

WINDOW FORMBORDERSTYLE property, WINDOW ICON property, WINDOW SHOWCAPTION property.

Returns the name of the primary table that specified the form is bound to.

This property value returns the name of the primary table if any controls on the form are data-bound, otherwise it returns null.

N/a.

     
 // Example – The primary table that the form is bound to//
 
 TableList = Get_Property( CtrlEntID, "TABLE" )
 

WINDOW ATRECORD property, WINDOW ID property, WINDOW ROW property, WINDOW RECORD property, WINDOW READROW method, WINDOW READ event.

Returns a flag denoting if Windows has created a taskbar button for the specified form.

This is a boolean value. It returns TRUE$ if Windows has created a taskbar button for the form, or FALSE$ otherwise.

There is usually a short delay between a form being created and Windows adding a button for it on the taskbar, and it sends a notification to the form once the button has been added. At this point it is then possible to set an OVERLAYICON if desired.

     
 // Example - set an overlay icon, but check if the taskbar button has been created//
 
 Loop
    HasButton = Get_Property( @Window, "TASKBARBUTTON" )
 Until HasButton
    Call Yield( TRUE$ )
 Repeat
 
 Call Set_Property_Only( @Window, "OVERLAYCON", IconFile )
 

PROGRESSBAR SYNCTASKBAR property, WINDOW ICON property, WINDOW OVERLAYICON property, WINDOW TASKBARID property.

Specifies a text string used to group or ungroup forms on the Windows taskbar. By default, Windows groups all forms belonging to the same process together under same taskbar button like so (shown here grouped under the main OpenInsight process):

This behavior can be changed for a form by setting the TASKBARID property to a new text value - this forces Windows to create a new button on the taskbar instead. (All forms that share this value will be grouped together):

This is a string value – when it is not null any forms sharing the same value will be grouped under the same taskbar button. When it is null the forms will be grouped under a default taskbar button.

This property uses the Windows SHGetPropertyStoreForWindow function to set a form- specific AppUserModelID internally. More for information on this and programming the Windows taskbar please see the relevant documentation on the Microsoft website.

     
 // Example - set the TASKBARID for the current form so it appears//
 // under its own button on the TaskBar. An easy way to do this is //
 // to use its actual name, as this will always be unique within//
 // a single instance of OpenInsight//
 
 Call Set_Property_Only( @Window, "TASKBARID", @Window )
 

WINDOW ICON property, WINDOW OVERLAYICON property, WINDOW TASKBARBUTTON property.

Specifies the minimum and maximum sizes that a user may resize a form to.

This property value is an @Fm-delimited array of integer values:

<1> Minimum Tracking Width

<2> Minimum Tracking Height

<3> Maximum Tracking Width

<4> Maximum Tracking Height

Each value must be greater than zero, or have a value of "-1", which means use the default Windows value for that attribute instead.

Setting all four fields to the same non-negative value will prevent the user resizing the form with the mouse or with its System Menu (see example below).

• This is useful for preventing the resizing of MDI child forms because Windows always creates them with a resizable border style, overriding any selected design settings such as a thin, non-sizable border.

Equated constants for use with the TRACKINGSIZE property can be found in the PS_EQUATES insert record.

The TRACKINGSIZE property is used during WM_GETMINMAXINFO message processing to determine form resizing limits. Please refer to the documentation on the Microsoft website for further information regarding this process.

 
 // Example - fix the size of the form so that the user cannot change it//
 $Insert PS_Equates
 
 FormSize = Get_Property( @Window, "SIZE" )
 
 TrackSize = ""
 TrackSize<PS_TRACKSIZE_MINWIDTH$>  = FormSize<3>
 TrackSize<PS_TRACKSIZE_MINHEIGHT$> = FormSize<4>
 TrackSize<PS_TRACKSIZE_MAXWIDTH$>  = FormSize<3>
 TrackSize<PS_TRACKSIZE_MAXHEIGHT$> = FormSize<4>
 
 Call Set_Property_Only( @Window, "TRACKINGSIZE", TrackSize )
 
 // Example - set the TRACKINGSIZE back to it's default values//

 TrackSize = str( PS_TRACKSIZE_VAL_NOTSET$ : @fm, 4 )
 TrackSize[-1,1] = ""
 
 Call Set_Property_Only( @Window, "TRACKINGSIZE", TrackSize )
 

Common GUI SIZE property, WINDOW FORMBORDERSTYLE property, WINDOW SYSTEMMENU property, WINDOW SIZE event.

Specifies the degree of transparency applied to a form when it is painted. Note that unlike the common GUI TRANSLUCENCY property, this effect applies to the entire form, not just its client area.

Form with 30% TRANSLUCENCY applied

Form with 70% TRANSLUCENCY applied

This property is an integer value between 1 and 100, which represents the percentage of transparency applied to the form. A value of 0 means fully opaque, while a value of 100 means fully transparent (i.e. the form will not be drawn).

Setting the TRANSLUCENCY to 100 will hide the form, but it is still considered to be visible, i.e. the VISIBLE property will not return an WS_HIDE$ value.

 
 // Set the TRANSLUCENCY of the current form to 30%//
 
 PrevVal = Set_Property( @Window, "TRANSLUCENCY", 30 )
 
 // Remove the TRANSLUCENCY from the current form //
 
 PrevVal = Set_Property( @Window, "TRANSLUCENCY", 0 )
 
 // Hide the current form (Note – the form is still considered to be visible!)//
 
 PrevVal = Set_Property( @Window, "TRANSLUCENCY", 100 )
 

Common GUI TRANSLUCENCY property, WINDOW HIDEEFFECT property, WINDOW SHOWEFFECT property, WINDOW VISIBLE property, WINDOW HIDE method, WINDOW SHOW method property.

Specifies if a form appears above all other non-TOPMOST forms in the system z-order, even when the form is not active.

This is a boolean value. It returns TRUE$ if the form is flagged as a topmost form, or FALSE$ otherwise.

The TOPMOST property is implemented internally using the SetWindowPos Windows API function, so please refer to the documentation on the Microsoft website for further information on changing the z-order.

     
 // Example – Determine if the current form is marked as a topmost form.//
 
 IsTopMost = Get_Property( @Window, "TOPMOST" ) 
 

Common GUI SETZORDER method.

Specifies if a form is visible, hidden, maximized, or minimized.

The VISIBLE property is an integer value that specifies how the form is displayed. It may be one of the following when used with Set_Property:

When used with Get_Property only the following values are returned:

• (0) SW_HIDE (form is hidden).
• (1) SW_SHOWNORMAL (form is visible).
• (2) SW_SHOWMINIMIZED (form is visible and minimized).
• (3) SW_SHOWMAXIMIZED (for is visible and maximized).

The VISIBLE property is implemented internally using the ShowWindow Windows API function and the property value corresponds to the function's nCmdShow parameter value. Please see the Microsoft website for more details on controlling form visibility.

Constants for these values are defined in the MSWIN_SHOWWINDOW_EQUATES insert record.

 
 $Insert MsWin_ShowWindow_Equates
    

Example - Hide the current form

    
 Call Set_Property_Only( @Window, "VISIBLE", SW_HIDE$ )
 
 // Example - Maximize the current form//
 
 IsMaximized = Get_Property( @Window, "VISIBLE" )
 If IsMaximized Else
 
    Call Set_Property_Only( @Window, "VISIBLE", SW_SHOWMAXIMIZED$ )
 
 End
 

Common GUI VISIBLE property.

Specifies how data set with the ATRECORD property is saved during a write operation.

This is a boolean value. When set to TRUE$, data from columns that are not bound to a control on the form (and that were set via the ATRECORD property) is written to the table in addition to the data in the controls. When set to FALSE$ (the default) only data from the controls is written back during a write operation.

See the ATRECORD property for a full explanation of how WRITEATRECORD works in conjunction with ATRECORD.

This property is considered deprecated in favor of the WRITEMODE property. It is effectively a backwards-compatible synonym for WRITEMODE.

     
 // Example - set the WRITEATRECORD so that any data not bound to a control in the//
 // current form is still updated in the WRITE event.//
 
 Call Set_Property_Only ( @Window, "WRITEATRECORD", TRUE$ )
 Call Set_Property_Only( @Window, "ATRECORD", MyDataRow )
 

WINDOW ATRECORD property, WINDOW RECORD property, WINDOW ROW property, WINDOW WRITEMODE property.

Specifies how data set with the ROW property is saved during a write operation.

This is an integer value that can be one of the following:

See the ROW property for a full explanation of how WRITEMODE works in conjunction with ROW.

Equated constants for use with the WRITEMODE property may be found in the PS_WINDOW_EQUATES insert record.

     
 // Example - set the WRITEMODE so that any data not bound to a control in the current.//
 // form is still updated in the WRITE event.//
 $Insert PS_Window_Equates
 
 Call Set_Property_Only ( @Window, "WRITEMODE", PS_WRMD_ALL$ )
 Call Set_Property_Only( @Window, "ROW", MyDataRow )
 

WINDOW ROW property.

The WINDOW object supports the following methods in addition to the Common GUI Object methods, except where noted below:

“Attaches” a labelled common area to the form. Attached common areas are automatically freed by the form when it is destroyed.

SucessFlag = Exec_Method( CtrlEntID, "ATTACHCOMMON", CommonName )

Returns TRUE$ if the common area is attached successfully, or FALSE$ otherwise.

This method is intended to help control the lifetime of a labelled common area that is related to a form. When the common area is attached it will be freed when the form is destroyed, thereby relieving the developer of the need to free it themselves during CLOSE event processing.

     
 // Example – Attach a common area to the current form//
 
 CommName = "%%MYDATA_" : @window
 Common CommName MyVar1@, MyVar2@
 
 bOK = Exec_Method( CtrlEntID, "ATTACHCOMMON", CommName )
 

WINDOW COMMONLIST property, WINDOW DETACHCOMMON method, End_Window stored procedure.

Centers a form on the desktop or over its parent object.

NewSize = Exec_Method( CtrlEntID, "CENTER", CenterParent, IdealSize, |

CalculateOnly, ParentSize, Options )

An @Fm-delimited dynamic array containing the new size of the form in the same format as the standard SIZE property.

N/a.

 
 // Center a form on the desktop//
 Call Exec_Method( @Window, "CENTER" )
 
 // Center a form on its parent window//
 Call Exec_Method( @Window, "CENTER", TRUE$ )
 
 // Center a form on the desktop with a specific size of 800x600//
 FormSize = -1 : @Fm : -1 : @Fm : 800 : @Fm : 600
 Call Exec_Method( @Window, "CENTER", FALSE$, FormSize )
 
 // Center a form on the desktop with a specific size of 800x600//
 // but only return the coordinates - do not update the form.//
 FormSize = -1 : @Fm : -1 : @Fm : 800 : @Fm : 600
 NewSize  = Exec_Method( @Window, "CENTER", FALSE$, FormSize, TRUE$ )
 
 // Center a form on the same desktop as the RTI_IDE form and //
 // ensure it stays within the desktop boundary.//

FormSize = -20 : @Fm : 10 : @Fm : 800 : @Fm : 600

 Options    = TRUE$
 Options<2> = "RTI_IDE"
 Call Exec_Method( @Window, "CENTER", FALSE$, FormSize, FALSE$, "", Options )
 

Common GUI MONITOR property, Common GUI SCREENSIZE property, Common GUI SIZE property, SYSTEM MONITORLIST property.

Clears the data from the controls in a data-bound form by triggering the form's CLEAR event.

Status = Exec_Method( CtrlEntID, "CLEARROW", SaveKey, SuppressWarning, |

MaintainFocus )

The CLEAR event status. If this is not null then an error has occurred or the user stopped the clear request).

N/a.

 // Example - Clear the contents of the current form without any warning//
 // and change the focus back to the first in the tab-order //
 
 Call Exec_Method( @Window, "CLEARROW", FALSE$, TRUE$, FALSE$ )
 

WINDOW CLEAR event.

Closes a form by triggering its CLOSE event.

Status = Exec_Method( CtrlEntID, "CLOSE", CloseFlags, CloseAsync )

If the form is closed asynchronously a boolean value is returned; TRUE$ if the CLOSE event request has made successfully, or FALSE$ otherwise.

If the form is not closed asynchronously the event status from the underlying CLOSE event is returned - if this is not null an error has occurred (or the has user stopped the close request).

Care should be taken when closing a form from an event that is raised from one of the form's own child controls. In this case it is always better to set the CloseAsync flag to TRUE$ so that the current event has chance to finish executing before the form is destroyed.

 // Example – Close the current form asynchronously allowing for any data warnings//
 

Call Exec_Method( @Window, "CLOSE", FALSE$, TRUE$ )

WINDOW CLOSE event, End_Dialog stored procedure, End_Window stored procedure.

Closes a modal dialog box and returns a value back to the caller.

ClosedFlag = Exec_Method( CtrlEntID, "CLOSEDIALOG", RetVal )

Returns TRUE$ if the dialog box was closed, or FALSE$ otherwise.

This method is a wrapper around the End_Dialog stored procedure. Please see the End_Dialog stored procedure description for more details.

     
 // Example – Close the current dialog box returning the contents of the EDL_NAME//
 // control to the caller//
 
 RetName = Get_Property( @ Window : ".EDL_NAME", "TEXT" )
 bClosed = Exec_Method( @Window, "CLOSEDIALOG", RetName )
 

WINDOW SHOWDIALOG method, Dialog_Box stored procedure, End_Dialog stored procedure.

“Detaches” a labelled common area from the form and optionally frees it.

SucessFlag = Exec_Method( CtrlEntID, "DETACHCOMMON", CommonName, bFree )

Returns TRUE$ if the common areas was detached successfully, or FALSE$ otherwise.

N/a.

     
 // Example – Detach a common area from the current form and free it.//
 
 CommName = "%%MYDATA_" : @window
 
 bOK = Exec_Method( CtrlEntID, "DETACHCOMMON", CommName, TRUE$ )
 

WINDOW COMMONLIST property, WINDOW ATTACHCOMMON method, End_Window stored procedure, FreeCommon Basic+ statement.

Deletes the currently loaded data row in a data-bound form by triggering the form's DELETE event.

Status = Exec_Method( CtrlEntID, "DELETEROW", SuppressWarning )

The DELETE event status. If this is not null an error has occurred (or the user has stopped the delete request).

N/a.

 // Example - Delete the contents of the current form unconditionally. //
 
 Call Exec_Method( @Window, "DELETEROW", TRUE$ )
 

WINDOW DELETE event.

"Flashes" a form's caption and/or taskbar button the specified number of times to draw the user's attention to it. The active state of the window is not changed.

ActiveFlag = Exec_Method( CtrlEntID, "FLASH", FlashCount, FlashCaption, |

FlashTaskBar , FlashRate )

Returns FALSE$ if the form was inactive before the flash or TRUE$ if it was active.

The FLASH method is implemented internally using the FlashWindowEx Windows API function, so please refer to the documentation on the Microsoft website for further information.

 // Example – flash the current form continuously until it is activated. //
 
 Call Exec_Method( @Window, "FLASH", -2 )
 

WINDOW ACTIVE property.

Returns the name of the control that has the focus if the form is active, or, if the form is not active, the name of the control that will receive the focus when it is.

FocusCtrlName = Exec_Method( CtrlEntID, "GETFOCUSEDCONTROL", NoInternal )

The name of the control that is currently focused or will receive the focus when the form is activated.

Executing this method is essentially the same as using the "get" operation in the WINDOW FOCUS property to return the current focus control for the form. However, some objects, like the cell editor an in EDITTTABLE control, are marked as "internal" and it may not be appropriate to use them when returned via the FOCUS property. In this case it is better to use the GETFOCUSEDCONTROL method and the NoInternal parameter to return the parent "non-internal" control instead.

 
 $Insert Logical
 
 // Return the focused control for the current form, resolving it to a non-internal ID.//

 FocusCtrlID = Exec_Method( @Window, "GETFOCUSEDCONTROL", TRUE$ )
 

Common GUI object FOCUS property, SYSTEM FOCUS property, WINDOW FIRSTFOCUS property, WINDOW FOCUS property, WINDOW ACTIVATED event, WINDOW INACTIVATED event.

Hides a form using the specified effect.

Call Exec_Method( CtrlEntID, "HIDE", HideEffect )

N/a.

This method does not apply when used with an MDI Child form.

Equated constants for the HIDEEFFECT property value can be found in the PS_WINDOW_EQUATES insert record.

     
 // Example – hide the current form using a "Slide Up" effect//
 $Insert PS_Window_Equates
 
 Call Exec_Method( @Window, "HIDE", PS_SHE_SLIDE_UP$ )
 

WINDOW HIDEEFFECT property, WINDOW SHOWEFFECT property, WINDOW TRANSLUCENCY property, WINDOW VISIBLE property, WINDOW SHOW method.

Hides the menubar for the specified form.

Call Exec_Method( CtrlEntID, "HIDEMENUBAR" )

N/a.

N/a.

N/a.

     
 // Example – hide the menubar for the current form//
 
 Call Exec_Method( @Window, "HIDEMENUBAR" )
 

MENUBAR object, WINDOW SHOWMENUBAR method

Arranges MDI child forms in a stacked cascading formation, ensuring the title bar of each is visible.

SuccessFlag = Exec_Method( CtrlEntID, "MDICASCADE", SkipDisabled, UseZOrder )

TRUE$ if the cascade operation was successful, FALSE$ otherwise.

This method only applies to MDI frame forms.

 
 // Cascade the MDI child forms for the current MDI frame form, ignoring disabled forms.//
 
 Call Exec_Method( @Window, "MDICASCADE", TRUE$ )
 

WINDOW MDIFRAME property, WINDOW MDIICONARRANGE method, WINDOW MDITILE method.

Arranges all minimized MDI child forms for the specified MDI frame form. Non-minimized MDI child forms are not affected.

SuccessFlag = Exec_Method( CtrlEntID, "MDIICONARRANGE" )

N/a.

TRUE$ if the operation was successful, FALSE$ otherwise.

This method only applies to MDI frame forms.

This method is called by the system-level ARRANGEICONS event handler.

For more details on this method please see the documentation for the WM_MDIICONARRANGE message on the Microsoft website.

 
 // Arrange the minimized MDI child icons for the current MDI frame form//
 
 Call Exec_Method( @Window, "MDIICONARRANGE", TRUE$ )
 

WINDOW MDIFRAME property, WINDOW MDICASCADE method , WINDOW MDITILE method, WINDOW ARRANGEICONS event.

Arranges MDI child forms in a tiled format. Each child is displayed in its entirety, overlapping none of the other child forms. All of the child forms are sized, as necessary, to fit within the MDI client area.

SuccessFlag = Exec_Method( CtrlEntID, "MDITILE", TileHorizontal, SkipDisabled )

TRUE$ if the tiling operation was successful, FALSE$ otherwise.

This method only applies to MDI frame forms.

The arguments passed to this method have been changed from previous versions of OpenInsight to support horizontal tiling and the "SkipDisabled" option simultaneously.

    
 // Tile the MDI child forms vertically for the current MDI frame form, //
 // ignoring disabled child forms.//
 
 Call Exec_Method( @Window, "MDITILE", FALSE$, TRUE$ )
 

WINDOW MDIFRAME property, WINDOW MDICASCADE method, WINDOW MDIICONARRAGE method.

Asks the user for an RLIST query statement and loads the results into the specified form's QBF result list (QBFLIST property).

Status = Exec_Method( CtrlEntID, "QBFASKQUERY" )

N/a.

The QBFQUERY event status. If this is not null then an error has occurred or the user has cancelled the operation.

This method triggers the form's QBFQUERY event.

The query statement entered must be a valid RLIST SELECT statement.

 // Example – ask the user for an RLIST query//
 
 Status = Exec_Method( @Window, "QBFASKQUERY" )
 If BLen( Status ) Then
    // Error or cancelled ....//
 End
 

WINDOW QBFLIST property, WINDOW QBFQUERY event, RLIST stored procedure.

Closes the QBF session for the specified form, returning it to normal operation.

Status = Exec_Method( CtrlEntID, "QBFCLOSESESSION" )

N/a.

The QBFCLOSE event status. If this is not null then an error has occurred.

This method triggers the form's QBFCLOSE event. If successful, the form's QBFSTATUS property is set to "QBFInactive".

 // Example – end the current form's QBF session.//
 
 Status = Exec_Method( @Window, "QBFCLOSESESSION" )
 

WINDOW QBFSTATUS property, WINDOW QBFINITSESSION method, WINDOW QBFCLOSE event.

Loads a specified row from the form's QBF result list (QBFLIST property) using an index position.

Status = Exec_Method( CtrlEntID, "QBFGOTO", Position )

The QBFABS event status. If this is not null then an error has occurred, or the user has cancelled the process.

This method triggers the form's QBFABS event.

The form must have a valid QBF result list active, i.e. the QBFSTATUS property must have a value of " QBFActive".

 // Example – display the 10<sup>th</sup> row in the QBF result list//
 
 Status = Exec_Method( @Window, "QBFGOTO", 10 )
 If BLen( Status ) Then
    // Error ...//
 End
 

WINDOW QBFLIST property, WINDOW QBFPOS property, WINDOW QBFSTATUS property, WINDOW QBFABS event.

Loads a specified row from the form's QBF result list (QBFLIST property) using a row ID.

Status = Exec_Method( CtrlEntID, "QBFGOTOID", RowID )

The QBFLOADID event status. If this is not null then an error has occurred, or the user has cancelled the process.

This method triggers the form's QBFLOADID event.

The form must have a valid QBF result list active, i.e. the QBFSTATUS property must have a value of " QBFActive".

 // Example – display the row with the key of “A123” in the QBF result list//
 
 Status = Exec_Method( @Window, "QBFGOTOID", “A123” )
 If BLen( Status ) Then
    // Error ...//
 End
 

WINDOW QBFLIST property, WINDOW QBFSTATUS property, WINDOW QBFLOADID event.

Initializes and begins a QBF session for the specified form. Any existing data is cleared, and normal data validation processing is temporarily removed from controls to allow easy data entry for the query.

Status = Exec_Method( CtrlEntID, "QBFINITSESSION" )

N/a.

The QBFINIT event status. If this is not null then an error has occurred.

This method triggers the form's QBFINIT event. If successful, the form's QBFSTATUS property is set to "QBFInitialize " to signify that the form is in "query entry" mode.

 // Example – begin a QBF session for the current form.//
 
 Status = Exec_Method( @Window, "QBFINITSESSION" )
 

WINDOW QBFSTATUS property, WINDOW QBFCLOSESESSION method, WINDOW QBFINIT event.

Asks the user for the name of a saved list and loads the keys into the specified form's QBF result list (QBFLIST property).

The source of the list may be chosen from the TCL Query Table or from the SYSLISTS table.

Status = Exec_Method( CtrlEntID, "QBFLOADSAVEDLIST" )

N/a.

The QBFLOADLIST event status. If this is not null then an error has occurred or the user has cancelled the operation.

This method triggers the form's QBFLOADLIST event.

 // Example – ask the user for the list of keys to load.//
 
 Status = Exec_Method( @Window, "QBFLOADSAVEDLIST" )
 

WINDOW QBFLIST property, WINDOW QBFLOADLIST event.

Builds and executes an RLIST query from the data in the controls and populates the specified form's QBF result list (QBFLIST property).

Status = Exec_Method( CtrlEntID, "QBFRUNQUERY" )

N/a.

The QBFRUN event status. If this is not null then an error has occurred.

This method triggers the form's QBFRUN event.

The form's QBFSTATUS property must have been set to "QBFInitialize" by executing the QBFINITSESSION method first.

 // Example – execute the QBF query process to find and load the results into the//
 // current form://
 
 Status = Exec_Method( @Window, "QBFRUNQUERY" )
 

WINDOW QBFLIST property, WINDOW QBFSTATUS property, WINDOW QBFINITSESSION method, WINDOW QBFRUN event.

Loads the first row from the specified form's QBF result list (QBFLIST property).

Status = Exec_Method( CtrlEntID, "QBFSHOWFIRST" )

N/a.

The QBFFIRST event status. If this is not null then an error has occurred.

This method triggers the form's QBFFIRST event.

The form must have a valid QBF result list active, i.e. the QBFSTATUS property must have a value of " QBFActive".

 // Example – display the first row in the QBF result list//
 
 Status = Exec_Method( @Window, "QBFSHOWFIRST" )
 If BLen( Status ) Then
    // Error ...//
 End
 

WINDOW QBFLIST property, WINDOW QBFPOS property, WINDOW QBFSTATUS property, WINDOW QBFSHOWLAST method, WINDOW QBFSHOWNEXT method, WINDOW QBFSHOWPREV method, WINDOW QBFSHOWTABLE method, WINDOW QBFFIRST event.

Loads the last row from the specified form's QBF result list (QBFLIST property).

Status = Exec_Method( CtrlEntID, "QBFSHOWLAST" )

N/a.

The QBFLAST event status. If this is not null then an error has occurred.

This method triggers the form's QBFLAST event.

The form must have a valid QBF result list active, i.e. the QBFSTATUS property must have a value of " QBFActive".

 // Example – display the last row in the QBF result list//
 
 Status = Exec_Method( @Window, "QBFSHOWLAST" )
 If BLen( Status ) Then
    // Error ...//
 End
 

WINDOW QBFLIST property, WINDOW QBFPOS property, WINDOW QBFSTATUS property, WINDOW QBFSHOWFIRST method, WINDOW QBFSHOWNEXT method, WINDOW QBFSHOWPREV method, WINDOW QBFSHOWTABLE method, WINDOW QBFLAST event.

Loads the next row from the specified form's QBF result list (QBFLIST property).

Status = Exec_Method( CtrlEntID, "QBFSHOWNEXT" )

N/a.

The QBFNEXT event status. If this is not null then an error has occurred.

If the current position is at the end of the QBF result list then it is reset to point at the first row instead.

This method triggers the form's QBFNEXT event.

The form must have a valid QBF result list active, i.e. the QBFSTATUS property must have a value of " QBFActive".

 // Example – display the next row in the QBF result list//
 
 Status = Exec_Method( @Window, "QBFSHOWNEXT" )
 If BLen( Status ) Then
    // Error ...//
 End
 

WINDOW QBFLIST property, WINDOW QBFPOS property, WINDOW QBFSTATUS property, WINDOW QBFSHOWFIRST method, WINDOW QBFSHOWLAST method, WINDOW QBFSHOWPREV method, WINDOW QBFSHOWTABLE method, WINDOW QBFNEXT event.

Loads the previous row from the specified form's QBF result list (QBFLIST property).

Status = Exec_Method( CtrlEntID, "QBFSHOWPREV" )

N/a.

The QBFPREV event status. If this is not null then an error has occurred.

If the current position is at the start of the QBF result list then it is reset to point at the last row instead.

This method triggers the form's QBFPREV event.

The form must have a valid QBF result list active, i.e. the QBFSTATUS property must have a value of " QBFActive".

 // Example – display the previous row in the QBF result list//
 
 Status = Exec_Method( @Window, "QBFSHOWPREV" )
 If BLen( Status ) Then
    // Error ...//
 End
 

WINDOW QBFLIST property, WINDOW QBFPOS property, WINDOW QBFSTATUS property, WINDOW QBFSHOWFIRST method, WINDOW QBFSHOWLAST method, WINDOW QBFSHOWNEXT method, WINDOW QBFSHOWTABLE method, WINDOW QBFPREV event.

Displays the QBF result list in a non-modal dialog box. As the user selects a value in the dialog the corresponding row is loaded in the owning form.

Status = Exec_Method( CtrlEntID, "QBFSHOWTABLE" )

N/a.

The QBFTABLE event status. If this is not null then an error has occurred.

This method triggers the form's QBFTABLE event.

The form must have a valid QBF result list active, i.e. the QBFSTATUS property must have a value of " QBFActive".

 // Example – display the QBF result list//
 
 Status = Exec_Method( @Window, "QBFSHOWTABLE" )
 If BLen( Status ) Then
    // Error ...//
 End
 

WINDOW QBFLIST property, WINDOW QBFPOS property, WINDOW QBFSTATUS property, WINDOW QBFSHOWFIRST method, WINDOW QBFSHOWLAST method, WINDOW QBFSHOWNEXT method, WINDOW QBFPREV event.

Populates controls in the specified form with data from the previously loaded row.

Status = Exec_Method( CtrlEntID, "READPREVROW", ControlList )

Error status results. If this is not null then an error has occurred.

A data-bound form caches row data at the following points:

• When data is written to the database – a copy of the data in the controls is saved.
• When data is loaded into the controls during a read operation. This is optional and only happens If the LOADPREVALWAYS property is TRUE$ : if so a copy of the data loaded into the controls during a READ event is cached (this is always overwritten by data from a write operation of course).

The READPREVROW method uses this cached data to load controls when requested.

Controls bound to key columns are ignored.

This method is intended to mimic the "Alt-C" functionality of found in Advanced Revelation applications.

     
 // Example - Load data from a previous row into the control that currently//
 // has the focus. This sort of functionality would typically be found on a //
 // form's Edit menu.//
 
 CtrlID = Get_Property( @Window, "FOCUS" )
 If BLen( CtrlID ) Then
    ColPos = Get_Property( CtrlID, "POS" )
    If ColPos Then
    // CtrlID is a non-key databound control//
       Status = Exec_Method( @Window, "READPREVROW", CtrlID )
    End
 End
 

WINDOW LOADPREVALWAYS property, WINDOW ROW property, WINDOW READ event, WINDOW WRITE event.

Reads the data into the specified data-bound form and populates the controls.

Status = Exec_Method( CtrlEntID, "READROW", RowID, SuppressWarning )

The READ event status. If this is not null then an error has occurred or the user has cancelled the process.

This method triggers the form's READ event.

     
 // Example - Read a row into the current form unconditionally//
 
 RowID = "AS123*EF"
 
 ReadStatus = Exec_Method( @Window, "READROW", RowID, TRUE$ )
 If BLen( ReadStatus ) Then
    // Error or cancelled...   //
 End
 

WINDOW ID property, WINDOW ROW property, WINDOW SAVEWARN property, WINDOW WRITEROW method, WINDOW READ event.

Scrolls the contents of the specified form’s client area.

SuccessFlag = Exec_Method( CtrlEntID, "SCROLL", XShift, YShift )

TRUE$ if the client area was scrolled successfully, or FALSE$ otherwise.

The XShift and YShift values are interpreted as DIPs or PX based on the form's SCALEUNITS property.

The SCROLL method is implemented internally using the ScrollWindow Windows API function. More information on this function can be found on the Microsoft website.

     
 // Example – scroll the form’s contents by 100 DIPs vertically//
 
 Call Exec_Method( @Window, "SCROLL", 0, 100 )
 

N/a.

Displays a form using the specified effect.

Call Exec_Method( CtrlEntID, "SHOW", ShowEffect )

N/a.

This method does not apply when used with an MDI Child form.

Equated constants for the SHOWEFFECT property value can be found in the PS_WINDOW_EQUATES insert record.

     
 // Example – shown the current form using a "Slide Down" effect//
 $Insert PS_Window_Equates
 
 Call Exec_Method( @Window, "SHOW", PS_SHE_SLIDE_DOWN$ )
 

WINDOW HIDEEFFECT property, WINDOW SHOWEFFECT property, WINDOW TRANSLUCENCY property, WINDOW VISIBLE property, WINDOW HIDE method.

Displays a dialog box using the specified form as the owner.

RetVal = Exec_Method( CtrlEntID, "SHOWDIALOG", DialogName, CreateParam, |

Options, AsyncParams )

If the dialog box is executed in synchronous mode the return value is the data passed back from the CLOSEDIALOG method (or an End_Dialog function call).

If the dialog is executed in asynchronous mode the return value will be the instance ID of the created dialog box. In this case the data passed back from an End_Dialog call will passed as an argument to the owner form's ENDDIALOG event.

If an error occurs the return value will be null.

This method is a wrapper around the Dialog_Box stored procedure. Please see the Dialog_Box stored procedure description for more details.

     
 // Example - Display a dialog box in synchronous mode using the //
 // current form as the owner and passing it the contents of a //
 // variable called CurrName as the CreateParam.//
 
 NewName = Exec_Method( @Window, "SHOWDIALOG", "MY_DIALOG_BOX", CurrName )
 
 If BLen( NewName ) Then
    // The user entered a new name so process it//
    Call Do_Something_With_This_Name( NewName )
 End
 

WINDOW CLOSEDIALOG method, WINDOW STARTFORM method, Dialog_Box stored procedure.

Displays an Index Lookup dialog box using the specified form as the owner.

RetVal = Exec_Method( CtrlEntID, "SHOWINDEXLOOKUP", IndexedTable, |

SearchColumns, DisplayColumns, SelMode )

The IXLOOKUP event status. If this is not null then an error has occurred or the user has cancelled the process.

This method triggers the form's IXLOOKUP event.

     
 // Example - launch the index lookup dialog using the current window as the owner,//
 // and put the returned key into the EDL_CUST_ID control//
 
 TableName   = "CUSTOMERS"
 SearchCols  = "SURNAME" : @Fm : "STREET" : @Fm : "CITY"
 DisplayCols = "FULL_NAME" : @Fm : "FULL_ADDRESS"
 
 SelMode     = "SINGLE"  
 SelMode<2>  = @Window : ".EDL_CUST_ID"
 SelMode<3>  = "TEXT"
 
 Status  = Exec_Method( @Window, "SHOWINDEXLOOKUP", |
                        TableName,                  |
                        SearchCols,                 |
                        DisplayCols,                |
                        SelMode )
    

WINDOW STARTDIALOG method, WINDOW SHOWMESSAGE method, WINDOW SHOWPOPUP method, WINDOW IXLOOKUP event.

Shows the menubar for the specified form.

Call Exec_Method( CtrlEntID, "SHOWMENUBAR" )

N/a.

N/a.

N/a.

     
 // Example – show the menubar for the current form//
 
 Call Exec_Method( @Window, "SHOWMENUBAR" )
 

MENUBAR object, WINDOW HIDEMENUBAR method

Displays a message box, using the specified form as the parent.

MessageValue = Exec_Method( CtrlEntID, "SHOWMESSAGE", MessageStruct, |

MessageName )

The value as specified by the message definition.

This method is basically a wrapper around the Msg stored procedure. Please see the documentation on Msg for more information.

SYSTEM SHOWMESSAGE method, Msg stored procedure.

 // Example - display a simple  message//
 
 $Insert Msg_Equates
 MsgStruct            = ""
 MsgStruct<MTEXT$>    = "WINDOW SHOWMESSAGE method example "
 MsgStruct<MICON$>    = "*"
 MsgStruct<MJUST$>    = "C"
 MsgStruct<MCAPTION$> = "Owned Message Box" 
 
 MsgVal = Exec_Method( CtrlEntID, "SHOWMESSAGE", MsgStruct )
 
 // Example display a  message with an entity name//
 MsgVal = Exec_Method( CtrlEntID, "SHOWMESSAGE", "", "OI_ABOUT" )
 

SYSTEM SHOWMESSAGE method, WINDOW STARTDIALOG method, WINDOW SHOWINDEXLOOKUP method, WINDOW SHOWPOPUP method, Msg stored procedure.

Displays a popup box using the specified form as the owner.

RetVal = Exec_Method( CtrlEntID, "SHOWPOPUP", PopupStruct,PopupName )

The value as defined by the popup structure. See the Popup stored procedure for more details.

This method is a wrapper around the Popup stored procedure. Please see the Popup stored procedure description and the POPUP_EQUATES insert record for more details.

     
 // Example - Display the ASCII_CHART popup box.//
 
 PopupVal = Exec_Method( @Window, "SHOWPOPUP", "", "ASCII_CHART" )
    

SYSTEM SHOWPOPUP method, WINDOW STARTDIALOG method, WINDOW SHOWINDEXLOOKUP method, WINDOW SHOWMESSAGE method, Popup stored procedure.

Executes a new form, using the specified form as the owner.

RetVal = Exec_Method( CtrlEntID, "STARTFORM", FormName, CreateParam )

The instance name of the newly created form, or null if the form cannot be started. The instance ID is usually the same as the passed FormName, but if the form is flagged as multi-instance then the PS can append a unique number (delimited with an "*" character) to the returned ID to ensure that there are no conflicts with existing forms.

This method is a wrapper around the Start_Window stored procedure. Please see the Start_Window stored procedure description for more details.

     
 // Example - Display a form using the current form as the owner and passing//
 // it the contents of a variable called SearchVar as the CreateParam.//
 
 FormID = Exec_Method( @Window, "STARTFORM", "QUICK_SEARCH", SearchVar )
 
 If BLen( FormID ) Else
    // Error!....//
 End
 

SYSTEM STARTFORM method, WINDOW SHOWDIALOG method, WINDOW STARTMDICHILDFORM method, Start_Window stored procedure.

Executes a new MDI child form for the specified MDI Frame form.

RetVal = Exec_Method( CtrlEntID, "STARTMDICHILDFORM", FormName, CreateParam |

AppearanceMode, InitX, InitY )

The Instance ID of the newly created form is returned if successful. Null is returned if the form fails to start. The instance ID is usually the same as the passed FormName, but if the form is flagged as multi-instance then the PS can append a unique number (delimited with an "*" character) to the returned ID to ensure that there are no conflicts with existing forms.

This method is only supported for MDI Frame forms.

This method is a wrapper around the Start_MDIChild stored procedure. Please see the Start_ MDIChild stored procedure description for more details.

     
 // Example - Start a maximized MDI Child form in an MDI Frame form, passing //
 //           an ID to load in the child's CREATE event.//
 
 $Insert MSWin_ShowWindow_Equates
 
 CustID  = "A12345"
 ChildID = Exec_Method( @Window, "STARTMDICHILDFORM", 
  "CUSTOMER_ENTRY",  |
  CustID, |
                         SW_SHOWMAXIMIZED$, "", "" )
 

WINDOW MDIFRAME property, SYSTEM STARTFORM method, WINDOW SHOWDIALOG method, WINDOW STARTMDICHILDFORM method, Start_MDIChild stored procedure.

Displays a dropdown menu for a top-level menu bar item on the specified form. The menu is created and displayed from the passed menu item structure.

Status = Exec_Method( CtrlEntID, "TRACKDROPDOWNMENU", MenuItemID, |

MenuStruct )

TRUE$ if the menu is created and displayed successfully, or FALSE$ otherwise.

This method is called by the DROPDOWNMENU event to display the dropdown menu associated with a top-level menu item.

This is considered a low-level method. It is better to make any adjustments to the menu structure in the DROPDOWN menu event handler instead.

Equates constants for working with menu structures can be found in the PS_MENU_EQUATES insert record. Equated constants for the "TPM_" values can be found in the MSWIN_MENU_EQUATES insert record.

 // Display a droopdown menu for the current form's "EXAMPLE" top-level menu item //
 // with two items and a separator//
 
 $Insert PS_Menu_Equates
 $insert MSWin_Menu_Equates
 
 MenuStruct = ""
 MenuID     = @Window : ".MENU.EXAMPLE"
 
 ItemStruct = ""
 ItemStruct<0,0,MENUPOS_TYPE$> = MENUTYPE_ITEM$
 ItemStruct<0,0,MENUPOS_END$>  = FALSE$
 ItemStruct<0,0,MENUPOS_NAME$> = MenuID : ".OPEN_SESAME"
 ItemStruct<0.0,MENUPOS_TEXT$> = "Open Sesame"
 
 MenuStruct<0,-1> = ItemStruct
 
 ItemStruct = ""
 ItemStruct<0,0,MENUPOS_TYPE$> = MENUTYPE_SEPARATOR$$
 ItemStruct<0,0,MENUPOS_END$   = FALSE$
 ItemStruct<0.0,MENUPOS_NAME$  = MenuID : ".SEP101"
 ItemStruct<0.0,MENUPOS_TEXT$> = "SEP101"
 
 MenuStruct<0,-1> = ItemStruct
 
 ItemStruct = ""
 ItemStruct<0,0,MENUPOS_TYPE$> = MENUTYPE_ITEM$
 ItemStruct<0,0,MENUPOS_END$>  = TRUE$
 ItemStruct<0,0,MENUPOS_NAME$> = MenuID : ".CLOSE_SESAME"
 ItemStruct<0.0,MENUPOS_TEXT$> = "Close Sesame"
 
 MenuStruct<0,-1> = ItemStruct
  
 IsOK = Exec_Method( @Window, "TRACKDROPDOWNMENU", MenuID, MenuStruct )
 

Common GUI MENU event, WINDOW DROPDOWNMENU event.

Updates the data associated with the primary table of a data-bound form without updating data-bound controls.

SuccessFlag = Exec_Method( CtrlEntID, "UPDATEROW", NewRow )

The TRUE$ if the row was updated successfully, or FALSE$ otherwise.

This method is essentially the same as setting the ROW property except that the controls are not updated. This can be useful when updating data columns that are not bound to a control without unnecessarily re-populating those that are, such as just before a WRITE operation for example. SAVEWARN will be set to TRUE$.

     
// Example - Update column <20> of the current row without reloading//
//           any data-bound controls//

$Insert Logical

RowData     = Get_Property( @Window, "ROW" )
RowData<20> = TRUE$ 

Call Exec_Method( @Window, "UPDATEROW", RowData )
 

WINDOW ROW property, WINDOW ID property, WINDOW WRITE event.

Writes the data contains in the specified data-bound form to the database.

Status = Exec_Method( CtrlEntID, "READROW", RowID )

The WRITE event status. If this is not null then an error has occurred or the user has cancelled the process.

This method triggers the form's WRITE event.

     
 // Example - Write the data in the current form using a new ID//   

 RowID = "AS123*EF"
 
 WriteStatus = Exec_Method( @Window, "WRTEROW", RowID )
 If BLen( WriteStatus ) Then
    // Error or cancelled...   //
 End
 

WINDOW CLEARONWRITE property, WINDOW ID property, WINDOW ROW property, WINDOW READROW method, WINDOW, CLEAR event, WINDOW WRITE event.

The WINDOW object supports the following events:

The following Common GUI Object events are also supported:

• BUTTONDOWN
• BUTTONUP
• CONTEXTMENU
• DROPFILES
• HELP
• HSCROLL
• INITCONTEXTMENU
• LOSTCAPTURE
• MOUSEMOVE
• NOTES
• OMNIEVENT
• OPTIONS
• SYSMSG
• TIMER
• VSCROLL
• WINMSG

The following Container Object API events are also supported:

• PAGECHANGED
• SIZE

Occurs when a form is activated.

bForward = ACTIVATED( CtrlEntID, CtrlClassID )

TRUE$ or FALSE$. If FALSE$, the program execution returns to the calling procedure. If TRUE$, the event processing goes to the next level.

The system event handler for ACTIVATED raises a FORMSTATECHANGED event.

For more information on this event please refer to the Windows documentation regarding WM_ACTIVATE window message on the Microsoft website.

Function ACTIVATED( CtrlEntID, CtrlClassID )

Example - ACTIVATED event for an MDI child form to let it parent frame

 // know that is has been activated so it may set its menu items correctly//
 
 MDIFrame = Get_Property( CtrlEntID, "MDIFRAME" )
 
 // Assume that the frame uses an OMNIEVENT handler to respond to the//
 // child being activated with a message of "CHILD_ACTIVATED" and the//
 // child ID as the first parameter//
 
 EvStatus = Exec_Method( MDIFrame, "SENDEVENT", "OMNIEVENT", |
                         "CHILD_ACTIVATED", CtrlEntID )
    

Return TRUE$

Common GUI FOCUS property, SYSTEM FOCUS property, WINDOW ACTIVE property, WINDOW FOCUS property, WINDOW FORMSTATECHANGED event, WINDOW INACTIVATED event.

Arranges all minimized MDI Child forms for an MDI frame form.

bForward = ARRANGEICONS( CtrlEntID, CtrlClassID )

TRUE$ or FALSE$. If FALSE$, the program execution returns to the calling procedure. If TRUE$, the event processing goes to the next level.

The system-level event handler for this event calls the MDIICONARRANGE method to perform the arrange operation, and because of this it has been deprecated in favor of that method. It is implemented only for backwards compatibility with earlier versions of OpenInsight.

(Note that this event is not a "true" event as such as it is never triggered by the PS, it can only be "manually" triggered by the developer in an application (typically from an MDI Window menu item) – it is actually a method masquerading as an event).

Please see the documentation for the WM_MDIICONARRANGE message on the Microsoft website for more details.

N/a.

WINDOW MDIICONARRANGE method.

Arranges all MDI Child forms into a cascading layout for an MDI frame form.

bForward = CASCADE( CtrlEntID, CtrlClassID )

TRUE$ or FALSE$. If FALSE$, the program execution returns to the calling procedure. If TRUE$, the event processing goes to the next level.

The system-level event handler for this event calls the MDICASCADE method to perform the cascade operation, and because of this it has been deprecated in favor of that method. It is implemented only for backwards compatibility with earlier versions of OpenInsight.

(Note that this event is not a "true" event as such as it is never triggered by the PS, it can only be "manually" triggered by the developer in an application (typically from an MDI Window menu item) – it is actually a method masquerading as an event).

Please see the documentation for the WM_MDICASCADE message on the Microsoft website for more details.

N/a.

WINDOW MDICASCADE method.

Occurs when data is cleared from a data-bound form.

bForward = CLEAR( CtrlEntID, CtrlClassID, bSaveKey, bSuppressWarning |

bMaintainFocus )

TRUE$ or FALSE$. If FALSE$, the program execution returns to the calling procedure. If TRUE$, the event processing goes to the next level.

The CLEAR event has a system-level handler that performs the following tasks:

• If the form is cleared while browsing a QBF result list, then a QBFNEXT event is raised to move to the next record instead.
• If the form is cleared while the QBFSTATUS property is QBFInitialize then a QBFCLOSE event is raised to clear the form instead.

If neither of these conditions apply the normal CLEAR process is followed:

• If the form's SUPPRESSSAVEWARN property is FALSE$ and the bSuppressWarning parameter is FALSE$ then:
  • Update the form's SAVEWARN property if data in the currently focused control has changed.
  • Check the SAVEWARN property and warns the user of any unsaved changes if the bSuppressWarning flag is FALSE allowing the operation to be cancelled. If so, then the clear operation is stopped here.
• Reset the form's SAVEWARN property to FALSE$
• Unlock any data-rows locked by the form.
• If bSaveKey is FALSE$ then clear data in the data-bound key controls
• Clear the contents of the data-bound controls.
• Reset the form's NEWROW property to FALSE$
• If bMaintainFocus is FALSE$ move the focus to the first control in the form's tab order.

A CLEAR event will be triggered by the system in the following circumstances:

• From a READ event, if the read operation is cancelled or fails.
• From a WRITE event, if the CLEARONWRITE property is TRUE$.
• From a DELETE event.

Applications needing to execute a clear operation programmatically should use the WINDOW CLEARROW method rather than using the Send_Event stored procedure to invoke a CLEAR event directly (as was the case in previous versions of OpenInsight).

Function CLEAR( CtrlEntID, CtrlClassID, bSaveKey, bSuppressWarning, bMaintainFocus )

Example - CLEAR event script that removes some information from a STATIC

 // control called TXT_INFO that is not data-bound.//
 $Insert RTI_SSP_Equates
 
 // First let the system event handler perform the clear in case the user cancels it//
 Call Set_EventStatus( SETSTAT_OK$ )
 Call Forward_Event( bSaveKey, bSuppressWarning, bMaintainFocus )
 If Get_EventStatus() Then
    // Assume cancelled or error//
    Null
 End Else
    Call Set_Property_Only( @Window : ".TXT_INFO", "TEXT", "" )
 End
 
 // Return FALSE$ to stop the event chain as we've already forwarded to the//
 // system CLEAR event handler above.//
 

Return FALSE$

WINDOW CLEARROW method, WINDOW READ event, WINDOW SYSMSG event, WINDOW WRITE event.

Occurs when a form is being closed.

bForward = CLOSE( CtrlEntID, CtrlClassID, CancelFlag, CloseFlags )

TRUE$ or FALSE$. If FALSE$, the program execution returns to the calling procedure. If TRUE$, the event processing goes to the next level.

The system-level CLOSE event handler performs the following tasks:

• If the suppress SAVEWARN flag is not set (or the form's SUPPRESSSAVEWARN property is FALSE$) then:
  • Update the form's SAVEWARN property if data in the currently focused control has changed.
  • Check the SAVEWARN property and warn the user of any unsaved changes, giving them the opportunity to save, ignore or cancel:
    • Choosing save performs a write operation and proceeds to close the form if successful, otherwise the close operation is stopped.
    • Choosing cancel stops the form from closing.
• The CLOSE quick event handler is executed (if defined) and the event status checked – if it returns anything other than FALSE$ the operation is cancelled.
• Any forms owned by the current form are closed. If any owned forms cannot be closed the entire close operation is cancelled.
• If the current form is an MDI Frame form, then any MDI Child forms are closed. If any child forms cannot be closed the entire close operation is cancelled.
• All database locks held by the form are released.
• The form is removed from screen via the HIDE method.
• The form is terminated via the End_Window stored procedure.

Care should be taken when closing a form from an event that is raised from one of the form's own child controls. In this case it is always better to set the CloseAsync flag in the CLOSE method so that the current event has chance to finish executing before the form is destroyed.

Applications needing to execute a close operation programmatically should use the WINDOW CLOSE method rather than using the Send_Event or Post_Event stored procedures to invoke a CLOSE event directly (as was the case in previous versions of OpenInsight).

Function CLOSE( CtrlEntID, CtrlClassID, CancelFlag, CloseFlags )

Example - CLOSE event script - let the system handler execute via a call

 // to formward_event, and cleanup resources if the form was closed.//
 $Insert RTI_SSP_Equates
 
 Call Set_EventStatus( STESTAT_OK$ )
 Call Forward_Event( CancelFlag, CloseFlags )
 If Get_EventStatus() Then
    // Form wasn't closed//
    Return FALSE$
 End
 
 // Final check - just in case someone forgot to set the EventStatus//
 If Get_Property( CtrlEntID, "HANDLE" ) Else
    // Form wasn't closed//
    Return FALSE$
 End
 
 // Now be very careful, as the form no longer exists, so try not to //
 // reference it from this point onwards (especially any synthetic //
 // properties)//
 
 GoSub CleanAllTheThings
 
 // Return FALSE$ to stop the event chain as we've already forwarded to the//
 // system CLOSE event handler above.//
 

Return FALSE$

WINDOW SAVEWARN property, WINDOW CLOSE method, WINDOW HIDE method, End_Window stored procedure.

Occurs when a form is created.

bForward = CREATE( CtrlEntID, CtrlClassID, CreateParam )

TRUE$ or FALSE$. If FALSE$, the program execution returns to the calling procedure. If TRUE$, the event processing goes to the next level.

There is no system level event handler for CREATE.

Function CREATE( CtrlEntID, CtrlClassID, CreateParam )

Example CREATE event. Assume this is a non-visible data bound form and we have

 // been passed the key to load in the CreateParam argument//
 
 CloseForm = FALSE$
 If BLen( CreateParam ) Then
    EvStatus = Exec_Method( @Window, "READROW", CreateParam )
    If BLen( EvStatus ) Then
       CloseForm = TRUE$ ; // Read Failed - close the form//
    End
 End
 
 If CloseForm Then
    Call Exec_Method( @Window, "CLOSE", TRUE$, TRUE$ ) ); // Async//
 End Else
    Call Exec_Method( @Window, "SHOW" ); // Loaded OK - show the form//
 End
 

Return Not( CloseForm )

SYSTEM SHOWDIALOG method, SYSTEM STARTFORM method, WINDOW SHOWDIALOG method, WINDOW STARTFORM method, WINDOW STARTMDICHILDFORM method, Dialog_Box stored procedure, Start_MDIChild stored procedure, Start_Window stored procedure.

Occurs when the user double-clicks the mouse button on a form.

bForward = DBLCLK( CtrlEntID, CtrlClassID, CtrlKey, ShiftKey, MouseButton )

TRUE$ or FALSE$. If FALSE$, the program execution returns to the calling procedure. If TRUE$, the event processing goes to the next level.

There is no system-level event handler for DBLCLK.

Function DBLCLK( CtrlEntID, CtrlClassID, CtrlKey, ShiftKey, MouseButton )

Example DBLCLK event. If the Ctrl key is down then load a non-modal, owned

 // child form//
 
 If CtrlKey Then
    Call Exec_Method( @Window, "STARTFORM", "MY_INFO_FORM" )
 End
    

Return TRUE$

Common GUI BUTTONDOWN event, Common GUI BUTTONUP Event, Common GUI LOSTCAPTURE event, Common GUI MOUSEMOVE event.

Occurs when the data row loaded into a data-bound form is deleted from the database.

bForward = DELETE( CtrlEntID, CtrlClassID, bSuppressWarning )

TRUE$ or FALSE$. If FALSE$, the program execution returns to the calling procedure. If TRUE$, the event processing goes to the next level.

The DELETE event has a system-level handler that performs the following tasks:

• Checks the see if all loaded data rows are locked. If not, the user is warned and the delete operation is aborted.
• If the bSuppressWarning parameter is FALSE$ the form displays a message warning the user that data is about to be deleted, giving them an opportunity to cancel the process.
• The data row is deleted from the database.
• The SAVEWARN property is reset to FALSE$.
• If the row was deleted while browsing a QBF result list, the list is updated and the next item in the list loaded, otherwise a CLEAR event is raised to reset the form's data-bound controls to their default state.

A DELETE event is never triggered by the system – it is only triggered by user action or developer code.

Applications needing to execute a delete operation programmatically should use the WINDOW DELETEROW method rather than using the Send_Event stored procedure to invoke a DELETE event directly (as was the case in previous versions of OpenInsight).

Function DELETE( CtrlEntID, CtrlClassID, bSuppressWarning )

Example - DELETE event script that checks to see if the user has rights to

 // perform the delete//
 $Insert RTI_SSP_Equates
 $Insert EvErrors
 
 IsOK = TRUE$
 GoSub IsTheUserOKToDeleteRows ; // whatever//
 If IsOK Else
    // Failed the check - warn the user and stop here//
    Call Exec_Method( @Window, "SHOWMESSAGE", "What do you think you are doing Dave?" )
    Call Set_EventStatus( SETSTAT_ERR$, EV_VALIDERR$ )
    Return FALSE$
 End
 
 // Assume single table form.//
 TableID = Get_Property( @Window, "TABLE" )
 RowID   = Get_Property( @Window, "ID" )
 
 // Now let the system event handler perform the DELETE in case we have a problem//
 Call Set_EventStatus( SETSTAT_OK$ )
 Call Forward_Event( bSuppressWarning )
 If Get_EventStatus() Then
    // Assume error or cancelled//
    Null
 End Else
    // Update the audit log...//
    Call Update_Some_Audit Log( @UserName : " deleted" : TableID : " " : RowID )
  End
 
 // Return FALSE$ to stop the event chain as we've already forwarded to the//
 // system DELETE event handler above.//
 

Return FALSE$

WINDOW SAVEWARN property, WINDOW CLEARROW method, WINDOW DELETEROW method, WINDOW CLEAR event, WINDOW SYSMSG event.

Occurs when a top-level item on a form's menu bar is selected and gives a chance for the application to modify the menu before it is displayed.

bForward = DROPDOWNMENU( CtrlEntID, CtrlClassID, menuID, menuStruct )

TRUE$ or FALSE$. If FALSE$, the program execution returns to the calling procedure. If TRUE$, the event processing goes to the next level.

The system-level event handler for DROPDOWNMENU performs the following tasks:

• The DROPDOWNMENU quick event handler is executed (if defined) and the event status checked – if it returns anything other than FALSE$ the operation is cancelled.
• If the menu item being selected is the "Window" item on an MDI Frame form then the details of the first ten MDI child forms are appended to the MenuStruct array – this is so they may be activated from the dropdown menu. If there are more than ten then a "More…" item is also appended which will trigger an "MDISELECT" event when selected.
• The dropdown menu is displayed via the TRACKDROPDOWNMENU method.

Function DROPDOWNMENU( CtrlEntID, CtrlClassID, menuID, menuStruct )

Example DROPDOWNMENU event code - check to see which clipboard items should

 // be enabled if this is the "Edit" menu item//
 $Insert PS_Menu_Equates
 $insert PS_Equates
 
 Begin Case
    Case ( MenuID  == @Window : ".MENU.EDIT" )
       // Get the current focus and it's EditState//
       FocusID   = Get_Property( "SYSTEM", "FOCUS" )
       EditState = Get_Property( FocusID, "EDITSTATEFLAGS" )
 
       xCount = FieldCount( MenuStruct, @Vm )
       For X = 5 to XCount
          If ( MenuStruct<0,X>[1,1] == "@" ) Then
             Null ; // Ignore - it's an imagelist header//
          End Else
             If ( MenuStruct<0,X,MENUPOS_TYPE$> == MENUTYPE_ITEM$ ) Then
                ItemName    = MenuStruct<0,X,MENUPOS_NAME$>[-1,"B."]
                DisableItem = FALSE$
                Begin Case
                   Case ( ItemName = "UNDO" )
                      DisableItem = ( EditState<PS_ESF_CANUNDO$> //!= TRUE$ )//
                   Case ( ItemName = "CUT" )
                      DisableItem = ( EditState<PS_ESF_CANCUT$> //!= TRUE$ )//
                   Case ( ItemName = "COPY" )
                      DisableItem = ( EditState<PS_ESF_CANCOPY$> //!= TRUE$ )//
                   Case ( ItemName = "PASTE" )
                      DisableItem = ( EditState<PS_ESF_CANPASTE$> //!= TRUE$ )//
                End Case
                
                If ( DisableItem ) Then
                   MenuStruct<0,X,MENUPOS_GREY$> = TRUE$
                End
             End
          End
       Next
       
 End Case
 

Return TRUE$

WINDOW TRACKDROPDOWNMENU method, Common GUI CONTEXTMENU event, WINDOW MDISELECT event.

Occurs when an asynchronous dialog box returns a value to its owner form.

bForward = ENDDIALOG( CtrlEntID, CtrlClassID, DialogID, DialogValue, AsyncID )

TRUE$ or FALSE$. If FALSE$, the program execution returns to the calling procedure. If TRUE$, the event processing goes to the next level.

There is no system-level event handler for ENDDIALOG.

Function ENDDIALOG( CtrlEntID, CtrlClassID, DialogID, DialogValue, AsyncID )

Example ENDDIALOG event script - look for a return value from the

 // GET_CLIENT_DATA dialog box and assume it was passed the name of //
 // the control to return the data to://
 
 Begin Case
    Case ( DialogID == "GET_CLIENT_DATA" )
       Call Set_Property_Only( AsyncID, "DEFPROP", DialogValue )
 End Case
 

Return TRUE$

WINDOW SHOWDIALOG method, WINDOW SHOWPOPUP method, Dialog_Box stored procedure, End_Dialog stored procedure.

Occurs when the “state” of a form changes. The term state refers to attributes that can affect the visual state of the form and the enabled state of its controls, such as being activated, reading data, clearing data etc. These actions usually require common UI menu items and buttons to be updated, for example Save, Clear and Delete menu items and buttons that perform the same actions.

This event is raised from the following system event handlers:

• ACTIVATED (for MDI Child forms)
• CLEAR, READ and WRITE events
• CLOSE (for MDI Child forms)
• QBF events

bForward = FORMSTATECHANGED( CtrlEntID, CtrlClassID, EventSource, FormState )

TRUE$ or FALSE$. If FALSE$, the program execution returns to the calling procedure. If TRUE$, the event processing goes to the next level.

This event is only raised if the form’s ALLOWFORMSTATEEVENTS property is TRUE$.

The system-level event handler for FORMSTATECHANGED performs the following tasks:

• Builds the default FormState array based on the state of the row data loaded into the form.
• Executes the FORMSTATECHANGED quick event handler (if defined) and checks the event status – if it returns anything other than FALSE$ the operation is cancelled.
• Sets the ENABLED state for a default set of items based on the flags in the FormState array parameter.
• If the form is an MDI Child then an MDICHILDSTATECHANGED event is raised for the parent MDI frame.

The default list of items affected by the form state is:

• MENU.FILE.SAVE
• MENU.FILE.SAVE_F9
• MENU.FILE.SAVE_ROW
• MENU.FILE.SAVE_AS
• MENU.FILE.CLEAR
• MENU.FILE.CLEAR_ROW
• MENU.FILE.DELETE
• MENU.FILE.DELETE_ROW
• MENU.FILE.PRINT
• MENU.FILE.PRINT_PREVIEW
• MENU.FILE.CLOSE
• MENU.EDIT.LOAD_PREVIOUS_DATA
• MENU.EDIT.LOAD_PREVIOUS_ROW
• MENU.QBF.INITIALIZE
• MENU.QBF.EXECUTE
• MENU.QBF.LOAD_FROM_EXTERNAL_LIST
• MENU.QBF.LOADLIST
• MENU.QBF.GETQUERY
• MENU.QBF.NEXT
• MENU.QBF.PREVIOUS
• MENU.QBF.FIRST
• MENU.QBF.LAST
• MENU.QBF.ABSOLUTE
• MENU.QBF.GOTO_ID
• MENU.QBF.TABLE
• MENU.QBF.CLOSE

Equates for use with the FORMSTATECHANGED event can be found in the RTI_FORMSTATE_EQUATES insert record.

Function FORMSTATECHANGED( CtrlEntID, CtrlClassID, EventSource, FormState )

 // Example - Set the state of some buttons based on the state of the form, and//
 //           set the Delete flag to FALSE$ if the user is not an administrator//
 //            (This assumes that this code runs _before_ the system event//
 //            handler!)//
 
 $Insert RTI_FormState_Equates
 $Insert Logical
 
 // Check the user//
 If ( @Admin == 0 ) Then
    // Not an Admin - no deleting//
    FormState<FormState<FSTATE_POS_DELETE$> = FALSE$
 End
 
 ObjxArray =        @Window : ".BTN_SAVE"
 PropArray =        "ENABLED"
 DataArray =        FormState<FSTATE_POS_SAVE$>
 
 ObjxArray := @Rm : @Window : ".BTN_CLEAR"
 PropArray := @Rm : "ENABLED"
 DataArray := @Rm : FormState<FSTATE_POS_CLEAR$>
 
 ObjxArray := @Rm : @Window : ".BTN_DELETE"
 PropArray := @Rm : "ENABLED"
 DataArray := @Rm : FormState<FSTATE_POS_DELETE$>
 
 Call Set_Property_Only( ObjxArray, PropArray, DataArray )
    

Return TRUE$

WINDOW ALLOWFORMSTATEEVENTS property, WINDOW ACTIVATED event, WINDOW CLOSE event, WINDOW CLEAR event, WINDOW MDICHILDSTATECHANGED event, WINDOW QBFABS event, WINDOW QBFCLOSE event, WINDOW QBFINIT event, WINDOW QBFFIRST event, WINDOW QBFLAST event, WINDOW QBFLOADID event, WINDOW QBFNEXT event, WINDOW QBFPREV event, WINDOW QBFQUERY event, WINDOW READ event, WINDOW WRITE event.

Occurs when a form becomes inactive.

bForward = INACTIVATED( CtrlEntID, CtrlClassID )

TRUE$ or FALSE$. If FALSE$, the program execution returns to the calling procedure. If TRUE$, the event processing goes to the next level.

There is no system-level event handler for INACTIVATED.

For more information on this event please refer to the Windows documentation regarding WM_ACTIVATE window message on the Microsoft website.

Function INACTIVATED( CtrlEntID, CtrlClassID )

 // Example - INACTIVATED event for an MDI child form to let it parent frame//
 // know that is has lost the active status so it may set its menu items correctly//
 
 MDIFrame = Get_Property( @Window, "MDIFRAME" )
 
 // Assume that the frame uses an OMNIEVENT handler to respond to the//
 // child being deactivated with a message of "CHILD_INACTIVATED" and the//
 // child ID as the first parameter//
 
 EvStatus = Exec_Method( MDIFrame, "SENDEVENT", "OMNIEVENT", |
                         "CHILD_INACTIVATED", @Window )
    

Return TRUE$

Common GUI FOCUS property, SYSTEM FOCUS property, WINDOW ACTIVE property, WINDOW FOCUS property, WINDOW ACTIVATED event.

Occurs when a form shows an Index Lookup dialog box.

bForward = INDEXLOOKUP( CtrlEntID, CtrlClassID, IndexedTable, SearchColumns,

DisplayColumns, SelMode )

TRUE$ or FALSE$. If FALSE$, the program execution returns to the calling procedure. If TRUE$, the event processing goes to the next level.

The system-level IXLOOKUP event handler performs the following tasks:

• Parses and verifies the parameters passed to the event.
• Constructs a dialog box to display the search columns.
• Constructs a results popup to allow the user to select one or more rows from the filtered search data.
• Returns the selected rows to the specified control or the form's QBF result list.

N/a.

WINDOW QBFLIST property, WINDOW SHOWINDEXLOOKUP method.

Occurs for an MDI Frame form when the “state” of an MDI Child form changes. The term state refers to attributes that can affect the visual state of the form and the enabled state of its controls, such as being activated, reading data, clearing data etc. These actions usually require common UI menu items and buttons to be updated, for example Save, Clear and Delete menu items and buttons that perform the same actions.

This event is raised from an MDI Child form’s FORMSTATECHANGED event.

bForward = MDICHILDSTATECHANGED( CtrlEntID, CtrlClassID, EventSource, |

FormState )

TRUE$ or FALSE$. If FALSE$, the program execution returns to the calling procedure. If TRUE$, the event processing goes to the next level.

This event is only raised if the MDI Child form’s ALLOWFORMSTATEEVENTS property is TRUE$.

The system-level event handler for MDICHILDSTATECHANGED performs the following tasks:

• If the EventSource is a CLOSE event and the last MDI Child form is being closed the flags in the FormState array are all set to FALSE$
• Executes the MDICHILDSTATECHANGED quick event handler (if defined) and checks the event status – if it returns anything other than FALSE$ the operation is cancelled.
• Sets the ENABLED state for a default set of items based on the flags in the FormState array parameter.

The list of items affected by the default form state handler is:

• MENU.FILE.SAVE
• MENU.FILE.SAVE_F9
• MENU.FILE.SAVE_ROW
• MENU.FILE.SAVE_AS
• MENU.FILE.CLEAR
• MENU.FILE.CLEAR_ROW
• MENU.FILE.DELETE
• MENU.FILE.DELETE_ROW
• MENU.FILE.PRINT
• MENU.FILE.PRINT_PREVIEW
• MENU.FILE.CLOSE
• MENU.EDIT.LOAD_PREVIOUS_DATA
• MENU.EDIT.LOAD_PREVIOUS_ROW
• MENU.QBF.INITIALIZE
• MENU.QBF.EXECUTE
• MENU.QBF.LOAD_FROM_EXTERNAL_LIST
• MENU.QBF.LOADLIST
• MENU.QBF.GETQUERY
• MENU.QBF.NEXT
• MENU.QBF.PREVIOUS
• MENU.QBF.FIRST
• MENU.QBF.LAST
• MENU.QBF.ABSOLUTE
• MENU.QBF.GOTO_ID
• MENU.QBF.TABLE
• MENU.QBF.CLOSE

Equates for use with the MDICHILDSTATECHANGED event can be found in the RTI_FORMSTATE_EQUATES insert record.

Function MDICHILDSTATECHANGED( CtrlEntID, CtrlClassID, EventSource, FormState )

 // Example - Set the state of some buttons based on the state of the child form//
 
 $Insert RTI_FormState_Equates
 $Insert Logical
 
 ObjxArray =        @Window : ".BTN_SAVE"
 PropArray =        "ENABLED"
 DataArray =        FormState<FSTATE_POS_SAVE$>
 
 ObjxArray := @Rm : @Window : ".BTN_CLEAR"
 PropArray := @Rm : "ENABLED"
 DataArray := @Rm : FormState<FSTATE_POS_CLEAR$>
 
 ObjxArray := @Rm : @Window : ".BTN_DELETE"
 PropArray := @Rm : "ENABLED"
 DataArray := @Rm : FormState<FSTATE_POS_DELETE$>
 
 Call Set_Property_Only( ObjxArray, PropArray, DataArray )
    

Return TRUE$

Common GUI ENABLED property, WINDOW ALLOWFORMSTATEEVENTS property, WINDOW MDIACTIVE property, WINDOW MDIFRAME property, WINDOW ACTIVATED event, WINDOW CLOSE event, WINDOW FORMSTATECHANGED event.

Occurs when the user selects the "More Windows…" item from an MDI Frame form's "Windows" menu.

bForward = MDISELECT( CtrlEntID, CtrlClassID, activeID )

TRUE$ or FALSE$. If FALSE$, the program execution returns to the calling procedure. If TRUE$, the event processing goes to the next level.

The system level event for MDISELECT performs the following tasks:

• The MDISELECT quick event handler is executed (if defined) and the event status checked – if it returns anything other than FALSE$ the event is cancelled.
• If ActiveID contains the name of a valid MDI child form it is activated, otherwise the the RTI_MDISELECT dialog box is displayed allow a user to activate an MDI child form.
• Returns FALSE$ because the event has been forwarded when checking the quick event handler as above.

N/a.

WINDOW MDIACTIVE property, WINDOW MDIFRAME property, WINDOW ACTIVATED event, WINDOW INACTIVATED event.

Pseudo-method used to change the current page of a form.

bForward = PAGE( CtrlEntID, CtrlClassID, PageAction )

TRUE$ or FALSE$. If FALSE$, the program execution returns to the calling procedure. If TRUE$, the event processing goes to the next level.

This is not really an event as such as it is never triggered in response to some other action – rather it is used as a method to change the current page on a form.

The system-level PAGE event handler uses the PageAction parameter to set the form's CURRENTPAGE property.

This event is considered deprecated in favor of the SETPAGE method.

N/a.

Container API CURRENT page property, Container API PAGECOUNT property, Container API SETPAGE method.

Occurs when the form loads a row in a QBF result list using a position index.

bForward = QBFABS( CtrlEntID, CtrlClassID, AbsPos )

TRUE$ or FALSE$. If FALSE$, the program execution returns to the calling procedure. If TRUE$, the event processing goes to the next level.

This event is triggered by setting the QBFPOS property.

The system level event for QBFABS performs the following tasks:

• If there is only one row in the QBF result list a message is displayed and the QBFABS operation is cancelled.
• If AbsPos is null then a message is displayed to allow the user to enter the index of the data row to display. If an invalid index is entered the user is warned and the QBFABS operation is cancelled.
• The form's SAVEWARN property is checked and the user warned of any unsaved changes with the option to cancel the QBFABS operation, ignore the changes, or save the data before continuing.
• If the QBFREADMODE property is OnlyRead then the READROW method is used to load the data row into the form, otherwise the custom QBF form load process is used instead. If QBFREADMODE is OBFThenRead a READ event is then triggered.
• The index into the QBF result list (QBFPOS property) is updated.
• The form's caption is updated to show the current index in the QBF result list.
• If displayed, the QBFTABLE result list dialog box is synchronized with the new index.
• The form's SAVEWARN property is set to FALSE$.

N/a.

WINDOW QBFPOS property, WINDOW QBFREADMODE property, WINDOW QBFSHOWFIRST method, QBFSHOWLAST method, WINDOW QBFSHOWNEXT method, WINDOW QBFSHOWPREV method.

Occurs when a form's QBF session is closed.

bForward = QBFCLOSE( CtrlEntID, CtrlClassID )

TRUE$ or FALSE$. If FALSE$, the program execution returns to the calling procedure. If TRUE$, the event processing goes to the next level.

This event is triggered from the QBFCLOSESESSION method.

The system level event for QBFCLOSE performs the following tasks:

• Checks the form's SAVEWARN property and warns the user of any unsaved changes. If so, then the user is warned and given the option to cancel the QBFCLOSE operation, ignore the changes, or save the data before continuing.
• Clears the data-bound controls in the form and unlocks the row if needed (Note – this is via an internal method and not via a CLEARROW method, i.e. the CLEAR event is not triggered).
• The QBFSTATUS is set to QBFInactive, and the QBFPOS and QBFLIST properties are cleared,
• Enabled/read-only controls that were enabled when the QBF session was started are disabled again if necessary.
• The form's caption is reset.
• A FORMSTATECHANGED event is raised (with a "QBFCLOSE" EventSource parameter ).

N/a.

WINDOW QBFSTATUS property, WINDOW QBFINITSESSION method, WINDOW QBFCLOSESESSION method, WINDOW FORMSTATECHANGED event, WINDOW QBFINIT event.

Occurs when the form loads the first row in a QBF result list.

bForward = QBFFIRST( CtrlEntID, CtrlClassID )

TRUE$ or FALSE$. If FALSE$, the program execution returns to the calling procedure. If TRUE$, the event processing goes to the next level.

This event is triggered from the QBFSHOWFIRST method.

The system level event for QBFFIRST performs the following tasks:

• The form's SAVEWARN property is checked and the user warned of any unsaved changes with the option to cancel the QBFABS operation, ignore the changes, or save the data before continuing.
• If the QBFREADMODE property is OnlyRead then the READROW method is used to load the first data row from the QBF results list into the form, otherwise the custom QBF form load process is used instead. If QBFREADMODE is OBFThenRead a READ event is then triggered.
• The index into the QBF result list (QBFPOS property) is updated.
• The form's caption is updated to show the current index in the QBF result list.
• If displayed, the QBFTABLE result list dialog box is synchronized with the new index.
• The form's SAVEWARN property is set to FALSE$.

N/a.

WINDOW QBFPOS property, WINDOW QBFREADMODE property, WINDOW QBFSHOWLAST method, WINDOW QBFSHOWNEXT method, WINDOW QBFSHOWPREV method.

Occurs when QBF session is initialized for a form.

bForward = QBFINIT( CtrlEntID, CtrlClassID )

TRUE$ or FALSE$. If FALSE$, the program execution returns to the calling procedure. If TRUE$, the event processing goes to the next level.

This event is triggered from the QBFINITSESSION method.

The system level event for QBFINIT performs the following tasks:

• Checks the form's SAVEWARN property and warns the user of any unsaved changes. If so, then the user is warned and given the option to cancel the QBFINIT operation, ignore the changes, or save the data before continuing.
• Updates the form's caption to show that the QBF session is active.
• The QBFSTATUS is set to QBFInitialize (Note that LOSTFOCUS data validation and conversion on controls will not be performed while the QBFSTATUS is QBFInitialize).
• Clears the data-bound controls in the form (Note: this is via an internal method and not via a CLEARROW method, i.e. the CLEAR event is not triggered).
• Enables all non-primary disabled/read-only data-bound controls and read-only/protected data-bound Edit Table columns

Function QBFINIT( CtrlEntID, CtrlClassID )

Example: allow the system QBFINIT to execute, and if sucsessful raise an

 // OMNIEVENT event on the parent MDI frame form to let it know the state of//
 // the child.//
 
 Call Set_EventStatus( SETSTAT_OK$ )
 Call Forward_Event()
 If Get_EventStatus() Then
    // Assume cancelled or error//
    Return FALSE$
 End
 
 MDIFrame = Get_Property( @Window, "MDIFRAME" )
 
 // Assume that the frame uses an OMNIEVENT handler to respond to the//
 // child being initialized with a message of "CHILD_QBFINIT" and the//
 // child ID as the first parameter//
 
 EvStatus = Exec_Method( MDIFrame, "SENDEVENT", "OMNIEVENT", |
                         "CHILD_QBFINIT", CtrlEntID )

 // Return FALSE$ to stop the event chain as we've already forwarded to the//
 // system QBFINIT event handler above.//

Return FALSE$

Common GUI CONV property, Common GUI VALID property, WINDOW QBFSTATUS property, WINDOW QBFCLOSESESSION method , WINDOW QBFINITSESSION method, WINDOW QBFRUNQUERY method, Common GUI LOSTFOCUS event, WINDOW QBFCLOSE event, WINDOW QBFRUN event.

Occurs when the form loads the last row in a QBF result list.

bForward = QBFLAST( CtrlEntID, CtrlClassID )

TRUE$ or FALSE$. If FALSE$, the program execution returns to the calling procedure. If TRUE$, the event processing goes to the next level.

This event is triggered from the QBFSHOWLAST method.

The system level event for QBFLAST performs the following tasks:

• The form's SAVEWARN property is checked and the user warned of any unsaved changes with the option to cancel the QBFABS operation, ignore the changes, or save the data before continuing.
• If the QBFREADMODE property is OnlyRead then the READROW method is used to load the last data row from the QBF results list into the form, otherwise the custom QBF form load process is used instead. If QBFREADMODE is OBFThenRead a READ event is then triggered.
• The index into the QBF result list (QBFPOS property) is updated.
• The form's caption is updated to show the current index in the QBF result list.
• If displayed, the QBFTABLE result list dialog box is synchronized with the new index.
• The form's SAVEWARN property is set to FALSE$.

N/a.

WINDOW QBFPOS property, WINDOW QBFREADMODE property, WINDOW QBFSHOWFIRST method, WINDOW QBFSHOWNEXT method, WINDOW QBFSHOWPREV method.

Occurs when the form loads a row in a QBF result list using a row ID.

bForward = QBFLOADID( CtrlEntID, CtrlClassID, RowID )

TRUE$ or FALSE$. If FALSE$, the program execution returns to the calling procedure. If TRUE$, the event processing goes to the next level.

This event is triggered by the QBFGOTOID method.

The system level event for QBFLOADID performs the following tasks:

• If RowID is null then a message is displayed to allow the user to enter the ID of the data row to display. If an invalid ID is entered the user is warned and the QBFLOADID operation is cancelled.
• The form's SAVEWARN property is checked and the user warned of any unsaved changes with the option to cancel the QBFLOADID operation, ignore the changes, or save the data before continuing.
• If the QBFREADMODE property is OnlyRead then the READROW method is used to load the data row into the form, otherwise the custom QBF form load process is used instead. If QBFREADMODE is OBFThenRead a READ event is then triggered.
• The index into the QBF result list (QBFPOS property) is updated.
• The form's caption is updated to show the current index in the QBF result list.
• If displayed, the QBFTABLE result list dialog box is synchronized with the new index.
• The form's SAVEWARN property is set to FALSE$.

N/a.

WINDOW QBFLIST property, WINDOW QBFPOS property, WINDOW QBFREADMODE property, WINDOW QNFGOTOID method, WINDOW QBFSHOWFIRST method, QBFSHOWLAST method, WINDOW QBFSHOWNEXT method, WINDOW QBFSHOWPREV method.

Occurs when the form needs to obtain the name of a saved list of keys to load into its QBF result list.

bForward = QBFLOADLIST( CtrlEntID, CtrlClassID )

TRUE$ or FALSE$. If FALSE$, the program execution returns to the calling procedure. If TRUE$, the event processing goes to the next level.

This event is triggered from the QBFLOADSAVEDLIST method.

The system level event for QBFLOADLIST performs the following tasks:

• Displays a dialog allowing the user to choose the source of the list. This may be an entry in the TCL Query Table, or the name of a saved list in the SYSLISTS table.
• Once the source has been determined the keys are extracted and loaded into the form's QBFLIST property.

N/a.

WINDOW QBFLIST property, WINDOW QBFLOADSAVEDLIST method.

Occurs when the form loads the next row in a QBF result list.

bForward = QBFNEXT( CtrlEntID, CtrlClassID )

TRUE$ or FALSE$. If FALSE$, the program execution returns to the calling procedure. If TRUE$, the event processing goes to the next level.

This event is triggered from the QBFSHOWNEXT method.

The system level event for QBFNEXT performs the following tasks:

• The form's SAVEWARN property is checked and the user warned of any unsaved changes with the option to cancel the QBFABS operation, ignore the changes, or save the data before continuing.
• The index into the QBF result list is calculated for the next item (If it is already set to the last item it is set to show the first item instead).
• If the QBFREADMODE property is OnlyRead then the READROW method is used to load the specified data row from the QBF results list into the form, otherwise the custom QBF form load process is used instead. If QBFREADMODE is OBFThenRead a READ event is then triggered.
• The index into the QBF result list (QBFPOS property) is updated.
• The form's caption is updated to show the current index in the QBF result list. If displayed, the QBFTABLE result list dialog box is synchronized with the new index.
• The form's SAVEWARN property is set to FALSE$.

N/a.

WINDOW QBFPOS property, WINDOW QBFREADMODE property, WINDOW QBFSHOWFIRST method, WINDOW QBFSHOWLAST method, WINDOW QBFSHOWPREV method.

Occurs when the form loads the previous row in a QBF result list.

bForward = QBFPREV( CtrlEntID, CtrlClassID )

TRUE$ or FALSE$. If FALSE$, the program execution returns to the calling procedure. If TRUE$, the event processing goes to the next level.

This event is triggered from the QBFSHOWPREV method.

The system level event for QBFPREV performs the following tasks:

• The form's SAVEWARN property is checked and the user warned of any unsaved changes with the option to cancel the QBFABS operation, ignore the changes, or save the data before continuing.
• The index into the QBF result list is calculated for the previous item (If it is already set to the first item it is set to show the last item instead).
• If the QBFREADMODE property is OnlyRead then the READROW method is used to load the specified data row from the QBF results list into the form, otherwise the custom QBF form load process is used instead. If QBFREADMODE is OBFThenRead a READ event is then triggered.
• The index into the QBF result list (QBFPOS property) is updated.
• The form's caption is updated to show the current index in the QBF result list.
• If displayed, the QBFTABLE result list dialog box is synchronized with the new index.
• The form's SAVEWARN property is set to FALSE$.

N/a.

WINDOW QBFPOS property, WINDOW QBFREADMODE property, WINDOW QBFSHOWFIRST method, WINDOW QBFSHOWLAST method, WINDOW QBFSHOWNEXT method.

Occurs when the user enters a "raw" RLIST SELECT statement to load a QBF result list.

bForward = QBFQUERY( CtrlEntID, CtrlClassID )

TRUE$ or FALSE$. If FALSE$, the program execution returns to the calling procedure. If TRUE$, the event processing goes to the next level.

This event is triggered from the QBFASKQUERY method.

The system level event for QBFQUERY performs the following tasks:

• Checks to see if the QBFSTATUS is QBFInitialize, or QBFActive – if so a QBFCLOSESESSION method is executed to return the form to a clean state, otherwise a CLEARROW method is executed instead.
• This user is prompted to enter the RLIST SELECT statement they wish to execute.
• If they do so the form's caption is updated to indicate that a search is being processed.
• If the search returns one or more rows a QBFSHOWFIRST method is executed to display the first result, otherwise the user is informed that no matching rows were found.

N/a.

WINDOW QBFSTATUS property, WINDOW CLEARROW method, WINDOW QBFCLOSESESSION method, WINDOW QBFSHOWFIRST method,

Occurs when the form uses the query data entered into the data-bound controls to search the database and load a QBF result list.

bForward = QBFRUN( CtrlEntID, CtrlClassID )

TRUE$ or FALSE$. If FALSE$, the program execution returns to the calling procedure. If TRUE$, the event processing goes to the next level.

This event is triggered from the QBFRUNQUERY method.

The system level event for QBFRUN performs the following tasks:

• Checks to see if the QBFSTATUS is QBFInitialize. If not, the query operation is cancelled.
• Updates the form's caption to indicate a query is being processed.
• Checks each data-bound control on the form to see if contains data – if so, this is used to build an RLIST query string.
• If no query data has been entered the user is asked if they wish to select all rows for the QBF result list instead. If not the form's caption is reset to indicate that the QBFSTATUS is still QBFInitialize and the event is stopped.
• Otherwise, the query string is parsed and executed to search the database for matching rows.
• If the search was unsuccessful the form returns to a QBFSTATUS of QBFInitialize and the user can enter different search terms or close the QBF session.
• If the search is successful the resulting keys are loaded into a QBF result list, and the enabled/read-only controls are reset. The QBFSTATUS is set to QBFInactive and a QBFFIRST event is triggered to load the first row in the result list.

N/a.

WINDOW QBFSTATUS property, WINDOW QBFINITSESSION method, WINDOW QBFCLOSESESSION method, WINDOW QBFRUNQUERY method, WINDOW QBFFIRST event.

Occurs when a form's QBF result list is about to be displayed in a non-modal dialog box, allowing the user an easy visual way of navigating it.

bForward = QBFTABLE( CtrlEntID, CtrlClassID )

TRUE$ or FALSE$. If FALSE$, the program execution returns to the calling procedure. If TRUE$, the event processing goes to the next level.

This event is triggered from the QBFSHOWTABLE method.

The system level event for QBFTABLE executes the non-modal OIWIN_QBFLISTRESULTS dialog box that displays the rows in the QBF result list along with the data from the data-bound controls in the form.

As the user selects a row in the dialog the QBFPOS property of the form is updated to load the row into it.

If a row Is deleted from the form, it is also deleted from the dialog. Likewise, if data is updated in the form it is updated in the dialog too.

N/a.

WINDOW QBFLIST property, WINDOW QBFPOS property, WINDOW QBFSHOWTABLE method.

Occurs when data is read from the database into a data-bound form.

bForward = READ( CtrlEntID, CtrlClassID )

TRUE$ or FALSE$. If FALSE$, the program execution returns to the calling procedure. If TRUE$, the event processing goes to the next level.

The READ event has a system-level handler that performs the following tasks:

• Checks the form's SAVEWARN property and warns the user of any unsaved changes. If so, then the user is warned and given the option to cancel the read operation (This step normally happens if the READ event is invoked programmatically via the READROW method).
• Checks to see that all controls bound to a key part are filled. If not, the user is warned and the read operation is aborted.
• Locks and reads the primary data row (and secondary ones if this is a multi-table form), constructing a "row-map" of data and bound controls.
  • If any locks fail the user is given the option to cancel the read operation or continue in a "view-only mode". If cancelled the CLEARROW method is executed to reset the form's contents.
  • The form's caption is updated to reflect the view-only mode if appropriate.
• The data in the row-map is loaded into the data-bound controls.
• The NEWROW property is set appropriately.
• The row-map is cached for use with the READPREVROW method if the LOADPREVALWAYS property is TRUE$.

A READ event will be triggered by the system in the following circumstances:

• From the LOSTFOCUS event of controls bound to key columns when they all contain data, and the key has been changed.
• From the READROW method.

Applications needing to execute a read operation programmatically should use the WINDOW READROW method rather than using the Send_Event stored procedure to invoke a READ event directly (as was the case in previous versions of OpenInsight).

Function READ( CtrlEntID, CtrlClassID )

 // Example - READ event script that adds some information to STATIC control//
 // called TXT_INFO that is not data-bound after the read operation//
 $Insert RTI_SSP_Equates
 
 // First let the system event handler perform the READ in case we have a problem//
 Call Set_EventStatus( SETSTAT_OK$ )
 Call Forward_Event()
 If Get_EventStatus() Then
    // Assume cancelled or error//
    Null
 End Else
    
    KeyCode = Get_Property( @Window : ".EDL_KEYCODE, "TEXT" )
    ISNCode = Get_Property( @Window : ".EDL_ISNCODE, "TEXT" )
    
    InfoText = KeyCode : ":" : ISNCode
    
    Call Set_Property_Only( @Window : ".TXT_INFO", "TEXT", InfoText  )
 End
 
 // Return FALSE$ to stop the event chain as we've already forwarded to the//
 // system READ event handler above.//
 

Return FALSE$

WINDOW LOADPREVALWAYS property, WINDOW SAVEWARN property, WINDOW CLEARROW method, WINDOW READPREVROW method, WINDOW READROW method, Common GUI LOSTFOCUS event, WINDOW SYSMSG event.

Arranges all MDI Child forms into a tiled layout for an MDI frame form.

bForward = TILE( CtrlEntID, CtrlClassID, Orientation )

TRUE$ or FALSE$. If FALSE$, the program execution returns to the calling procedure. If TRUE$, the event processing goes to the next level.

The system-level event handler for this event calls the MDITILE method to perform the tiling operation, and because of this it has been deprecated in favor of that method. It is implemented only for backwards compatibility with earlier versions of OpenInsight.

(Note that this event is not a "true" event as such as it is never triggered by the PS, it can only be "manually" triggered by the developer in an application (typically from an MDI Window menu item) – it is actually a method masquerading as an event).

Please see the documentation for the WM_MDITILE message on the Microsoft website for more details.

N/a.

WINDOW MDITILE method.

This event is raised when the form’s DPI or SCALEFACTOR property is changed. OpenInsight will automatically adjust the following properties for the form’s child controls:

• Position and size coordinates.
• Fonts.
• Images.

The SCALED event provides the opportunity for a developer to apply any further modifications needed to handle the new scale.

bForward = SCALED( CtrlEntID, CtrlClassID, OrigDpiX, OrigDpiY, OrigScaleFactor, |

NewDpiX, NewDpiY, NewScaleFactor )

TRUE$ or FALSE$. If FALSE$, the program execution returns to the calling procedure. If TRUE$, the event processing goes to the next level.

There is no system-level event handler for this event.

The Windows WM_DPICHANGED message will trigger the SCALED event when the form’s DPI is changed by moving it to a monitor with a different DPI. More information on WM_DPICHANGED can be found on the Microsoft website.

Function SCALED( CtrlEntID, CtrlClassID, OrigDpiX, OrigDpiY, OrigScaleFactor, |

                                       NewDpiX, NewDpiY, NewScaleFactor )
                                       
 // Example - SCALED event to set the  Zoom property of an imaginary OLE preview //
 //           control based on the passed DPI and custom scalefactor.//
 
 $Insert Logical
 
 // We are assuming that this imaginary "Zoom" property is an integer//
 // value which expresses the zoom factor as a percentage, e.g.//
 ////
 // E.g.//
 ////
 //  Zoom Factor   Property Value//
 //  =========== ==============//
 //    50%    ->   50//
 //   100%    ->  100//

125% → 125

 ////
 //  etc.//
 ////
 // We are going to combine the scaling factor of the DPI along with//
 // the custom scale factor (if any).//
 
 DpiFactor   = ( NewDpiX / 96 )
 TotalFactor = DpiFactor * NewScaleFactor 
 
 NewZoom = Int( 100 * TotalFactor )
 
 Call Set_Property_Only( @Window : ".OLE_PREVIEW", "OLE.Zoom", NewZoom )
 

Return TRUE$

SYSTEM DPI property, WINDOW DPI property, WINDOW SCALEFACTOR property, Appendix K – High DPI Programming.