These properties apply to all object types (Intrinsic and User, GUI and non-GUI) except where noted in individual type descriptions later.

Gets or sets a string of user-defined data, using a custom property name. The property name is defined by the developer and must be prefixed with an '@' symbol. This string can be used for any purpose, and stays with the specified object until replaced by another string or the object is destroyed.

A string containing user defined data.

User-defined properties are a convenient way to store application-specific data against an object at runtime. There is no limit to number of user-defined properties for an object, and they exist for the lifetime of the object they are linked to.

Note that using the normal property interface (i.e. Get_Property and Set_Property) is not suitable for storing property values that contain binary data, i.e. data that contains Char(0) characters. In this case the GETUDP and SETUDP methods should be used instead.

  
 // Read a configuration record and cache its contents against the//
 // current window in an "@CONFIG" property.//
 
 Read CfgRec from @File_SysEnv, CfgID Then
    Call Set_Property_Only( @Window, "@CONFIG", CfgRec )
 End
 
 ...
 
 // At a later point when we want to retrieve the data ...//
 CfgData = Get_Property( @Window, "@CONFIG" )
 

Common MISC property, Common UDPLIST property, Common GETUDP method, Common SETUDP method.

Specifies if an object can accept the input focus.

A boolean value denoting if the object can accept the input focus.

In the majority of cases this property is Get-Only and is controlled by the Presentation Server. For example, STATIC controls can never accept the input focus and this property always returns FALSE$, while other controls, such as the TABCONTROL do allow this property to be set at design time, thereby allowing the developer more fine-grained control of their behavior. These cases are noted in the documentation for the object type.

Note that this property is not dependent on the ENABLED property, which can also stop an object receiving the input focus. An object that is disabled can still return TRUE$ from its ALLOWFOCUS property, as the ENABLED state is considered to be "temporary" and a property of the object instance, rather than its type.

  
 // See if we can give TAB_MAIN the focus before we try and move it there//
 
 If Get_Property( @Window : ".TAB_MAIN", "ALLOWFOCUS" ) Then
    Call Set_Property( "SYSTEM", "FOCUS", @Window : ".TAB_MAIN" )
 End  
 

SYSTEM FOCUS property, WINDOW FOCUS property, Common GUI GOTFOCUS event, Common GUI LOSTFOCUS event.

Allows a method to be executed via the Set_Property and Set_Property_Only functions.

A @Fm-delimited dynamic array of data containing the name of the method to call along with its parameters. The first field in the array is always the method name to execute (in uppercase).

<1> Method Name

<2> Param 1

<3> Param 2

<n> Param n-1

If any of the parameters are themselves dynamic arrays containing system delimiters they must be converted down a level before they are set, because the EXECMETHOD property handler will convert them back up a level before it executes the method.

This property exists as an optimization tool, to allow a set of methods to take advantage of the Property Concatenation feature (See Appendix A – Concatenating Properties) that allows two or more properties to be set with a single call to the Presentation Server.

    
 // EXECMETHOD property example – exec two methods using Set_Property//
 
 // Qualify the WM_SYSCOLORCHANGE message to detect if the user makes a //
 // theme change.//
 
 ObjxArray =       @Window
 PropArray =       "EXECMETHOD"
 DataArray =       "QUALIFYEVENT" : @Fm : WM_SYSCOLORCHANGE$ : @Fm : TRUE$
 
 // Trap the WM_RBUTTONDOWN message to detect mouse right clicks. Make the //
 // event synchronous so our context menus can be created before the //
 // ntext menu is generated.//
 
 ObjxArray := @Rm : @window
 PropArray := @Rm : "EXECMETHOD"       
 DataArray := @Rm : QUALIFYEVENT""      |
            : @Fm : WM_RBUTTONDOWN$     |
            : @Fm : TRUE$ : @Vm : "" : @Vm : "" : @Vm : TRUE$
 
 Call Set_Property_Only( ObjxArray, PropArray, DataArray )
 

