guides:oi10:presentation_server_model:500_window_object

The WINDOW object (more commonly referred to as a Form) is the core object type used to build an OpenInsight desktop user interface. It represents a visual surface on which other GUI controls (such as EditLines, Listboxes, Checkboxes and so on) are placed and arranged which allow the user to interact with an application.

Developer Notes

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

WINDOW Properties

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

Name Description
ACCELERATORFORM Specifies the name of form that menu accelerator keystrokes on the current form are redirected to.
ACTIVE Specifies if the form is active.
ALLOWFORMSTATEEVENTSSpecifies if a form triggers the FORMSTATECHANGED and MDICHILDSTATECHANGED events.
ALLOWSELFLOCKS Specifies if a data-bound form ignores locks placed on the same record.
ALLOWSEQKEYRESET Specifies if a user is allowed to reset a data-bound form's sequential key counter.
ARRANGEICONS Specifies if an MDI Frame form automatically arranges its minimized MDI child forms.
ATRECORD Gets or sets data associated with the primary table of a data-bound form and updates data-bound controls.
AUTOCOMPOSITED Specifies if the form uses system double-buffering during sizing operations.
COMMONLIST Returns a list of attached labelled common areas.
COMMUTERMODULE Contains the name of the stored procedure used to handle events for the specified form.
CTRLMAP Returns a list of controls hosted by the specified form.
DESTROYFLAG Specifies if the form is flagged for destruction during SYSTEM QUERYEND processing.
DPI Returns the current DPI (dots-per-inch) setting for the specified form.
DWMANIMATION Specifies if the form uses Desktop Window Managet (DWM) animations.
FIRSTFOCUS Returns the name of the first control that receives the input focus when the specified form is created.
FORMBORDERSTYLE Specifies the border style of a form.
GOTFOCUSCONTROL Returns the last control on the form with a GOTFOCUS event handler that had the input focus.
HELPBUTTON Specifies if a help button is displayed on a form's caption bar.
HIDEEFFECT Specifies the animation used with a form's HIDE method.
ICON Specifies the name of the icon displayed in the form's caption bar.
ID Returns the current row key associated with the primary table data-row in a data-bound form.
INITIALFOCUS Returns the control that receives the input focus when the specified form is activated.
INITIALPOSITION Specifies the starting location of the specified form.
IOOPTIONS Specifies the data-binding options for a form.
LOADPREVALWAYS Specifies if the form's PREVROWVAL property is updated during a read operation as well as a write operation.
LOCKCOORDINATION Specifies if table-lock coordination is used by the form in conjunction with record locking.
LOCKTYPE Specifies the type of row locking used by a form.
MAXIMIZEBUTTON Specifies if a maximize button is displayed on a form's caption bar.
MDIACTIVE Activates an MDI child form or returns the name of the currently active MDI child form for the specified MDI frame form.
MDIFRAME Returns the name of the parent MDI frame form for the specified MDI child form.
MINIMIZEBUTTON Specifies if a maximize button is displayed on a form's caption bar.
MULTIINSTANCE Specifies if multiple instances of the same form may be executed in the same session at runtime.
NEWROW Returns TRUE$ if the specified form has loaded a new (blank) data row.
NOACTIVATE Prevents a top-level window becoming the foreground window when the user clicks it.
NOCLEARONWRITE Specifies if a data bound form clears its contents after a successful write operation.
NUMERICCOMPARE Specifies the type of comparison the form write operation uses to determine if a column needs updating.
OVERLAYICON Specifies a small icon that may be used to overlay the normal icon on a form's taskbar button.
OWNER Gets or sets the owner of the specified form.
PLACEMENTDATA Get or sets the show state and the restored, minimized, and maximized positions of the specified form.
PREVROWVAL Returns the values that were held in the specified form's controls for a previously loaded data row.
PROGRESSSTATE Sets the state of the current progress information on the specified form's taskbar button.
PROGRESSVALUE Displays progress information on the specified form's taskbar button.
QBFLIST Gets or sets the list of data keys used by the current QBF (Query-By-Form) session for the specified form.
QBFPOS Gets or sets the index of the row to display when the specified form has a valid QBFLIST loaded.
QBFSTATUS Returns the status of the QBF session for the specified form.
QBFREADMODE Specifies if a form triggers the READ event when loading data during QBF processing.
RECORD Gets or sets the cached copy of the data row associated with the specified form.
REQUIREONWRITE Specifies when a form performs "required data" checks.
RESTORESIZE Returns the position and size of the specified form in its non-maximized/minimized state.
ROW Gets or sets data associated with the primary table of a data-bound form and updates data-bound controls.
ROWLOCKED Returns TRUE$ if the form has loaded and locked a data row.
SAVEWARN Specifies if a data-bound form contains changed data that has not been saved.
SCALEFACTOR Specifies the custom magnification factor for a form.
SCALEUNITS Specifies how size and position coordinates are interpreted by a form.
SHOWCAPTION Specifies if a form displays a caption bar.
SHOWEFFECT Gets or sets the animation used with the SHOW method for the specified form.
SIZINGMODE Specifies if a form can resized with the mouse,
STATUSLINE Identifies the control that receives "status" messages from stored procedures when the specified form is active.
STYLESHEEET Specifies the name of a form to use as a "styling template" when adding controls to a form at design-time.
SUPPRESSSAVEWARN Specifies if a data-bound form checks the SAVEWARN property before clearing its contents or closing.
SYSTEMMENU Specifies if a "System Menu" is allowed for the specified form.
TABLE Returns the name of the primary table that the specified form is bound to.
TASKBARBUTTON Returns a flag denoting if Windows has created a taskbar button for the specified form.
TASKBARID Specifies a text string used to group or ungroup forms on the Windows taskbar.
TRACKINGSIZE Specifies the minimum and maximum sizes that a user may resize a form to.
TRANSLUCENCY Specifies the degree of transparency applied to a form when it is painted.
TOPMOST Specifies if the form appears above all other non-TOPMOST forms in the system z-order.
VISIBLE Specifies if a form is visible, hidden, maximized, or minimized.
WRITEATRECORD Specifies how data set with the ATRECORD property is saved during a write operation.
WRITEMODE Specifies how data set with the ROW property is saved during a write operation.

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

Description

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.

Property Value

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.

Property Traits

DevelopmentRuntimeIndexedScaledSynthetic
N/a Get/Set No No No

Remarks

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

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

See Also

MENU object.

Description

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

Property Value

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

Property Traits

DevelopmentRuntimeIndexedScaledSynthetic
N/a Get No No No

Remarks

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

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

See Also

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

Description

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.

Property Value

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

Property Traits

DevelopmentRuntimeIndexedScaledSynthetic
Get/Set Get No No Yes

Remarks

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

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

See Also

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

Description

Specifies if a form triggers the FORMSTATECHANGED and MDICHILDSTATECHANGED events.

Property Value

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

Property Traits

DevelopmentRuntimeIndexedScaledSynthetic
Get/Set Get No No Yes

Remarks

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

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

See Also

WINDOW IOOPTIONS property, WINDOW FORMSTATECHANGED event WINDOW MDICHILDSTATECHANGED event.

Description

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.

Property Value

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

Property Traits

DevelopmentRuntimeIndexedScaledSynthetic
Get/Set Get/Set No No Yes

Remarks

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

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

See Also

Common GUI DEFVALUE property, WINDOW IOOPTIONS property.

Description

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

Property Value

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

Property Traits

DevelopmentRuntimeIndexedScaledSynthetic
Get/Set Get/Set No No No

Remarks

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

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

See Also

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

Description

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

Property Value

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.

Property Traits

DevelopmentRuntimeIndexedScaledSynthetic
N/a Get/Set No No Yes

Remarks

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

     
 // 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$.//
 

See Also

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.

Description

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

Property Value

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,

Property Traits

DevelopmentRuntimeIndexedScaledSynthetic
Get/Set Get/Set No No No

Remarks

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

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

See Also

Common GUI COMPOSITED property.

Description

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

Property Value

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

Property Traits

DevelopmentRuntimeIndexedScaledSynthetic
N/a Get No No Yes

Remarks

N/a.

Example

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

See Also

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

Description

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

Property Value

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

Property Traits

DevelopmentRuntimeIndexedScaledSynthetic
Get/Set Get No No Yes

Remarks

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

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

See Also

Appendix XXX – Event processing.

Description

Returns a list of controls hosted by the specified form.

Property Value

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

Property Traits

DevelopmentRuntimeIndexedScaledSynthetic
N/a Get No No Yes

Remarks

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

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

See Also

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

Description

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

Property Value

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

Property Traits

DevelopmentRuntimeIndexedScaledSynthetic
N/a Get No No No

Remarks

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.

Example

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

See Also

Common GUI HANDLE property, SYSTEM QUERYEND property.

Description

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

Property Value

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

<1> X (horizontal) DPI
<2> Y (vertical) DPI

Property Traits

DevelopmentRuntimeIndexedScaledSynthetic
N/a Get No No No

