Common Properties [Revelation On-Line Wiki]

This page is read only. You can view the source, but not change it. Ask your administrator if you think this is wrong.
This section describes the properties, methods and events that are common to all PS object in the system, regardless of whether or not they are GUI based.

{{050__common_object_api_image_1.png?256x256}}

====== Common Properties ======

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

^Name           ^Description                                                         ^
|'@'            |Denotes a User Defined Property (UDP).                              |
|ALLOWFOCUS     |Specifies if the object can receive focus.                          |
|EXECMETHOD     |Optimization for calling methods using the property mechanism.      |
|INTERNALOBJECT |Specifies if the object is flagged as "internal"                    |
|MISC           |Specifies miscellaneous data for the object.                        |
|NAME           |Returns the object name.                                            |
|QUALIFIEDEVENTS|Returns a list of all events qualified for the object.              |
|REPOSTYPE      |Returns the Repository Type of the object.                          |
|PSSTYLE        |Returns the PS Style flags for an object.                           |
|PSSTYLEN       |Returns the PS Style flags for a object in numeric format.          |
|PSSTYLEEX      |Returns the extended PS Style flags for an object                   |
|PSSTYLEEXN     |Returns the extended PS Style flags for an object in numeric format.|
|TYPE           |Returns the Type of the object.                                     |
|TYPECLASS      |Returns the Type and sub-type (class) of the object.                |
|UDPLIST        |Returns a list of user-defined (UDP or '@') properties.             |



===== '@' (User-defined) property =====

=== Description ===

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.

=== Property Value ===

A string containing user defined data.

=== Property Traits ===

^//Development//^//Runtime//^//Indexed//^//Scaled//^//Synthetic//^
|N/a            |Get/Set    |No         |No        |No           |

=== Remarks ===

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.

=== Example ===

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

=== See Also ===

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

===== ALLOWFOCUS property =====

=== Description ===

Specifies if an object can accept the input focus.

=== Property Value ===

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

=== Property Traits ===

^//Development//^//Runtime//^//Indexed//^//Scaled//^//Synthetic//^
|Get            |Get        |No         |No        |No           |

=== Remarks ===

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

=== Example ===

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

=== See Also ===

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

===== EXECMETHOD property =====

=== Description ===

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

=== Property Value ===

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.

=== Property Traits ===

^//Development//^//Runtime//^//Indexed//^//Scaled//^//Synthetic//^
|N/a            |Set        |No         |No        |No           |

=== Remarks ===

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.

=== Example ===

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

=== See Also ===

Exec_Method stored procedure, Appendix A – Concatenating Properties.



===== INTERNALOBJECT property =====

=== Description ===

Specifies if an object is flagged as "internal".

=== Property Value ===

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

=== Property Traits ===

^//Development//^//Runtime//^//Indexed//^//Scaled//^//Synthetic//^
|N/a            |Get        |No         |No        |No           |

=== Remarks ===

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.

=== Example ===

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

=== See Also ===

WINDOW GETFOCUSEDCONTROL method.



===== MISC property =====

=== Description ===

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.

=== Property Value ===

A string containing user defined data.

=== Property Traits ===

^//Development//^//Runtime//^//Indexed//^//Scaled//^//Synthetic//^
|Get/Set        |Get/Set    |No         |No        |No           |

=== Remarks ===

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.

=== Example ===

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

=== See Also ===

Common '@' Properties.

===== REPOSTYPE property =====

=== Description ===

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

=== Property Value ===

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

=== Property Traits ===

^//Development//^//Runtime//^//Indexed//^//Scaled//^//Synthetic//^
|n/a            |Get        |No         |No        |No           |

=== Remarks ===

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

=== Example ===

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

=== See Also ===

N/a.

===== TYPE property =====

=== Description ===

Returns the Presentation Server type classification of the specified object.

=== Property Value ===

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

=== Property Traits ===

^//Development//^//Runtime//^//Indexed//^//Scaled//^//Synthetic//^
|n/a            |Get        |No         |No        |No           |

=== Remarks ===

N/a.

=== Example ===

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

=== See Also ===

Common TYPECLASS property, SYSTEM TYPES property.

===== TYPECLASS property =====

=== Description ===

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

=== Property Value ===

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

=== Property Traits ===