Exec_Method stored procedure, Appendix A – Concatenating Properties.

Specifies if an object is flagged as "internal".

A boolean value denoting if the object is flagged as "internal".

Some PS objects, such as the cell editor control in an EDITTABLE, are marked as "internal", which means that they are essentially owned and controls by the PS and are not intended to be referenced for general use outside of system calls. This property denotes if this is the case.

  
// Check the current focus and see if it's an internal object...//

FocusCtrl = Get_Property( "SYSTEM", "FOCUS" )
If BLen( FocusCtrl ) Then
   IsInternal = Get_Property( FocusCtrl, "INTERNALOBJECT" )
   If IsInternal Then
      // Get the parent//
      FocusCtrl = Get_Property( FocusCtrl, "PARENT" )
   End
End
 

WINDOW GETFOCUSEDCONTROL method.

Gets or sets a string of user-defined data. This string can be used for any purpose and stays with the specified object until replaced by another string.

A string containing user defined data.

MISC is a convenient way to store application-specific data against an object at design time as well as runtime. If MISC is not sufficient then more data can be stored against an object at runtime using a UDP (User-Defined Property), also known as an '@' Property.

    
 // MISC property example//
 
 $Insert Logical
 
 // Save some data in the MISC property of the SYSTEM object//
 Call Set_Property_Only( "SYSTEM", "MISC", UserSettings )
 
 // Save customer data in the MISC property of the current //
 // window//
 Call Set_Property_Only( @Window, "MISC", CustomerData )
 
 // Do some processing ...//

…and retrieve the data from MISC

 CustomerData = Get_Property( @Window, "MISC" )     
 

Common '@' Properties.

Returns the repository type classification for the specified object. Used internally as part of the Presentation Server event-dispatching mechanism.

The REPOSTYPE property is a two-part string composed of the Application ID and the Application Type, delimited by an "*" character.

e.g.

SYSPROG*OIWIN

EXAMPLES*OIWIN

This property was originally called REPOS_TYPE in versions of OpenInsight prior to version 10. The old name is still supported for backwards compatibility.

 
 // REPOSTYPE Example//
 ReposType = Get_Property ( @Window, "REPOSTYPE" )   
 

N/a.

Returns the Presentation Server type classification of the specified object.

A string containing the type of the object, such as "EDITBOX", "PUSHBUTTON" and so on.

N/a.

 
 // TYPE Example//
 Type = Get_Property ( @Window, "TYPE" )   
 

Common TYPECLASS property, SYSTEM TYPES property.

Returns the Presentation Server Type and Class classification of the specified object.

A string containing the TYPE of the object, followed by its class (if it has one), both delimited by a "." character.

Not all objects have a CLASS attribute so in these instances some instances the TYPECLASS is the same as the TYPE property.

The class portion of an OLECONTROL control contains its GUID or ProgID, while the class portion of a WINCONTROL contains its Windows ClassName.

    
 // TYPECLASS example - OLECONTROL controls return a TYPECLASS//
 // specifier with the GUID/ProgID contained in the CLASS portion//
 
 OleTypeClass = Get_Property( @Window : ".OLE_WEBBROWSER", "TYPECLASS" )
 OleClass  = Field( OleTypeClass, ".", 2, 999 )
    

Common TYPE property, OLECONTROL object, WINCONTROL object.

Returns a list of user defined ("@") property names that have been set for an object.

An @Fm delimited list of user-defined property names.

N/a.

    
 // UDPLIST property example//
 // //
 // Set some User defined properties for the current window and //
 // use the UDPLIST property to check what has been set ...//
 
 $Insert Logical
 
 Call Set_Property_Only( @Window, "@_LOCKED", TRUE$ )
 Call Set_Property_Only( @Window, "@_ID", CustomerID )
 
 UdpIDs = Get_Property( @Window, "UDPLIST" )
 
 // UdpIDs contains the following @fm-delimited list://
 ////
 // <1> @_LOCKED//
 // <2> @_ID//
 