Remarks

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.

Example

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

See also

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

Description

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

Property Value

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

Property Traits

DevelopmentRuntimeIndexedScaledSynthetic
N/a Get/Set No No No

Remarks

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

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

See Also

N/a.

Description

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

Property Value

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.

Property Traits

DevelopmentRuntimeIndexedScaledSynthetic
N/a Get No No No

Remarks

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

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

See Also

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

Description

Gets or sets the border style of the form.

Property Value

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

ValueName Description
0 None The form has no border and cannot have a caption bar or be resized by the user.
1 Fixed The form has a thin border and cannot be resized by the user.
2 Sizeable The form has a normal border and can be resized by the user.
3 Dialog The form has a normal border but cannot be resized by the user.
4 FixedTool The form has a normal border with a thinner caption bar but cannot be resized by the user.
5 SizeableToolThe form has a normal border with a thinner caption bar and can be resized by the user.

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.

Property Traits

DevelopmentRuntimeIndexedScaledSynthetic
Get/Set Get/Set No No No

Remarks

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

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

See Also

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

Description

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

Property Value

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.

Property Traits

DevelopmentRuntimeIndexedScaledSynthetic
N/a Get No No No

Remarks

N/a.

Example

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

 GotFocusCtrl = Get_Property( @Window, "GOTFOCUSCONTROL" )
 

See Also

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

Description

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

Property Value

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

Property Traits

DevelopmentRuntimeIndexedScaledSynthetic
Get/Set Get/Set No No No

Remarks

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

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

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

See Also

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

Description

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

Property Value

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

ValueName Description
0 None No animation effect when hidden. This is the default.
1 Fade The form fades until is no longer visible.
2 Slide down The form's top edge slides down to its bottom edge until the form is no longer visible.
3 Slide up The form's bottom edge slides up to its top edge until the form is no longer visible.
4 Slide right The form's left edge slides to its right edge until it the form is no longer visible.
5 Slide left The form's right edge moves to its left edge until the form is no longer visible.
6 Slide down and rightThe form's top-left corner slides down to its bottom-right corner until the form is no longer visible.
7 Slide down and left The form's top-right corner slides down to the bottom-left corner until the form is no longer visible.
8 Slide up and right The form's bottom-left corner slides up to its top-right corner until the form is no longer visible.
9 Slide up and left The form's bottom-right corner slides up to its top-left corner until the form is no longer visible.

Property Traits

DevelopmentRuntimeIndexedScaledSynthetic
Get/Set Get/Set No No No

Remarks

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

     
 // 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" )
 

See Also

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

Description

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.

Property Value

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"

Property Traits

DevelopmentRuntimeIndexedScaledSynthetic
Get/Set Get/Set No No No

Remarks

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.

Example

 
 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 )
    

See Also

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

Description

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

Property Value

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.

Property Traits

DevelopmentRuntimeIndexedScaledSynthetic
N/a Get No No Yes

Remarks

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

Example

     
 // 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 ""//
 

See Also

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

Description

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

Property Value

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.

Property Traits

DevelopmentRuntimeIndexedScaledSynthetic
N/a Get/Set No No No

Remarks

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

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

See Also

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

Description

Specifies the starting location of the specified form.

Property Value

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

ValueName Description
0 As designed The form is displayed using the form's Left and Top property values.
1 Center on desktopThe form is displayed centered on the desktop.
2 Center on parent The form is displayed centered on its parent.

Property Traits

DevelopmentRuntimeIndexedScaledSynthetic
Get/Set Get Only No No No

Remarks

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.

Example

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

See Also

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

Description

Specifies the data-binding options for the form.

Property Value

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

FieldPropertyName Description
<1> Reserved N/a.
<2> LockType Specifies the type of row locking used by the form.
<3> LockCoordination Specifies if table-lock coordination is used by the form in conjunction with record locking.
<4> AllowSelfLocks Specifies if attempts to lock rows that are already locked by the current session are allowed.
<5> Reserved N/a.
<6> NoClearOnWrite Specifies if a form clears its contents after a successful write operation.
<7> Reserved N/a.
<8> Reserved N/a.
<9> Reserved N/a.
<10> RequireOnWrite Specifies if "data-required" checks are performed before a write operation.
<11> QBFReadMode Specifies if a form's READ event is triggered when loading a data row in QBF mode.
<12> NumericCompare Specifies how comparisons for column updates are performed during a write operation.
<13> WriteMode Specifies how data set via the ROW property is saved during a write operation.
<14> LoadPrevAlways Specifies if the "previous data row" is updated on a read operation as well as a write operation.
<15> SuppressSaveWarn Specifies if a data-bound form ignores the SAVEWARN property during CLEAR and CLOSE processing.
<16> AllowFormStateEventsSpecifies if a form triggers the FORMSTATECHANGED and MDICHILDSTATECHANGED events.

Property Traits

DevelopmentRuntimeIndexedScaledSynthetic
N/a Get/Set No No Yes

Remarks

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

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

See Also

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.

Description

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

Property Value

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

Property Traits

DevelopmentRuntimeIndexedScaledSynthetic
Get/Set Get/Set No No Yes

Remarks

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

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

See Also

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

Description

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

Property Value

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

ValueName Description
0 Normal No table locks are used. This is the default.
1 WithTableLocksA shared table lock will be applied in concert with the row lock. A shared table lock will conflict with any exclusive table locks which are already on the table or with any exclusive table locks which are attempted on the table after the shared table lock is implicitly applied. Table locks will always be attempted before row locks are applied.

Property Traits

DevelopmentRuntimeIndexedScaledSynthetic
Get/Set Get No No Yes

Remarks

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

Example

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

See Also

WINDOW IOOPTIONS property, WINDOW LOCKLEVEL property.

Description

Specifies the type of row locking used by a form.

Property Value

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

ValueName Description
0 Exclusive Exclusive locks disallow other users from gaining exclusive or shared locks on the same rows (This is the default option.)

When a READ event is triggered exclusive locks will be applied to the primary table row and rows from subsidiary tables before any read operations are attempted.

Failure of any lock will cause a locking error to be presented and the user will be allowed to continue in view-only mode or to cancel the read operation altogether.

Locks will be removed when the form data is cleared through any mechanism, (for example, CLEAR, DELETE, CLOSE, or QBF operation).
1 Shared This type is similar to the Exclusive type except that a shared lock is applied instead of an exclusive lock.

A shared lock disallows other exclusive locks but allows other shared locks to be gained against the same rows.

Write and delete operations should be disabled for this locking option.

Shared locking is not supported on all networks – in this case this option behaves exactly as does the Exclusive option.
2 No LockingNo locking is performed on any rows, either from the primary or subsidiary tables.

Write and delete operations should be disabled for this locking option.

This setting may be appropriate for View only forms or for forms which perform custom locking beforehand.

Property Traits

DevelopmentRuntimeIndexedScaledSynthetic
Get/Set Get No No Yes

Remarks

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

Example

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

See Also

WINDOW IOOPTIONS property, WINDOW LOCKCOORDINATION property.

Description

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

Property Value

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

Property Traits

DevelopmentRuntimeIndexedScaledSynthetic
Get/Set Get/Set No No No

Remarks

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

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

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

See Also

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

Description

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

Property Value

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.

Property Traits

DevelopmentRuntimeIndexedScaledSynthetic
N/a Get/Set No No No

Remarks

This property applies to MDI frame forms only.

Example

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

See Also

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

Description

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

Property Value

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.

Property Traits

DevelopmentRuntimeIndexedScaledSynthetic
N/a Get No No No

Remarks

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

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

See Also

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

Description

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

Property Value

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

Property Traits

DevelopmentRuntimeIndexedScaledSynthetic
Get/Set Get/Set No No No

Remarks

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

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

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

See Also

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

Description

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

Property Value

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

Property Traits

DevelopmentRuntimeIndexedScaledSynthetic
Get/Set Get No No No

Remarks

N/a.

Example

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

See Also

WINDOW STARTFORM method, WINDOW STARTMDICHILDFORM method.

Description

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

Property Value

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

Property Traits

DevelopmentRuntimeIndexedScaledSynthetic
N/a Get No No Yes

Remarks

N/a.

Example

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

See Also

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

Description

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

Property Value

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,

Property Traits

DevelopmentRuntimeIndexedScaledSynthetic
Get/Set Get No No Yes

Remarks

N/a.

Example

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

See Also

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

Description

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

Property Value

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

Property Traits

DevelopmentRuntimeIndexedScaledSynthetic
Get/Set Get Only No No No

Remarks

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.

Example

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

See also

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

Description

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

Property Value

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.

Property Traits

DevelopmentRuntimeIndexedScaledSynthetic
Get/Set Get No No Yes

Remarks

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

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

See Also

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

Description

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

Property Value

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

Property Traits

DevelopmentRuntimeIndexedScaledSynthetic
N/a Get/Set No No No

Remarks

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

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

See Also

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

Description

Gets or sets the owner of the specified form.