^//Development//^//Runtime//^//Indexed//^//Scaled//^//Synthetic//^
|n/a            |Get        |No         |No        |No           |

=== Remarks ===

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.

=== Example ===

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

=== See Also ===

Common TYPE property, OLECONTROL object, WINCONTROL object.

===== UDPLIST property =====

=== Description ===

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

=== Property Value ===

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

=== Property Traits ===

^//Development//^//Runtime//^//Indexed//^//Scaled//^//Synthetic//^
|n/a            |Get        |No         |No        |No           |

=== Remarks ===

N/a.

=== Example ===

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

=== See Also ===

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

====== Common Methods ======

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

^Name        ^Description                                               ^
|GETUDP      |Returns a binary format user-defined property (UDP).      |
|POSTEVENT   |Asynchronously triggers an event for the specified object.|
|QUALIFYEVENT|Modifies event processing for an object.                  |
|SENDEVENT   |Triggers an event for the specified object.               |
|SETUDP      |Stores a binary format user-defined property (UDP).       |

===== GETUDP Method =====

=== Description ===

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.

=== Syntax ===

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

=== Parameters  ===

^Name    ^Required^Description                                                                       ^
|PropName|Yes     |Name of the user-defined property to retrieve. This must begin with an "@" symbol.|

=== Returns ===

The stored property data.

=== Remarks ===

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.

=== Example ===

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

=== See also ===

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

===== POSTEVENT method =====

=== Description ===

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

=== Syntax ===

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

Param1, Param2, Param3, Param4, Param5, |

Param6, Param7, Param8, Param9, Param10 )

=== Parameters  ===

^Name                      ^Required^Description                                ^
|Event                     |Yes     |Specifies the name of the event to trigger.|
|Param1\\ \\ |\\ \\ Param10|No      |Event-specific parameters.                 |

=== Returns ===

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

=== Remarks ===

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

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

=== See also ===

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

===== QUALIFYEVENT Method =====

=== Description ===

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

=== Syntax ===

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

=== Parameters  ===

^Name       ^Required^Description^
|EventID    |Yes     |Name of the event to update. If this is numeric then it is assumed to be a Windows message ID instead – refer to the Common GUI QUALIFYWINMSG method for more details.|
|NewQualInfo|No      |An @Fm-delimited array that specifies how to update the event processing.\\ \\ <1> Enable Flag – TRUE$ to enable the event, FALSE$ to disable it. This field is required.  If set to TRUE$ then the following fields are also valid: \\ \\  <2> Qualifier String. Can contain the name of an event qualifier to execute rather than the default (See Remarks below for more details). This field is optional.\\ \\  <3> Event Name - May contain the name of a different event to execute (See Remarks below for more details). This field is optional.\\ \\  <4> SyncFlags – specifies the priority of the event. Can be one of the following values:\\ 0 : Asynchronous – the event is queued and executed as the queue is processed.  This is the default.\\ 1 : Basic Sync – the event is executed as soon as it is received. If this is not possible the event will be discarded.\\ 2 : Callback Sync– similar to Basic, except that the event will also be executed if the PS is in a "wait state". \\ \\ (See Remarks below for more details)|

=== Returns ===

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.

=== Remarks ===

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:

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

E.g.

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

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

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

=== See also ===

Common GUI QUALIFYWINMSG method, OLECONTROL QUALIFYOLEEVENT method

===== SENDEVENT method =====

=== Description ===

Triggers an event for the specified object.

=== Syntax ===

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

Param1, Param2, Param3, Param4, Param5, |

Param6, Param7, Param8, Param9, Param10 )

=== Parameters  ===

^Name                      ^Required^Description                                ^
|Event                     |Yes     |Specifies the name of the event to trigger.|
|Param1\\ \\ |\\ \\ Param10|No      |Event-specific parameters.                 |

=== Returns ===

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

=== Remarks ===

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

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

=== See also ===

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

===== SETUDP Method =====

=== Description ===

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.

=== Syntax ===

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

=== Parameters  ===

^Name     ^Required^Description                                                                                     ^
|PropName |Yes     |Name of the user-defined property to set. This must begin with an "@" symbol.                   |
|PropValue|No      |Value of the user defined property to set. This can be null (effectively removing the property).|

=== Returns ===

N/a.

=== Remarks ===

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.

=== Example ===

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

=== See also ===

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