Common '@' (User-defined) property, Common GETUDP method, Common SETUDP method.

These methods apply to all object types (Intrinsic and User, GUI and non GUI) except where noted in individual type descriptions later.

Retrieves a user-defined string of binary data that has been stored with the SETUDP method using a custom property name. The property name is defined by the developer and must be prefixed with an '@' symbol. This string can be used for any purpose, and stays with the specified object until replaced by another string or the object is destroyed.

PropValue = Exec_Method( CtrlEntID, "GETUDP", PropName )

The stored property data.

The normal property API (i.e. the Get_Property and Set_Property functions) do not allow binary data to be stored, because any data will be truncated at the first char(0) character encountered (normal property values are usually processed as null-terminated strings). In this case the GETUDP and SETUDP methods can be used to store binary values instead, as they treat the passed value as a length-encoded block.

Note that a user-defined property value set with Set_Property can only be retrieved with Get_Property, and likewise the GETUDP method can only be used to retrieve a property set with the SETUDP method. The two interfaces are not interchangeable.

 // Store some binary data in a UDP and retrieve it//
 
 OSRead BinData From "c:\temp\mydata.dat" Else
    // Handle error//
 End
 
 // Store the data//
 Call Exec_Method( @Window, "SETUDP", "@_MYDATA", BinData )
    
 // ... processing etc ...//
    
 // Get the data//
 BinData = Exec_Method( @Window, "GETUDP", "@_MYDATA" )
        

Common '@' (User-defined) property, Common UDPLIST property, Common SETUDP method.

Asynchronously triggers an event for the specified object by adding it to the Presentation Server's event queue.

SuccessFlag = Exec_Method( CtrlEntID, "POSTEVENT", Event, |

Param1, Param2, Param3, Param4, Param5, |

Param6, Param7, Param8, Param9, Param10 )

A boolean value – TRUE$ if the event was added to the queue successfully or FALSE$ otherwise.

This method uses the Post_Event stored procedure internally. Its primary function is to provide a generic way of triggering events using the PS object API rather than using a "raw" Post_Event call.

 
 // Example - trigger the current form's OMNIEVENT CHECK_ITEMS event,//
 
 IsOK = Exec_Method( @Window, "POSTEVENT", "OMNIEVENT", "CHECK_ITEMS" )
                 

Common SENDEVENT method, Get_EventStatus stored procedure, Post_Event stored procedure, Send_Event stored procedure.

Enables or disables the processing of a specified event for an object.

PrevQualInfo = Exec_Method( CtrlEntID, "QUALIFYEVENT", EventID, NewQualInfo )

The previous event qualifier information before any adjustments are made. This can be used with a subsequent call to QUALIFYEVENT to reset the default processing.

If the EventID is numeric then it is assumed that we are qualifying a Windows Message – refer to the Common GUI QUALIFYWINMSG method for more details.

Setting the "Qualifier String" allows the system to use a different event script at runtime rather than the default one. This can be useful when centralizing code – a script may be written once and then other controls may be "redirected" to use it. A qualifier string is defined by two parts, delimited by a "*" character. These are:

1. The number of arguments the event expects (including the object name and class), and
2. The ID of a SYSREPOSEVENTEXES object code record to execute when the event is fired.

E.g.

>   
> 
> 3*SYSPROG*CLOSE.WINDOW.OIWIN*
> 
> ^ ^ ^
> 
> | | |
> 
> | |-------------------------|
> 
> | |
> 
> | OIEventExeID
> 
> ArgCount

Setting the "Event Name" allows the system to fire a specific named event when the message is received rather than simply calling the same event. This is mainly for use with OLE and WINMSG events (see the QUALIFYWINMSG and QUALIFYOLEEVENT methods for more details).