Property Value

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

Property Traits

DevelopmentRuntimeIndexedScaledSynthetic
N/a Get/Set No No No

Remarks

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

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

See Also

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

Description

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

Property Value

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

FieldPropertyNameDescription
<1> ShowCmd Specifies the show state of the form – this is equivalent to its VISIBLE property.
<2> NormalPosition Specifies size of the form in its normal position:

\\    <0,1> Left\\    <0,2> Top\\    <0,3> Width\\    <0,4> Height\\ 
<3> MinPosition Specifies the coordinates of the form's upper-left corner when minimized. This is an @Vm-delimited array:

\\    <0,1> Left\\    <0,2> Top\\ 
<4> MaxPosition Specifies the coordinates of the form's upper-left corner when maximized. This is an @Vm-delimited array:

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

Property Traits

DevelopmentRuntimeIndexedScaledSynthetic
N/a Get/Set No Yes No

Remarks

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

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

See Also

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

Description

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

Property Value

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

Property Traits

DevelopmentRuntimeIndexedScaledSynthetic
N/a Get No No Yes

Remarks

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

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

 
 PrevRow = Get_Property( @Window, "PREVROWVAL" )
 

See Also

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

Description

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

Property Value

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

ValueName Description
0 No Progress Removes progress information from the taskbar button.
1 Normal Sets the color of the taskbar button progress information to Green.
2 Error Sets the color of the taskbar button progress information to Red.
3 Paused Sets the color of the taskbar button progress information to Amber.
4 IndeterminateSets the taskbar button progress information to a green marquee effect.

Property Traits

DevelopmentRuntimeIndexedScaledSynthetic
N/a Set No No No

Remarks

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

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

See Also

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

Description

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

Property Value

This is an @Fm delimited array containing progress information:

FieldName Description
<1> CurrrentValueThis is an integer specifying the current progress position. It is used with the MaximumValue field to calculate a percentage value which is then used to display the width of progress indicator on the taskbar button.

It cannot be greater than the MaximumValue.
<2> MaximumValue This is an integer specifying the maximum progress value. It is used with the CurrentValue field to calculate a percentage value which is then used to display the width of the progress indicator on the taskbar button.

It cannot be less than the CurrentValue.

Property Traits

DevelopmentRuntimeIndexedScaledSynthetic
N/a Set No No No

Remarks

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

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

See Also

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

Description

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

Property Value

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

Property Traits

DevelopmentRuntimeIndexedScaledSynthetic
N/a Get/Set No No Yes

Remarks

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

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

See Also

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

Description

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

Property Value

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

Property Traits

DevelopmentRuntimeIndexedScaledSynthetic
N/a Get/Set No No Yes

Remarks

Setting this property triggers the form's QBFABS event.

Example

     
 // 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
 

See Also

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

Description

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

Property Value

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

ValueName Description
0 QBFInactive No QBF session is active for the form.
1 QBFInitializeThe form is ready to accept query data into its controls.
2 QBFActive A QBF query has been executed and the QBF result list (QBFLIST property) has been populated.

Property Traits

DevelopmentRuntimeIndexedScaledSynthetic
N/a Get No No Yes

Remarks

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

Example

     
 // 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
 

See Also

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

Description

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

Property Value

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

ValueName Description
0 OnlyQBF The custom QBF form loading process is used. A READ event is not triggered. This is the default for backwards compatibility.
1 QBFThenReadThe standard QBF form-load process is used, followed by a READ event. This causes the data to be read and loaded twice.

This is option is available for backwards compatibility purposes only and should be considered deprecated.
2 OnlyRead The standard READ event process is used to load rows during QBF processing.

This is the preferred option.

Property Traits

DevelopmentRuntimeIndexedScaledSynthetic
Get/Set Get No No Yes

Remarks

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

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

See Also

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

Description

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

Property Value

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.

Property Traits

DevelopmentRuntimeIndexedScaledSynthetic
N/a Get/Set No No Yes

Remarks

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.

Example

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

See Also

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

Description

Specifies when a form performs "required data" checks.

Property Value

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

Property Traits

DevelopmentRuntimeIndexedScaledSynthetic
Get/Set Get/Set No No Yes

Remarks

N/a.

Example

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

just before a write operation

 
 IsRequiredOnWrite = Get_Property( @Window, "REQUIREONWRITE" )   
 

See Also

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

Description

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

Property Value

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

<1> Left

<2> Top

<3> Width

<4> Height

Property Traits

DevelopmentRuntimeIndexedScaledSynthetic
N/a Get No No No

Remarks

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

Example

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

See also

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

Description

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

Property Value

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.

Property Traits

DevelopmentRuntimeIndexedScaledSynthetic
N/a Get/Set No No Yes

Remarks

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

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

See Also

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

Description

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

Property Value

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

Property Traits

DevelopmentRuntimeIndexedScaledSynthetic
N/a Get No No Yes

Remarks

N/a.

Example

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

See Also

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

Description

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.

Property Value

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.

Property Traits

DevelopmentRuntimeIndexedScaledSynthetic
N/a Get/Set No No Yes

Remarks

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

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

See Also

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.

Description

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

Property Value

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

FieldName Description
<1> ScaleFactor This is a number that specifies how much to scale the form by. A value of 1 means that the form has no custom scaling applied, a value of 1.5 scales the form to one-and-a-half times its normal size and so on.

* This value cannot be set at design time.
* This value can be set on its own at runtime without having to specify the other fields.
<2> MinScaleFactor This specifies the minimum value that the ScaleFactor can be set to. By default it is set to “0.5”, and can be a value between "0.1" and "1.0" inclusive.
<3> MaxScaleFactor This specifies the maximum value that the ScaleFactor can be set to. By default it is set to “5.0", and can be a value between "1.0" and "5.0" inclusive.
<4> ScaleFactor IncrementIf this field is set to a value other than 0 (the default) it allows the ScaleFactor to be adjusted via the Mouse-wheel /Ctrl-key combination, or with a “pinch-zoom” gesture if running with a touch screen. The increment value controls the rate at which the form grows or shrinks.

Property Traits

DevelopmentRuntimeIndexedScaledSynthetic
Get/Set Get/Set No No Yes

Remarks

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

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

See Also

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

Description

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.

Property Value

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:

ValueDescription
0 Use DIPs (the default).
1 Use pixels.

Property Traits

DevelopmentRuntimeIndexedScaledSynthetic
N/a Get/Set No No No

Remarks

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

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

See also

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

Description

Specifies if a form displays a caption bar.

Property Value

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

Property Traits

DevelopmentRuntimeIndexedScaledSynthetic
Get/Set Get/Set No No No

Remarks

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

Example

Example – Remove the current form's caption bar

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

See Also

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

Description

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

Property Value

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

ValueName Description
0 None No animation effect when shown. This is the default.
1 Fade The form fades in until it is fully visible.
2 Slide down The form's bottom edge slides down from its top edge until the form is fully visible.
3 Slide up The form's top edge slides up from its bottom edge until the form is fully visible.
4 Slide right The form's right edge slides out from its left edge until it the form is fully visible.
5 Slide left The form's left edge slides out from its right edge until the form is fully visible.
6 Slide down and rightThe form's bottom-right corner slides down from its top-left corner until the form is fully visible.
7 Slide down and left The form's bottom-left corner slides down from its top-right corner until the form is fully visible.
8 Slide up and right The form's top-right corner slides up from its bottom-left corner until the form is fully visible.
9 Slide up and left The form's top-left corner slides up from its bottom-right corner until the form is fully visible.

Property Traits

DevelopmentRuntimeIndexedScaledSynthetic
Get/Set Get/Set No No No

Remarks

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

     
 // 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" )
 

See Also

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

Description

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.

Property Value

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

ValueNameDescription
0 Default Resizing the form is controlled by the FORMBORDERSTYLE property.
1 Always The form may always be resized with the mouse.
2 Never The form cannot be resized with the mouse.

Property Traits

DevelopmentRuntimeIndexedScaledSynthetic
Get/Set Get/Set No No No

Remarks

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

Example

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

See Also

WINDOW FORMBORDERSTYLE property.

Description

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.

Property Value

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

Property Traits

DevelopmentRuntimeIndexedScaledSynthetic
Get/Set Get/Set No No No

Remarks

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

     
 // 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" )
 

See Also

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

Description

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

Property Value

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

Property Traits

DevelopmentRuntimeIndexedScaledSynthetic
Get/Set N/a No No Yes

Remarks

N/a.

Example

N/a.

See Also

N/a.

Description

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

Property Value

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.

Property Traits

DevelopmentRuntimeIndexedScaledSynthetic
Get/Set Get/Set No No Yes

Remarks

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

Example

     
 // 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" )   
 

See Also

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

Description

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:

Property Value

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

Property Traits

DevelopmentRuntimeIndexedScaledSynthetic
Get/Set Get/Set No No No

Remarks

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

Example – Ensure that the current form has a System Menu

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

See Also

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

Description

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

Property Value

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

Property Traits

DevelopmentRuntimeIndexedScaledSynthetic
N/a Get No No Yes

Remarks

N/a.

Example

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

See Also

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

Description

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

Property Value

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

Property Traits

DevelopmentRuntimeIndexedScaledSynthetic
N/a Get No No No

Remarks

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

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

See Also

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

Description

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

Property Value

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.

Property Traits

DevelopmentRuntimeIndexedScaledSynthetic
Get/Set Get/Set No No No

Remarks

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

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

See Also

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

Description

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

Property Value

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.

Property Traits

DevelopmentRuntimeIndexedScaledSynthetic
Get/Set Get/Set No Yes No

Remarks

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

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

See also

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

Description

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

Property Value

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

Property Traits

DevelopmentRuntimeIndexedScaledSynthetic
Get/Set Get/Set No No No

Remarks

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.

Example

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

See also

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

Description

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

Property Value

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

Property Traits

DevelopmentRuntimeIndexedScaledSynthetic
Get/Set Get/Set No No No

Remarks

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

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

See Also

Common GUI SETZORDER method.

Description

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

Property Value

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:

ValueName Description
0 SW_HIDE Hides the form and activates another form.
1 SW_SHOWNORMAL Displays the form and activates it. If the form is minimized or maximized, the system restores it to its original size and position.
2 SW_SHOWMINIMIZED Minimizes the form and activates it.
3 SW_SHOWMAXIMIZED Maximizes the form and activates it.
4 SW_SHOWNOACTIVATE Displays the form in its most recent size and position. This value is similar to SW_SHOWNORMAL, except that the form is not activated.
5 SW_SHOW Activates the form and displays it in its current size and position.
6 SW_MINIMIZE Minimizes the specified form and activates the next top-level form in the Z order.
7 SW_SHOWMINNOACTIVEDisplays the form as a minimized form. This value is similar to SW_SHOWMINIMIZED, except the form is not activated.
8 SW_SHOWNA Displays the form in its current size and position. This value is similar to SW_SHOW, except that the form is not activated.
9 SW_RESTORE Activates and displays the form. If the form is minimized or maximized, the system restores it to its original size and position. An application should specify this flag when restoring a minimized form.

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

Property Traits

DevelopmentRuntimeIndexedScaledSynthetic
Get/Set Get/Set No No No

Remarks

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.

Example

 
 $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
 

See also

Common GUI VISIBLE property.

Description

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

Property Value

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.

Property Traits

DevelopmentRuntimeIndexedScaledSynthetic
N/a Get/Set No No Yes

Remarks

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

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

See Also

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

Description

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

Property Value

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

ValueName Description
0 WriteControlsOnlyOnly data from data-bound controls on the form is written back to the table during a write operation. This is the default behavior.
1 WriteEntireRow Data from columns that are not bound to a control on the form (and that were set via the ROW property) is written to the table in addition to the data in the controls.

Property Traits

DevelopmentRuntimeIndexedScaledSynthetic
Get/Set Get No No Yes

Remarks

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

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

See Also

WINDOW ROW property.

WINDOW Methods

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

Name Description
ATTACHCOMMON Attaches a labelled common to the form.
CENTER Centers a form on the desktop or over its parent.
CLEARROW Clears the data row from a data-bound form.
CLOSE Closes a form by triggering its CLOSE event.
CLOSEDIALOG Closes a dialog box and returns a value to the owner.
DELETEROW Deletes the currently loaded data row in a data-bound form.
DETACHCOMMON Detaches a labelled common from the form and optionally frees it.
FLASH "Flashes" a form's caption and/or taskbar button a specified number of times.
GETFOCUSEDCONTROLReturns the control with focus on the form.
HIDE Hides a form using the specified effect.
HIDEMENUBAR Hides the specified form's menu bar.
MDICASCADE Arranges MDI child forms in a cascaded overlapping formation.
MDIICONARRANGE Arranges minimized MDI child forms.
MDITILE Arranges MDI child forms in a tiled formation.
QBFASKQUERY Asks for and executes an RLIST query statement and populates the specified form's QBF result list.
QBFCLOSESESSION Closes a QBF session for the specified form.
QBFGOTO Loads a specific row from the form's QBF result list based on it's position.
QBFGOTOID Loads a specific row from the QBF result list using its ID.
QBFINITSESSION Initializes and begins a QBF session for the specified form.
QBFLOADSAVEDLIST Asks the user for the name of a saved list and loads the keys into the specified form's QBF result list.
QBFRUNQUERY Builds and executes an RLIST query from the data in the controls and populates the specified form's QBF result list.
QBFSHOWFIRST Shows the first row from the specified form's QBF result list.
QBFSHOWLAST Shows the last row from the specified form's QBF result list.
QBFSHOWNEXT Shows the next row from the specified form's QBF result list.
QBFSHOWPREV Shows the previous row from the specified form's QBF result list.
QBFSHOWTABLE Displays the specified form's QBF result list in a non-modal dialog box.
READROW Reads the data into the specified data-bound form and populates the controls.
READPREVROW Populates controls in the specified form with data from the previously loaded row.
*SCROLL Scrolls the contents of the form by the specified amount.
SHOW Displays a form using the specified effect.
SHOWMENUBAR Displays the specified form's menu bar.
SHOWDIALOG Displays a modal dialog using the specified form as the owner.
SHOWINDEXLOOKUP Displays the index lookup dialog box using the specified form as the owner,
SHOWMESSAGE Displays a message box, using the specified form as the parent.
SHOWPOPUP Displays a popup box, using the specified form as the owner.
STARTFORM Executes a new form, using the specified form as the owner.
STARTMDICHILDFORMExecutes a new MDI child form for the specified MDI frame parent.
TRACKDROPDOWNMENUDisplays a dropdown menu for a top-level menu bar item on the specified form.
UPDATEROW Updates the data associated with the primary table of a data-bound form without updating data-bound controls.
WRITEROW Writes the data contains in the specified data-bound form to the database.

Description

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

Syntax

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

Parameters

Name RequiredDescription
CommonNameYes Name of the common area to attach.

Returns

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

Remarks

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

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

See Also

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

Description

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

Syntax

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

CalculateOnly, ParentSize, Options )

Parameters

Name RequiredDescription
CenterParent No If TRUE$ then the form is centered on its parent, otherwise it is centered on the desktop. Defaults to FALSE$.
IdealSize No This is an @Fm-delimited array specifying the desired coordinates and size to move the window to:

\\    <1> Left-position (if -1 then the window is   \\        Centered on the X-axis) \\ \\    <2> Top-position (if -1 then the window is centered \\        On the Y-axis)\\ \\    <3> Width (-1 means do not adjust the window width)\\ \\    <4> Height (-1 means do not adjust the window \\        height)\\ 



All these values default to -1.

They must be in the same scale units as the form being centered.

CalculateOnlyNo If TRUE$ then the form is not moved or resized, but the resulting coordinates are returned instead. Defaults to FALSE$.
ParentSize No This is an @Fm-delimited array that can be used to override the size of the parent (if CenterParent is TRUE$), or the Desktop (if CenterParent is FALSE$).

\\    <1> Left-position \\    <2> Top-position\\    <3> Width\\    <4> Height\\ 



They must be in the same scale units as the form being centered.

Options No This is an @Fm-delimited array of options structured like so:

\\    <1> Force boundary check.  If this is TRUE$ then\\        the form is kept within the boundary of the\\        desktop even if the IdealSize Top and Left\\        positions have been explicitly specified.\\ \\    <2> Desktop "anchor" form.  Contains the name of \\        a form to use when deciding which monitor to \\        center the form on.  The form is centered \\        on the same desktop as the anchor form.\\ 

Returns

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

Remarks

N/a.

Example

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

See Also

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

Description

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

Syntax

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

MaintainFocus )

Parameters

Name RequiredDescription
SaveKey No This is a boolean value. If TRUE$ then the controls bound to key columns will not be cleared. The default is FALSE$.
SuppressWarningNo This is a boolean value. If TRUE$ then the user will not be warned if they have unsaved changes in the form before it is cleared. The default is FALSE$.
MaintainFocus No This is a boolean value. If TRUE$ then the focus is not moved. By default it is moved to the first control in the tab-order.

Returns

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

Remarks

N/a.

Example

 // 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$ )
 

See also

WINDOW CLEAR event.

Description

Closes a form by triggering its CLOSE event.

Syntax

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

Parameters

Name RequiredDescription
CloseFlagsNo This is an @Fm delimited array with the following structure:

\\    <1> If TRUE$ then suppress any warnings with \\        due to changed data if the form is data-\\        bound.\\ 
CloseAsyncNo This is a boolean value. If TRUE$ then the form is closed in an asynchronous manner. The default is FALSE$.

(This is analogous to using Send_Event or Post_Event to trigger a CLOSE event in previous versions of OpenInsight)

Returns

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

Remarks

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

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

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

See also

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

Description

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

Syntax

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

Parameters