Setting the "SyncFlags": Normal PS event processing is executed in an asynchronous fashion, which means it is placed in a queue and run when the PS checks its message queue. However, events can also be executed synchronously using one of two methods: "Basic Sync" or "Callback Sync".

In Basic Sync mode the PS attempts to execute the event as soon as it is notified. However, if it is busy processing a previously executed event then the new one cannot be processed and will be discarded.

In Callback Sync mode the PS attempts to execute the event as soon as it is notified. However, if it is busy processing a previously executed event then it checks to see if that one is in a "wait-state", i.e. it Basic+ has called back into the PS through use of something like a Set_Property call and is waiting for the PS to respond. This can happen if setting the property generates a Windows notification message which triggers a PS event – the event can be raised before the Set_Property call returns. Using the Callback mode is generally a better idea than the simple Synchronous mode.

In previous versions of OpenInsight this method was called QUALIFY_EVENT. That name may still be used to preserve backwards compatibility.

 // Example : Redirect the CHAR event of EDL_DATA2 to use the CHAR event script //
 //         : of EDL_DATA1//
 
 QualInfo = Exec_Method( @Window : ".EDL_DATA1", "QUALIFYEVENT", "CHAR" )
 Call Exec_Method(  @Window : ".EDL_DATA2", "QUALIFYEVENT", "CHAR", QualInfo )
 
 
 // Example : Turn off the CHANGED event processing of EDL_DATA3 and restore it //
 //         : again.//
 
 QualInfo = Exec_Method( @Window : ".EDL_DATA3", "QUALIFYEVENT", "CHANGED", FALSE$ )
 
 ////
 // .. Do some processing ...//
 // //
 
 Call Exec_Method( @Window : ".EDL_DATA3", "QUALIFYEVENT", "CHANGED", QualInfo )
                             

Common GUI QUALIFYWINMSG method, OLECONTROL QUALIFYOLEEVENT method

Triggers an event for the specified object.

Status = Exec_Method( CtrlEntID, "SENDEVENT", Event, |

Param1, Param2, Param3, Param4, Param5, |

Param6, Param7, Param8, Param9, Param10 )

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

This method uses the Send_Event stored procedure internally. Its primary function is to provide a generic way of triggering events using the PS object API rather than using a "raw" Send_Event call.

 
 // Example - trigger the current form's OMNIEVENT CHECK_ITEMS event,//
 
 Status = Exec_Method( @Window, "SENDEVENT", "OMNIEVENT", "CHECK_ITEMS" )
                 

POSTEVENT method, Get_EventStatus stored procedure, Post_Event stored procedure, Send_Event stored procedure.

Stores a user-defined string of binary data using a custom property name. The property name is defined by the developer and must be prefixed with an '@' symbol. This string can be used for any purpose, and stays with the specified object until replaced by another string or the object is destroyed.

Call Exec_Method( CtrlEntID, "SETUDP", PropName, PropValue )

N/a.

The normal property API (i.e. the Get_Property and Set_Property functions) do not allow binary data to be stored, because any data will be truncated at the first char(0) character encountered (normal property values are usually processed as null-terminated strings). In this case the GETUDP and SETUDP methods can be used to store binary values instead, as they treat the passed value as a length-encoded block.

Note that a user-defined property value set with Set_Property can only be retrieved with Get_Property, and likewise the GETUDP method can only be used to retrieve a property set with the SETUDP method. The two interfaces are not interchangeable.

 // Store some binary data in a UDP and retrieve it//
 
 OSRead BinData From "c:\temp\mydata.dat" Else
    // Handle error//
 End
 
 // Store the data//
 Call Exec_Method( @Window, "SETUDP", "@_MYDATA", BinData )
    
 // ... processing etc ...//
    
 // Get the data//
 BinData = Exec_Method( @Window, "GETUDP", "@_MYDATA" )
        

Common '@' (User-defined) property, Common UDPLIST property, Common GETUDP method.