Name RequiredDescription
RetValNo Value to return to the caller.

Returns

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

Remarks

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

Example

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

See Also

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

Description

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

Syntax

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

Parameters

Name RequiredDescription
CommonNameYes Name of the common area to attach.
bFree No If TRUE$ then the common area will be freed after it has been detached.

Returns

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

Remarks

N/a.

Example

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

See Also

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

Description

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

Syntax

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

Parameters

Name RequiredDescription
SuppressWarningNo This is a boolean value. If TRUE$ then the user will not be asked to confirm if they wish to delete the row. The default is FALSE$.

Returns

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

Remarks

N/a.

Example

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

See also

WINDOW DELETE event.

Description

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

Syntax

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

FlashTaskBar , FlashRate )

Parameters

Name RequiredDescription
FlashCount No An integer value specifying the number of times to flash the form, or flash it continuously (defaults to 1)

* A value greater than 0 flashes it that many times.
* A value of -1 flashes the form until it is stopped.
* A value of -2 flashes the form until it is brought to the foreground.
* A value of 0 stops the form flashing.
FlashCaptionNo A boolean value – if TRUE$ (the default) the form's caption bar is flashed.
FlashTaskBarNo A boolean value – if TRUE$ (the default) the form's taskbar button is flashed (if it has one).
FlahsRate No A integer value specifying the flash rate in milliseconds. This defaults to the system cursor blink rate.

Returns

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

Remarks

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

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

See also

WINDOW ACTIVE property.

Description

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.

Syntax

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

Parameters

Name RequiredDescription
NoInternalNo If TRUE$ then only controls not marked as "Internal" will be returned. Defaults to FALSE$.

Returns

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

Remarks

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.

Example

 
 $Insert Logical
 
 // Return the focused control for the current form, resolving it to a non-internal ID.//
 FocusCtrlID = Exec_Method( @Window, "GETFOCUSEDCONTROL", TRUE$ )
 

See Also

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

Description

Hides a form using the specified effect.

Syntax

Call Exec_Method( CtrlEntID, "HIDE", HideEffect )

Parameters

Name RequiredDescription
HideEffectNo If specified this should be a numeric value corresponding to a hide effect as defined in the HIDEEFFECT property.

If null or "-1" then the effect specified in the HIDEEFFECT property is used.

Returns

N/a.

Remarks

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

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

See Also

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

Description

Hides the menubar for the specified form.

Syntax

Call Exec_Method( CtrlEntID, "HIDEMENUBAR" )

Parameters

N/a.

Returns

N/a.

Remarks

N/a.

Example

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

See Also

MENUBAR object, WINDOW SHOWMENUBAR method

Description

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

Syntax

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

Parameters

Name RequiredDescription
SkipDisabledNo This is a boolean value - if TRUE$ then any disabled MDI child forms are excluded from the cascade operation.
UseZOrder No This is a boolean value - if TRUE$ then the MDI Child forms are arranged in z-order.

Returns

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

Remarks

This method only applies to MDI frame forms.

Example

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

See Also

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

Description

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

Syntax

SuccessFlag = Exec_Method( CtrlEntID, "MDIICONARRANGE" )

Parameters

N/a.

Returns

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

Remarks

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.

Example

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

See Also

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

Description

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.

Syntax

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

Parameters

Name RequiredDescription
TileHorizontalNo This is a boolean value - if TRUE$ then the MDI Child forms are tiled horizontally, otherwise they are tiled vertically.
SkipDisabled No This is a boolean value - if TRUE$ then any disabled MDI child forms are excluded from the tiling operation.

Returns

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

Remarks

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.

Example

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

See Also

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

Description

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

Syntax

Status = Exec_Method( CtrlEntID, "QBFASKQUERY" )

Parameters

N/a.

Returns

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

Remarks

This method triggers the form's QBFQUERY event.

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

Example

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

See also

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

Description

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

Syntax

Status = Exec_Method( CtrlEntID, "QBFCLOSESESSION" )

Parameters

N/a.

Returns

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

Remarks

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

Example

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

See also

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

Description

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

Syntax

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

Parameters

Name RequiredDescription
PositionNo This is a numeric value which should be between 1 and the number of rows in the QBF result list.

If not specified, the user is asked to enter the position via a message box.

Returns

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

Remarks

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

 // 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
 

See also

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

Description

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

Syntax

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

Parameters

Name RequiredDescription
RowIDNo This is key value that should be in the QBF result list.

If not specified, the user is asked to enter it directly via a message box.

Returns

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

Remarks

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

 // 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
 

See also

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

Description

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.

Syntax

Status = Exec_Method( CtrlEntID, "QBFINITSESSION" )

Parameters

N/a.

Returns

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

Remarks

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

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

See also

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

Description

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.

Syntax

Status = Exec_Method( CtrlEntID, "QBFLOADSAVEDLIST" )

Parameters

N/a.

Returns

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

Remarks

This method triggers the form's QBFLOADLIST event.

Example

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

See also

WINDOW QBFLIST property, WINDOW QBFLOADLIST event.

Description

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

Syntax

Status = Exec_Method( CtrlEntID, "QBFRUNQUERY" )

Parameters

N/a.

Returns

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

Remarks

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

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

See also

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

Description

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

Syntax

Status = Exec_Method( CtrlEntID, "QBFSHOWFIRST" )

Parameters

N/a.

Returns

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

Remarks

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

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

See also

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

Description

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

Syntax

Status = Exec_Method( CtrlEntID, "QBFSHOWLAST" )

Parameters

N/a.

Returns

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

Remarks

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

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

See also

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

Description

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

Syntax

Status = Exec_Method( CtrlEntID, "QBFSHOWNEXT" )

Parameters

N/a.

Returns

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

Remarks

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

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

See also

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

Description

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

Syntax

Status = Exec_Method( CtrlEntID, "QBFSHOWPREV" )

Parameters

N/a.

Returns

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

Remarks

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

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

See also

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

Description

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.

Syntax

Status = Exec_Method( CtrlEntID, "QBFSHOWTABLE" )

Parameters

N/a.

Returns

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

Remarks

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

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

See also

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

Description

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

Syntax

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

Parameters

Name RequiredDescription
ControlListNo If specified this an @Fm-delimited array of data-bound control names that should be loaded from the cached data.

If this parameter is null then all data-bound controls will be loaded from the cached data.

Returns

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

Remarks

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

     
 // 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
 

See Also

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

Description

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

Syntax

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

Parameters

Name RequiredDescription
RowID No If specified this is the ID of the row to be loaded into the form.

For a multi-table form RowID should be an @fm-delimited array of keys that matches the order of the tables in the form's join specification:

i.e.

\\   rowID<1> = Key for primary table\\   rowID<2> = Key for first subsidiary table\\   rowID<3> = Key for second subsidiary table\\   rowID<n> = Key for nth subsidiary table \\ 



etc.

If null (the default) then the data entered in the key-controls is extracted to build the RowID used to load the row.

SuppressWarningNo If TRUE$ then the SAVEWARN property is not checked before a new row is loaded when rowID is specified.

The default is FALSE$, which means the SAVEWARN property will be processed as normal.

This parameter is ignored is RowID is null.

Returns

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

Remarks

This method triggers the form's READ event.

Example

     
 // 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
 

See Also

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

Description

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

Syntax

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

Parameters

Name RequiredDescription
XShiftYes Integer value specifying the amount of horizontal scrolling.
YShiftYes Integer value specifying the amount of vertical scrolling.

Returns

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

Remarks

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

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

See Also

N/a.

Description

Displays a form using the specified effect.

Syntax

Call Exec_Method( CtrlEntID, "SHOW", ShowEffect )

Parameters

Name RequiredDescription
ShowEffectNo If specified this should be a numeric value corresponding to a show effect as described in the SHOWEFFECT property.

If null or "-1" then the effect specified in the SHOWEFFECT property is used.

Returns

N/a.

Remarks

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

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

See Also

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

Description

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

Syntax

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

Options, AsyncParams )

Parameters

Name RequiredDescription
DialogName Yes Name of the form to execute as a dialog box. Must be in upper-case.
CreateParamNo Data to pass to the form's CREATE event. This data is passed as the "CreateParam" argument when the CREATE event is triggered. It must not contain any @Rm system delimiter characters.
Options No A dynamic array of extra options for launching the form:

<1> If TRUE$ then disable ALL other forms owned by

the owner form, not just the owner form itself.

<2> GETPARENTFORM override. The Dialog_Box stored

procedure uses the WINDOW object GETPARENTFORM

method internally. This option allows it to be

tweaked as desired.
AsyncParamsNo A dynamic array of options that control Asynchronous mode. When executed in this mode the returned data is not passed directly back to the calling stored procedure – rather it is passed back via the owner's ENDDIALOG event.

<1> If TRUE$ then the dialog will be executed in

Asynchronous mode.

<2> Contains a string argument passed back to the

owner's ENDDIALOG event. Useful for identifying

the returned data.

Returns

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.

Remarks

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

Example

     
 // 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
 

See Also

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

Description

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

Syntax

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

SearchColumns, DisplayColumns, SelMode )

Parameters

Name RequiredDescription
IndexedTable Yes The indexed table to search. This table must have at least one Btree Index on it.
SearchColumns Yes Contains an @Fm-delimited list of column names to display in the dialog that the user may search.
DisplayColumnsYes Contains an @Fm-delimited list of columns names to show in the results popup when a user chooses the row(s) to load into the form.
SelMode No Contains an @fm delimited list of selection options:

\\   <1> Mode – this can be either "MULTI" or\\       "SINGLE" (the default).  If "MULTI"\\       then the user may select more than\\       one row to return.\\ \\   <2> Contains the name of the control to \\       return the selected row IDs to. If \\       null then the row IDs are loaded into\\       the form as a QBF result list.\\ \\       This can be a virtual name like "@WINDOW"\\       or "@SELF" that are used in normal quick\\       event programming.\\ \\   <3> If a control name is specified in\\       field <2> this field contains the name \\       of the property to set such as "TEXT"\\       \\ 

Returns

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

Remarks

This method triggers the form's IXLOOKUP event.

Example

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

See Also

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

Description

Shows the menubar for the specified form.

Syntax

Call Exec_Method( CtrlEntID, "SHOWMENUBAR" )

Parameters

N/a.

Returns

N/a.

Remarks

N/a.

Example

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

See Also

MENUBAR object, WINDOW HIDEMENUBAR method

Description

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

Syntax

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

MessageName )

Parameters

Name RequiredDescription
MessageStructMaybe This is an @Fm-delimited array that contains a message structure as per the Msg() stored procedure.

Required if MessageName is null.
MessageName Maybe Contains the name of an OpenInsight repository MSG entity to display. The fields in the MessageStruct parameter override the fields from the stored entity.

Required if MessageStruct is null.

Returns

The value as specified by the message definition.

Remarks

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

See also

SYSTEM SHOWMESSAGE method, Msg stored procedure.

Example

 // 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" )
 

See Also

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

Description

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

Syntax

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

Parameters

Name RequiredDescription
PopupStructNo Contains the popup definition structure. This is an @Fm-delimited array of values that define the popup as per the Popup stored procedure.

This parameter is required if PopupName is null.
MessageNameNo Contains the name of a valid POPUP entity as stored in the OpenInsight repository. This can be the fully qualified entity ID, or just the name of the popup, e.g.

\\    MYAPP*POPUP**MYPOPUP\\ 



or

\\    MYPOPUP\\ 



This parameter is required if PopupStruct is null.

Returns

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

Remarks

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

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

See Also

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

Description

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

Syntax

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

Parameters

Name RequiredDescription
FormName Yes Name of the form to execute. Must be in upper-case.
CreateParamNo Data to pass to the form's CREATE event. This data is passed as the "CreateParam" argument when the CREATE event is triggered.

Returns

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.

Remarks

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

Example

     
 // 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
 

See Also

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

Description

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

Syntax

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

AppearanceMode, InitX, InitY )

Parameters

Name RequiredDescription
FormName Yes Name of the child form to execute. Must be in upper-case.
CreateParam No Data to pass to the child form's CREATE event. This data is passed as the "CreateParam" argument when the CREATE event is triggered.
AppearanceModeNo Specifies how the child form should be displayed. Can be one of the following values:

\\    0 : Displays in the same way as the currently\\      : active child (this is the default)\\    1 : Normal\\    2 : Minimized\\    3 : Maximized\\ 
InitX No The initial X position of the child in the parent form's MDI Client area.
InitY No The initial Y position of the child in the parent form's MDI Client area.

Returns

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.

Remarks

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

     
 // 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$, "", "" )
 

See Also

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

Description

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.

Syntax

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

MenuStruct )

Parameters

Name RequiredDescription
MenuItemIDYes Contains the fully qualified name of the top-level menu item to "drop-down".
MenuStructYes A dynamic array containing the executable structure of the menu.

Note that this structure does not include the usual menu header fields.

Returns

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

Remarks

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.

Example

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

See also

Common GUI MENU event, WINDOW DROPDOWNMENU event.

Description

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

Syntax

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

Parameters

Name RequiredDescription
NewRowYes New data for the row.

Returns

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

Remarks

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

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

See Also

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

Description

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

Syntax

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

Parameters

Name RequiredDescription
RowIDNo If specified this is the ID to use when writing the data to the database. If this is different to the ID of the currently loaded row a "Save As" operation is performed, and the data in the key controls updated to reflect this.

For a multi-table form RowID should be an @fm-delimited array of keys that matches the order of the tables in the form's join specification:

i.e.

\\   rowID<1> = Key for primary table\\   rowID<2> = Key for first subsidiary table\\   rowID<3> = Key for second subsidiary table\\   rowID<n> = Key for nth subsidiary table \\ 



etc.

If null (the default) then the data entered in the key-controls is extracted to build the RowID used to write the row.

Returns

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

Remarks

This method triggers the form's WRITE event.

Example

     
 // 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
 

See Also

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

WINDOW Events

The WINDOW object supports the following events:

Name Description
ACTIVATED Occurs when a form is activated.
ARRANGEICONS Arranges all minimized MDI Child forms for an MDI frame form.
CASCADE Arranges all MDI Child forms into a cascading layout for an MDI frame form.
CLEAR Occurs when data is cleared from a data-bound form.
CLOSE Occurs when a form is being closed.
CREATE Occurs when a form is created.
DBLCLK Occurs when a user double-clicks the mouse on a form.
DELETE Occurs when data is cleared from a data-bound form.
DROPDOWNMENU Occurs when a top-level item on a form's menu bar is selected.
ENDDIALOG Occurs when an asynchronous dialog box returns a value to its owner form.
FORMSTATECHANGED Occurs when the "form state" of a form changes.
INACTIVATED Occurs when a form becomes inactive.
IXLOOKUP Occurs when a form shows an Index Lookup dialog box.
MDICHILDSTATECHANGEDOccurs when the "form state" of an MDI Child form changes.
MDISELECT Occurs when a user selects the "More Windows…" item from the "Window" menu on an MDI Frame form.
PAGE Pseudo-method used to change the current page of a form.
QBFABS Occurs when the form loads a row in a QBF result list using a position index.
QBFCLOSE Occurs when a form's QBF session is closed.
QBFFIRST Occurs when the form loads the first row in a QBF result list.
QBFINIT Occurs when a QBF session is started for a form.
QBFLAST Occurs when the form loads the last row in a QBF result list.
QBFLOADID Occurs when the form loads a row from the QBF result list using a specified key.
QBFLOADLIST Occurs when the form needs to obtain the name of a saved list of keys to load into its QBF result list.
QBFNEXT Occurs when the form loads the next row in a QBF result list.
QBFPREV Occurs when the form loads the previous row in a QBF result list.
QBFQUERY Occurs when the user wished to execute a "raw" QBF SELECT statement
QBFRUN Occurs when the form uses the entered query data to search the database and load the QBF result list.
QBFTABLE Occurs when a form's QBF result list is about to be displayed.
READ Occurs when data is read from the database into a data-bound form.
SCALED Occurs when the scaling factor of a form changes.
TILE Arranges all MDI Child forms into a tiled layout for an MDI frame form.
VISUALSTYLECHANGED Occurs when Window’s visual styling changes.
WRITE Occurs when data is written from a data-bound form to the database.

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

Description

Occurs when a form is activated.

Syntax

bForward = ACTIVATED( CtrlEntID, CtrlClassID )

Parameters

Name Description
CtrlEntID Fully qualified name of the form object receiving the event.
CtrlClassIDType of object receiving the event (always "WINDOW").

Returns

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

Remarks

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.

Example

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$

See Also

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

Description

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

Syntax

bForward = ARRANGEICONS( CtrlEntID, CtrlClassID )

Parameters

Name Description
CtrlEntID Fully qualified name of the form receiving the event.
CtrlClassIDType of object receiving the event (always "WINDOW")

.

Returns

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

Remarks

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.

Example

N/a.

See Also

WINDOW MDIICONARRANGE method.

Description

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

Syntax

bForward = CASCADE( CtrlEntID, CtrlClassID )

Parameters

Name Description
CtrlEntID Fully qualified name of the form receiving the event.
CtrlClassIDType of object receiving the event (always "WINDOW").

Returns

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

Remarks

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.

Example

N/a.

See Also

WINDOW MDICASCADE method.

Description

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

Syntax

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

bMaintainFocus )

Parameters

Name Description
CtrlEntID Fully qualified name of the form receiving the event.
CtrlClassID Type of object receiving the event (always "WINDOW").
bSaveKey This is a boolean value. If TRUE$ then the controls bound to key columns will not be cleared.
bSuppressWarningThis is a boolean value. If TRUE$ then the user will not be warned if they have unsaved changes in the form before it is cleared.
bMaintainFocus This is a boolean value. If TRUE$ then the focus is not moved. By default it is moved to the first control in the tab-order.

Returns

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

Remarks

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

Example

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$

See Also

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

Description

Occurs when a form is being closed.

Syntax

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

Parameters

Name Description
CtrlEntID Fully qualified name of the form receiving the event.
CtrlClassIDType of object receiving the event (always "WINDOW").
CancelFlag A boolean value used to check the response from SYSMSG calls. This is always set to FALSE$ when the CLOSE event is executed, it can be set to TRUE$ if the user cancels the CLOSE attempt.
CloseFlags This is an @Fm-delimited array with this following structure (currently there is only one field):

\\    <1> If TRUE$ then suppress SAVEWARN processing\\ 

Returns

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

Remarks

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

Example

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$

See Also

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

Description

Occurs when a form is created.

Syntax

bForward = CREATE( CtrlEntID, CtrlClassID, CreateParam )

Parameters

Name Description
CtrlEntID Fully qualified name of the form receiving the event.
CtrlClassIDType of object receiving the event (always "WINDOW").
CreateParamData passed from the method that created the form.

Returns

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

Remarks

There is no system level event handler for CREATE.

Example

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 )

See Also

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.

Description

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

Syntax

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

Parameters

Name Description
CtrlEntID Fully qualified name of the form receiving the event.
CtrlClassIDType of object receiving the event (always "WINDOW" ).
CtrlKey TRUE$ if the Ctrl key was pressed down when the double-click was triggered, FALSE$ otherwise.
ShiftKey TRUE$ if the Shift key was pressed down when the double-click was triggered, FALSE$ otherwise.
MouseButtonInteger specifying which mouse button was double-clicked:

"0" - Left button or middle button

"1" - Right button

Returns

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

Remarks

There is no system-level event handler for DBLCLK.

Example

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$

See Also

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

Description

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

Syntax

bForward = DELETE( CtrlEntID, CtrlClassID, bSuppressWarning )

Parameters

Name Description
CtrlEntID Fully qualified name of the form receiving the event.
CtrlClassID Type of object receiving the event (always "WINDOW").
bSuppressWarningThis is a boolean value. If TRUE$ then the delete operation should be unconditional, otherwise, the user will be warned about the delete and given the opportunity to cancel.

Returns

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

Remarks

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

Example

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$

See Also

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

Description

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.

Syntax

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

Parameters

Name Description
CtrlEntID Fully qualified name of the form object receiving the event.
CtrlClassIDType of object receiving the event (always "WINDOW").
MenuID Contains the fully qualified name of the top-level menu item to "drop-down".
MenuStruct A dynamic array containing the executable structure of the menu.

Note that this structure does not include the usual menu header fields.

Returns

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

Remarks

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.

Example

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$

See Also

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

Description

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

Syntax

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

Parameters

Name Description
CtrlEntID Fully qualified name of the form object receiving the event.
CtrlClassIDType of object receiving the event (always "WINDOW").
DialogID Name of the dialog box returning the value to its owner.
DialogValueValue returned from the dialog box to its owner.
AsyncID ID passed to the dialog box by its owner when it was created.

Returns

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

Remarks

There is no system-level event handler for ENDDIALOG.

Example

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$

See Also

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

Description

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

Syntax

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

Parameters

Name Description
CtrlEntID Fully qualified name of the form receiving the event.
CtrlClassIDType of object receiving the event (always "WINDOW").
EventSourceName of the event that triggered the form state change.
FormState An @Fm-delimited array of boolean flags that denote the proposed enabled state of various common menu and toolbuttons:

\\   <1>  Save\\   <2>  SaveAs\\   <3>  Clear\\   <4>  Delete\\   <5>  LoadPrevRow\\   <6>  Print\\   <7>  PrintPreview\\   <8>  Close\\   <20> QBFInit\\   <21> QBFRun\\   <22> QBFFirst\\   <23> QBFPrev\\   <24> QBFNext\\   <25> QBFLast\\   <26> QBFPosition\\   <27> QBFTable\\   <28> QBFLoadList\\   <29> QBFGetQuery\\   <30> QBFClose\\ 

Returns

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

Remarks

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.

Example

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$

See Also

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.

Description

Occurs when a form becomes inactive.

Syntax

bForward = INACTIVATED( CtrlEntID, CtrlClassID )

Parameters

Name Description
CtrlEntID Fully qualified name of the form receiving the event.
CtrlClassIDType of object receiving the event (always "WINDOW").

Returns

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

Remarks

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.

Example

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$

See Also

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

Description

Occurs when a form shows an Index Lookup dialog box.

Syntax

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

DisplayColumns, SelMode )

Parameters

Name Description
CtrlEntID Fully qualified name of the form receiving the event.
CtrlClassID Type of object receiving the event (always "WINDOW").
IndexedTable The indexed table to search. This table must have at least one Btree index on it.
SearchColumns Contains an @Fm-delimited list of column names to display in the dialog that the user may search.
DisplayColumnsContains an @Fm-delimited list of columns names to show in the results popup when a user chooses the row(s) to load into the form.
SelMode Contains an @fm delimited list of selection options:

\\   <1> Mode – this can be either "MULTI" or\\       "SINGLE" (the default).  If "MULTI"\\       then the user may select more than\\       one row to return.\\ \\   <2> Contains the name of the control to \\       return the selected row IDs to. If \\       null then the row IDs are loaded into\\       the form as a QBF result list.\\ \\       This can be virtual name like "@WINDOW"\\       or "@SELF" that are used in normal quick\\       event programming.\\ \\   <3> If a control name is specified in\\       field <2> this field contains the name \\       of the property to set such as "TEXT"\\       \\ 

Returns

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

Remarks

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.

Example

N/a.

See Also

WINDOW QBFLIST property, WINDOW SHOWINDEXLOOKUP method.

Description

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.

Syntax

bForward = MDICHILDSTATECHANGED( CtrlEntID, CtrlClassID, EventSource, |

FormState )

Parameters

Name Description
CtrlEntID Fully qualified name of the MDI Frame form receiving the event.
CtrlClassIDType of object receiving the event (always "WINDOW").
EventSourceName of the event that triggered the form state change.
FormState An @Fm-delimited array of boolean flags that denote the proposed enabled state of various common menu and toolbuttons – this is set by the originating FORMSTATECHANGED event:

\\   <1>  Save\\   <2>  SaveAs\\   <3>  Clear\\   <4>  Delete\\   <5>  LoadPrevRow\\   <6>  Print\\   <7>  PrintPreview\\   <8>  Close\\   <20> QBFInit\\   <21> QBFRun\\   <22> QBFFirst\\   <23> QBFPrev\\   <24> QBFNext\\   <25> QBFLast\\   <26> QBFPosition\\   <27> QBFTable\\   <28> QBFLoadList\\   <29> QBFGetQuery\\   <30> QBFClose\\ 

Returns

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

Remarks

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.

Example

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$

See Also

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

Description

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

Syntax

bForward = MDISELECT( CtrlEntID, CtrlClassID, activeID )

Parameters

Name Description
CtrlEntID Fully qualified name of the form receiving the event.
CtrlClassIDType of object receiving the event (always "WINDOW").
ActiveID Contains either:

* The name of the MDI Child form to activate, or
* "-1" (the default) to show the RTI_MDISELECT dialog box – this allows the user to select an MDI Child form to activate.

Returns

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

Remarks

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.

Example

N/a.

See Also

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

Description

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

Syntax

bForward = PAGE( CtrlEntID, CtrlClassID, PageAction )

Parameters

Name Description
CtrlEntID Fully qualified name of the form receiving the event.
CtrlClassIDType of object receiving the event (always "WINDOW").
PageAction May be one of the following values:

* An integer that specifies the page to display. If this is greater than the page count then the last page is displayed, of less than 1 then the first page is displayed.
* "+" means go to the next page, and do not wrap around to the first page if on the last page.
* "++" means go to the next page and wrap around to the first page if on the last page.
* "-" means go to the previous page and do not wrap around to the last page if on the first page.
* "–" means go to the previous page and wrap around to the last page if on the first page.
* "L" means go to the last page.

Returns

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

Remarks

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.

Example

N/a.

See Also

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

Description

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

Syntax

bForward = QBFABS( CtrlEntID, CtrlClassID, AbsPos )

Parameters

Name Description
CtrlEntID Fully qualified name of the form receiving the event.
CtrlClassIDType of object receiving the event (always "WINDOW").
AbsPos If specified this contains the index of the row to display (i.e. the "absolute" position).

If may also be null to allow the user to enter the index via a message box.

Returns

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

Remarks

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

Example

N/a.

See Also

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

Description

Occurs when a form's QBF session is closed.

Syntax

bForward = QBFCLOSE( CtrlEntID, CtrlClassID )

Parameters

Name Description
CtrlEntID Fully qualified name of the form receiving the event.
CtrlClassIDType of object receiving the event (always "WINDOW").

Returns

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

Remarks

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

Example

N/a.

See Also

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

Description

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

Syntax

bForward = QBFFIRST( CtrlEntID, CtrlClassID )

Parameters

Name Description
CtrlEntID Fully qualified name of the form receiving the event.
CtrlClassIDType of object receiving the event (always "WINDOW").

Returns

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

Remarks

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

Example

N/a.

See Also

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

Description

Occurs when QBF session is initialized for a form.

Syntax

bForward = QBFINIT( CtrlEntID, CtrlClassID )

Parameters

Name Description
CtrlEntID Fully qualified name of the form receiving the event.
CtrlClassIDType of object receiving the event (always "WINDOW").

Returns

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

Remarks

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

Example

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$

See Also

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.

Description

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

Syntax

bForward = QBFLAST( CtrlEntID, CtrlClassID )

Parameters

Name Description
CtrlEntID Fully qualified name of the form receiving the event.
CtrlClassIDType of object receiving the event (always "WINDOW").

Returns

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

Remarks

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

Example

N/a.

See Also

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

Description

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

Syntax

bForward = QBFLOADID( CtrlEntID, CtrlClassID, RowID )

Parameters

Name Description
CtrlEntID Fully qualified name of the form receiving the event.
CtrlClassIDType of object receiving the event (always "WINDOW").
RowID If specified this contains the ID of the row to display. It must be in the QBF result list.

If may also be null to allow the user to enter the ID via a message box.

Returns

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

Remarks

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

Example

N/a.

See Also

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

Description

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

Syntax

bForward = QBFLOADLIST( CtrlEntID, CtrlClassID )

Parameters

Name Description
CtrlEntID Fully qualified name of the form receiving the event.
CtrlClassIDType of object receiving the event (always "WINDOW").

Returns

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

Remarks

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.

Example

N/a.

See Also

WINDOW QBFLIST property, WINDOW QBFLOADSAVEDLIST method.

Description

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

Syntax

bForward = QBFNEXT( CtrlEntID, CtrlClassID )

Parameters

Name Description
CtrlEntID Fully qualified name of the form receiving the event.
CtrlClassIDType of object receiving the event (always "WINDOW").

Returns

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

Remarks

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

Example

N/a.

See Also

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

Description

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

Syntax

bForward = QBFPREV( CtrlEntID, CtrlClassID )

Parameters

Name Description
CtrlEntID Fully qualified name of the form receiving the event.
CtrlClassIDType of object receiving the event (always "WINDOW").

Returns

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

Remarks

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

Example

N/a.

See Also

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

Description

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

Syntax

bForward = QBFQUERY( CtrlEntID, CtrlClassID )

Parameters

Name Description
CtrlEntID Fully qualified name of the form receiving the event.
CtrlClassIDType of object receiving the event (always "WINDOW").

Returns

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

Remarks

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.

Example

N/a.

See Also

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

Description

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

Syntax

bForward = QBFRUN( CtrlEntID, CtrlClassID )

Parameters

Name Description
CtrlEntID Fully qualified name of the form receiving the event.
CtrlClassIDType of object receiving the event (always "WINDOW").

Returns

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

Remarks

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.

Example

N/a.

See Also

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

Description

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.

Syntax

bForward = QBFTABLE( CtrlEntID, CtrlClassID )

Parameters

Name Description
CtrlEntID Fully qualified name of the form receiving the event.
CtrlClassIDType of object receiving the event (always "WINDOW").

Returns

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

Remarks

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.

Example

N/a.

See Also

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

Description

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

Syntax

bForward = READ( CtrlEntID, CtrlClassID )

Parameters

Name Description
CtrlEntID Fully qualified name of the form receiving the event.
CtrlClassIDType of object receiving the event (always "WINDOW").

Returns

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

Remarks

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

Example

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$

See Also

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

Description

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

Syntax

bForward = TILE( CtrlEntID, CtrlClassID, Orientation )

Parameters

Name Description
CtrlEntID Fully qualified name of the form receiving the event.
CtrlClassIDType of object receiving the event (always "WINDOW").
OrientationBoolean value – TRUE$ to tile vertically, of FALSE$ to tile horizontally.

Returns

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

Remarks

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.

Example

N/a.

See Also

WINDOW MDITILE method.

Description

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.

Syntax

bForward = SCALED( CtrlEntID, CtrlClassID, OrigDpiX, OrigDpiY, OrigScaleFactor, |

NewDpiX, NewDpiY, NewScaleFactor )

Parameters

Name Description
CtrlEntID Fully qualified name of the form receiving the event.
CtrlClassID Type of object receiving the event (always "WINDOW").
OrigDpiX X DPI value before the scale change took place.
OrigDpiY Y DPI value before the scale change took place.
OrigScaleFactorCustom scaling factor before the scale change took place.
NewDpiX X DPI value after the scale change took place.
NewDpiY Y DPI value after the scale change took place.
NewScaleFactor Custom scaling factor after the scale change took place.

Returns

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

Remarks

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.

Example

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$

See Also

SYSTEM DPI property, WINDOW DPI property, WINDOW SCALEFACTOR property, Appendix K – High DPI Programming.

Description

Occurs when Window’s visual styling changes, usually in response to the user changing colors in the Personalization Settings.

Syntax

bForward = VISUALSTYLECHANGED( CtrlEntID, CtrlClassID )

Parameters

Name Description
CtrlEntID Fully qualified name of the form object receiving the event.
CtrlClassIDType of object receiving the event (always "WINDOW").

Returns

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

Remarks

There is no default event handler for the VISUALSTYLECHANGED event.

This event is raised for the following Windows messages:

  • WM_DWMCOLORIZATIONCOLORCHANGED
  • WM_SYSCOLORCHANGE

Further information on these messages may be found on the Microsoft web site.

Example

N/a.

See Also

SYSTEM DWMCOLORS property, SYSTEM SYSTEMFONTS property, SYSTEM THEMED property, SYSTEM ALPHACOLOR method, SYSTEM DARKENCOLOR method, SYSTEM LIGHTENCOLOR method, SYSTEM MIXCOLORS method.

Description

Occurs when data is written from a data-bound form to the database.

Syntax

bForward = WRITE( CtrlEntID, CtrlClassID )

Parameters

Name Description
CtrlEntID Fully qualified name of the form receiving the event.
CtrlClassIDType of object receiving the event (always "WINDOW").

Returns

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

Remarks

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

  • Triggers a LOSTFOCUS event on the control with focus to ensure that any data it contains is properly validated. If there is a problem here the write operation is aborted.
  • Checks to see that all controls bound to a key part are filled. If not, the user is warned and the write operation is aborted.
  • Checks the see if all loaded data rows are locked. If not, the user is warned and the write operation is aborted.
  • Data is extracted from the data-bound controls into a "row-map" structure. This is then used to update the data row columns as necessary, and each row is then written back to the database after all its columns have been updated.
    • Note that using the ATRECORD or ROW properties, or the UPDATEROW method may cause data not bound to controls to be written back here as well – see the individual entries for those members for more details.
  • The SAVEWARN property is reset to FALSE$.
  • The NEWROW property is reset to FALSE$
  • The row-map is cached for use with the READPREVROW method and the ORIGROWVALUE property.
  • The form's caption is reset to it's default state.
  • If the CLEARONWRITE property is TRUE$ a CLEARROW method is executed to reset the form's data-bound controls to their default state.

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

  • From the LOSTFOCUS event when a new key has been entered and changes have also been made in the data-bound controls. The user is presented with a message which allows them to save the changes, which can then execute a write operation.

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

Example

Function WRITE( CtrlEntID, CtrlClassID )

 // Example - WRITE event script that performs some preliminary validation checks//
 // before allowing the WRITE event to proceed. If that's OK then update an audit //
 // log after the WRITE//
 $Insert RTI_SSP_Equates
 $Insert EvErrors
 
 IsOK = TRUE$
 GoSub DoTheChecks
 If ISOK Else
    // Failed the checks - warn the user and stop here//
    Call Exec_Method( @Window, "SHOWMESSAGE", "Err ... Computer says no" )
    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 WRITE in case we have a problem//
 Call Set_EventStatus( SETSTAT_OK$ )
 Call Forward_Event()
 If Get_EventStatus() Then
    // Assume error//
    Null
 End Else
    // Update the audit log...//
    Call Update_Some_Audit Log( @UserName : " updated " : TableID : " " : RowID )
  End
 
 // Return FALSE$ to stop the event chain as we've already forwarded to the//
 // system WRITE event handler above.//
 

Return FALSE$

See Also

Common GUI ORIGROWVAL property, WINDOW ATRECORD property, WINDOW ROW property, WINDOW SAVEWARN property, WINDOW CLEARROW method, WINDOW READPREVROW method, WINDOW WRITEROW method, WINDOW UPDATEROW method, Common GUI LOSTFOCUS event, WINDOW CLEAR event, WINDOW SYSMSG event.

  • guides/oi10/presentation_server_model/500_window_object.txt
  • Last modified: 2024/03/29 18:52
  • by 127.0.0.1