Category Archives: Presentation Server

Contains posts about the OpenInsight Presentation Server, which is the module responsible for managing GUI windows and controls on the Windows Desktop.

Menu Designer update in v10.0.8

Version 10.0.8 has seen each of the Menu Designer tools (Form and Context) get a substantial overhaul, both to fix some bugs and also to improve their usability.  This post will provide a quick overview of what has changed.

The Context Menu Designer

ContextMenu Designer

Context Menu Designer

  • The “Item Properties” have been moved from the IDE Property Panel onto the designer itself, adjacent to the menu structure outline.  The previous layout needed far too much mouse movement between the items and their properties.
  • The ability to specify an image list for the menu has been added (this has always been supported at runtime but was not exposed via the Menu Design tools).
  • Re-added the “OI Menu” and “Windows Menu” options.
    • These are no longer global like they were in version 9.x, rather they are specific to the menu in question.
  • Added back the leading “-” symbol for items that don’t have an image as per version 9.
  • Added back the missing “F11” and “F12” Accelerator Key options
  • Improvements to the validation of item properties, e.g:
    • Better generation of default Item IDs.
    • Better checks for duplicate IDs.
    • Prevent events for POPUP item types.
    • A warning message when indenting/un-indenting items will change the parent item type (for example, indenting an item could cause the preceding ITEM to become a POPUP which would remove any existing event code from it).
  • Added “Shift-key” functionality to the buttons to control “insert before/after” operations (normal operation is “insert before”, pressing Shift changes them “insert after”), i.e:
    • Shift + Insert button for “insert after current item”.
    • Shift + Insert Separator button for “insert separator after current item”.
    • Shift + Paste button for “paste after current item”.
  • Added a full keyboard interface for the menu item structure list-box:
    • F2 (or Double-Click) to edit Item text in place.
    • Enter to insert a new item after the current item and move automatically into  “edit mode” (as per “F2” above).
      • Down arrow on the last item will insert a new item as per above.
      • Esc on a new “untouched” item will delete it.
    • Left key to shift an item and any sub-items to the left (un-indent).
    • Right key to shift an item and any sub-items to the right (indent).
    • Del key to delete items and their child items.
    • Ctrl-C to copy an item and it’s sub-items to the Windows Clipboard.
    • Ctrl-X to cut an item and it’s sub-items to the Windows Clipboard.
    • Ctrl-P to Paste items from the Windows Clipboard into the menu structure.
  • Added a context menu to the menu item structure listbox that duplicates the buttons, and adds the following operations:
    • Reset All Item IDs – processes the entire menu and changes all item IDs to their defaults based on their text and the name of their parent item.
    • Copy All – Copies all items to the Windows Clipboard – useful for duplicating menus from one form to another.
    • Delete All – Removes all items from the menu.
  • You are not asked to save the details for each item as you select items in the designer, but you will be prevented from moving to a different item if there is a validation failure.

The Form Menu Designer

Form Menu Designer

Form Menu Designer

Likewise the Form Menu designer has received the same treatment with a few additional extras:

  • A tab has been added for maintaining Event Scripts.
  • The events tab has colored indicators (orange and blue) to denote if an item has a QuickEvent or an Event Script.
  • More validation:
    • Prevent Separators being top-level items.
    • Prevent events for top-level items (unfortunately they are not supported by the Presentation Server in this version).
  • Syntax checking.
    • Syntax is automatically checked if you attempt to select another item – you will be prevented from moving to a different item if the check fails.

You should be able to catch these improvements in the next release, so please try them out and let us know how they work for you!

OpenInsight 10 and QuickEvent Processing

OpenInsight 10 introduced a couple of changes to how QuickEvents are processed that you may or may not be aware of, so in this post we’ll take a look at them so you can see how they work.

1) QuickEvent arguments are now passed by reference

In previous versions of OpenInsight, arguments passed to QuickEvents were duplicated and passed as copies, which meant that if you altered them in your Commuter Module you wouldn’t see the changes in the calling routine.  As QuickEvents are normally the last item processed in the event chain this is not something you might actually notice, unless perhaps you were using the Forward_Event() procedure from an Event Script.

Event arguments in version 10 are now passed by reference, which means a calling routine will see any changes you make to them.  This is an important point to bear in mind now that it’s possible to alter the order in which QuickEvents are executed in the event chain (see the “Has Priority” flag section below), so be careful when using those arguments in your Commuter Modules.

2) The new “Has Priority” flag

Under normal circumstances QuickEvents are always the last handlers processed in the event chain which normally looks something like this:

  1. Control-specific Event Script
  2. Promoted Events
  3. “System” Promoted Events
  4. QuickEvent

For most purposes this works fine, but there are occasions when you might need to step in front of the system code to do some pre-processing on events such as READ and WRITE, and unfortunately this usually involves writing an Event Script (or a Promoted Event perhaps) to contain your pre-system code like so:

E.g.  Sample pre-WRITE Event Script

Function WRITE( CtrlEntID, CtrlClassID )

   $Insert Logical
   WriteOK = TRUE$

   // Check if we can save the record - if not then WriteOK will be 
   // Set to FALSE$ which will stop the event chain
   GoSub CheckOKToWrite
 
Return WriteOK

However, this removes one of the main advantages of using Commuter Modules in the first place: i.e. the ability to keep all of your code in one place. To alleviate this you could just place your pre-WRITE code in your Commuter Module and call it directly :

Function WRITE( CtrlEntID, CtrlClassID )

   $Insert Logical

   // (Assume Commuter Module ID is the same name as the form with an 
   // "_EVENTS" suffix)
   CommID  = @window[1,"*"] : "_EVENTS"
   WriteOK = Function( @CommID( CtrlEntID, "PREWRITE" ) )
 
Return WriteOK

But then you’re still having to create the Event Script, so you still have a fragment that you need to track.

With version 10 we added a new flag to the QuickEvent handler called “Has Priority”:

QuickEvent definition showing the "Has Priority" flag set

“Has Priority” QuickEvent

If you set this to True the event chain is changed to this instead:

  1. Control-specific Event Script
  2. QuickEvent
  3. Promoted Events
  4. “System” Promoted Events

Which means that you can place something like a WRITE event handler in the Commuter Module, do your pre-processing, and return TRUE$ to allow the system to continue the chain, or use Forward_Event() if you need to do some post processing as well.

Points to note:

  • If you call Set_EventStatus( TRUE$ ) in your Commuter Module QuickEvent handler the event chain is stopped.
  • If you return FALSE$ (“0”) from your Commuter Module QuickEvent handler (and it has to be “0”, not null) the event chain is stopped.

Hopefully this removes the need for Event Scripts for writing pre-system events and should help to keep your applications a little more streamlined and organized, and preserve the benefits of using Commuter Modules.

What is the ENDDIALOG event?

If you’ve been using OpenInsight 10 one of the new features you may have noticed is that forms now have a new event called ENDDIALOG, and in this post we’ll take a brief look at how to use it.

The downsides of modal Dialog_Box programming

There are two primary issues with the classic Dialog_Box/End_Dialog style of programming:

  1. The system has to wait in a loop until the dialog is dismissed, and
  2. This forms a “stack” where the dialogs can only be closed in the order in which they were opened.

Historically the first issue was a bigger problem due to the fact that it tied up the engine thread and maxed out the CPU core it was running on.  This was resolved by moving the dialog “wait loop” into the Presentation Server in version 8, where it could be managed better and the engine thread would effectively “sleep” without consuming resources (prior to this it was a simple Basic+ For/Next loop – very processor intensive).

The second issue still remained however. While it may initially seem logical that modal dialogs should form a “stack” this actually breaks down when they are used from different top-level windows.

For example, suppose I have two instances of the IDE, and I load a modal dialog from the first instance and then another from the second instance.  I can’t close the first before I close the second as the Dialog_Box calls are stacked “inside” the engine.  This is potentially confusing behavior and likely to become a bigger issue if your development moves away from single MDI frames and multiple-monitor setups become more prevalent.

Dialog_Box programming without stacking

The only real way to solve this stacking problem is to break away from the current model of “synchronous” Dialog_Box programming and adopt an “asynchronous” callback model instead.  With this methodology there is no looping at all so the CPU usage stays low and code is only executed as needed, and because the loop is removed there is no stacking either.

The drawback of this approach, however, is that it complicates programming because your code has to be split up into two different sections; one to execute the dialog, and another to respond to the return value.

E.g. Consider a CLICK event handler using the normal approach:

OnClick:
   ... <prepare dialog args> ...
   RetVal = Dialog_Box( "MYDIALOG", DlgParent, DlgParam )
   ... <process RetVal> ...    
Return

… all nice and simple. To do this in an asynchronous fashion would take something like this:

   OnClick:
      ... <prepare dialog args> ...
      Call Dialog_Box( "MYDIALOG", DlgParent, DlgParam  )
   return
   

   OnSomeCallbackEvent:
      // param1 -> DialogID
      // param2 -> RetVal
      Begin Case
         Case ( Param1 == "MYDIALOG" )
            ... <process param2 (RetVal) > ...  
      End Case
   Return

… which is a little more complex.

This approach can actually be taken in any version of OpenInsight, but there’s no framework in place to enforce it and so it ends up needing even more work as the developer needs to find a way to define and target the callback process (E.g. implementing a custom event, using OMNIEVENT, calling a commuter module directly, and so on).

For version 10 we decided to provide that framework so that your code could be structured in a standardized fashion, resulting in some updates to the Dialog_Box and End_Dialog stored procedures and the addition of a new WINDOW event called ENDDIALOG.

Changes to Dialog_Box

Dialog_Box now accepts a new dynamic array argument called “AsyncParams”:

RetVal = Dialog_Box( DialogID, DlgParent, CreateParam, DlgOptions, AsyncParams )

Where AsyncParams is:

<1> An Async flag, to denote it needs to send it's return value to 
    the parent window's ENDDIALOG event

<2> A "cookie" value, which is a simple string passed to the ENDDIALOG 
    event that can be used to identify the returning dialog

e.g.

   AsyncParams    = TRUE$
   AsyncParams<2> = "wibble"

   RetVal = Dialog_Box( "MYDIALOG", DlgParent, DlgParam, "", AsyncParams )

Changes to End_Dialog

This procedure now checks to see if the dialog is in asynchronous mode, and if so it takes the dialog ID, the return value, and the cookie, and sends them to the parent’s ENDDIALOG event, thereby giving us a properly defined framework to implement the callback process.

(Note that the “parent” is considered to be the parent as specified in the originating Dialog_Box call, not the actual runtime PARENT, as these may not be the same thing!).

The new ENDDIALOG event

This event is called from the End_Dialog procedure and accepts three arguments:

DialogID  - name of the dialog that triggered the callback

ReturnVal - the dialog return value passed to End_Dialog

AsyncID   - the cookie value that was passed to Dialog_Box

Example

For the purposes of this example we assume that we are going to launch a simple form called “MY_DIALOG_BOX” using the Dialog_Box function.  The form contains a single EDITLINE control called “EDL_NAME”, and a button called “BTN_OK”.  When BTN_OK is clicked it will get the text from EDL_NAME and return it to the owner with an End_Dialog call like so:

   // CLICK event script for MY_DIALOG_BOX.BTN_OK

   // Get the data the user entered
   Name = Get_Property( @Window : ".EDL_NAME", "TEXT" )
   
   // Return it to the owner window
   Call End_Dialog( @Window, Name )

To launch MY_DIALOG_BOX in asynchronous fashion, do the following from an event on the owner window:

// Launches MY_DIALOG_BOX as a modal Dialog_Box in asynchronous fashion 
// passing it the contents of a variable called CurrName as the CreateParam.
   
AsyncParams = ""
AsyncParams<1> = TRUE$      ; // Async mode
AsyncParams<2> = "GetName"  ; // Optional “AsyncID” param for the 
                            ; // ENDDIALOG event
   
// This code does not halt here - anything the user selects in the dialog
// will be passed back in the ENDDIALOG event 
DlgID = Dialog_Box( "MY_DIALOG_BOX", @Window, CurrName, "", AsyncParams )

In this mode the calling program will NOT halt at the Dialog_Box call and wait for the user to close it. Instead any data returned from the End_Dialog call on MY_DIALOG_BOX.BTN_OK will be passed as an argument to the calling window’s ENDDIALOG event.

The ENDDIALOG event on the parent form would look something like this:

Function ENDDIALOG( CtrlEntID, CtrlClassID, DialogID, DialogValue, AsyncID )
 
// This is an ENDDIALOG event that will be triggered by the End_Dialog 
// call on MY_DIALOG_BOX.BTN_OK when launched in asynchronous mode,
//
// ENDDIALOG is passed three parameters:
//
//   DialogID 
//   DialogValue
//   AsyncID
   
Begin Case
   Case ( DialogID = "MY_DIALOG_BOX" )
      // This is optional but we can check AsyncID if we wanted to have
      //  more fine grain control over how this event is processed.
      If ( AsyncID == "GetName" ) Then
         Call Do_Something_With_This_Name( NewName )
      End
End Case 

Return 0

More details on using the ENDDIALOG event can be found in the online help for the Dialog_Box and End_Dialog procedures in version 10.

OLE Control improvements in v10.0.8

We added quite a bit of design-time functionality for OLE controls in v10.0.8 so this post provides a quick overview of what’s new:

The CLSID property

This property has a new “editor” dialog.  While it doesn’t allow you to change the CLSID (that’s by design – if you change the CLSID it’s a totally different control!) it does provide you with a lot of information about the control question such as it’s Registry attributes and it’s properties, methods and events, e.g:

OLE Control CLSID General Tab

OLE Control CLSID Properties Tab

OLE Control CLSID Methods Tab

OLE Control CLSID Events Tab

The QualifiedOleEvents property

This property has a new editor that allows you to specify which OLE events you wish to qualify when the control is created, hopefully removing the need for you to do this in code:

OLE Control QualifiedOleEvents Editor

The OLE Properties section

We’ve also added a new category called “OLE” to the properties displayed in the IDE Property Panel, and this contains all of the design-time OLE properties that can be edited for the control:

OLE Properties in the IDE Property Panel

You may also notice that we’ve added some property type-support for editing OLE properties here as well:

  • Color properties can now use the standard Color property editor
  • Fonts can now be edited with the standard Windows Font dialog
  • Enumerated types are edited with a dropdown list showing the “internal” and “external values, e.g:

OLE Enumerated Properties dropdown

Hopefully this will make working with OLE controls and OpenInsight 10 easier for you in the future.

Adding Custom Properties in the Form Designer

User-defined properties (“UDPs”) have always been supported at run-time in OpenInsight by giving the desired property a name prefixed with an “@” symbol and then setting a value for it, e.g:

Call Set_Property( CtrlEntID, "@MYPROP_1", "SomeVal" )
Call Set_Property( CtrlEntID, "@MYPROP_2", "SomethingElse" )

Value = Get_Property( CtrlEntID, "@MYPROP_1" )

// etc...

With the upcoming release of version 10.0.8, design-time support for these has been added in the Form Designer via the new “CustomProperties” property.  This is simply a list of UDP  property names and values that can be specified and stored in the Form definition record, which are then processed during form creation to create UDPs that can be accessed in the normal way by Get_Property and Set_Property.

For example, if you enter a couple of custom properties in the Form Designer called MYPROP_1 and MYPROP_2:

CustomProperties Property

Editing the CustomProperties property

You may then use these with Get_Property and Set_Property at runtime, by referencing them with an “@” prefix (i.e. “@MYPROP_1” and “@MYPROP_2”) like so:

// Value will contain "SomethingElse"
Value = Get_Property( CtrlEntID, "@MYPROP_2" )

Two things to note:

1) You don’t need to specify an “@” prefix for the property name in the CustomProperties editor, and

2) You are not limited to simple strings when entering CustomProperties values – you may also use the standard “[,]” syntax for entering dynamic arrays just like you would for QuickEvent parameters:

E.g. to enter an @fm-delimited array you enclose the list of items in ‘[]’ brackets, and delimit them with a comma like so:

An array like this: 

   <1> ItemOne
   <2> ItemTwo

Can be entered as:

   ['ItemOne','ItemTwo']

Note that each array item must be single-quoted, but you can escape a quote in the data by using two single quotes, e.g.

An array like 

   <1> ItemOne
   <2> ItemTwo's Stuff

Can be entered as:

   ['ItemOne','ItemTwo''s Stuff']

For arrays with lower-level delimiters like @vm and @svm you add a set of nested ”[]’ brackets for each level, e.g:

An array like:
   <1>      ItemOne
   <2,1>    ItemTwo_A
   <2,2>    ItemTwo_B
   <2,3,1>  ItemTwo_C_1
   <2,3,2>  ItemTwo_C_2
   <3>      ItemThree

Can be entered as:
   
   ['ItemOne',['ItemTwoA','ItemTwoB',['ItemTwo_C_1','ItemTwo_C_2']],'ItemThree']

And so on.

Hopefully you find this new feature useful and help to reduce the amount of code you need to write.

A focus on the FOCUS property

There are two methods for setting the input focus in OpenInsight, and there is a subtle implementation difference that can impact your applications if you’re not careful how you apply them.

The first method is to use an object’s own FOCUS property and set it to TRUE$ like so:

Call Set_Property_Only( @Window : ".EDL_SURNAME", "FOCUS", TRUE$ )

This moves the focus to the specified object, but the event queue will be flushed both before and after the focus has been set, thereby preventing any events raised as a result of the focus being moved from being processed.  This method was originally designed for use with validation routines so the focus could be reset to an invalid control “safely”.

The second method is to use the SYSTEM object’s FOCUS property:

Call Set_Property_Only( "SYSTEM", "FOCUS", @Window : ".EDL_SURNAME" )

This moves the focus, but any events triggered as a result of moving the focus (like LOSTFOCUS and GOTFOCUS events) will be processed.

That all sounds straightforward enough, but using the first method can lead to unexpected results if you are relying on an event already in the queue that you subsequently need – not a common situation but one we encountered recently while converting an old form to v10.  In our case we had a menu failing to show when the focus was on a specific control, and it turned out that the LOSTFOCUS event for the control was setting it’s FOCUS property to TRUE$.  This had the effect of killing a pending MENUDROPDOWN event (new in v10) that created the menu to display, hence no menu.

In this case the solution is to use the SYSTEM BLOCKEVENTS property to turn off events being triggered while the focus is moved and then restore event processing afterwards:

Call Set_Property_Only( "SYSTEM", "BLOCKEVENTS", TRUE$ )
Call Set_Property_Only( "SYSTEM", "FOCUS", @Window : ".EDL_SURNAME" )
Call Set_Property_Only( "SYSTEM", "BLOCKEVENTS", FALSE$ )

This prevented any LOSTFOCUS and GOTFOCUS events from being raised, but the MENUDROPDOWN event was still in the queue.

Using the SYSTEM FOCUS and BLOCKEVENTS properties in this way is a far “safer” alternative when moving the focus because you have full control over how events are handled, and I would always advocate using this method over using a control’s own FOCUS property.

 

Coloring your tabs with the ITEMSTYLE property

A new facility introduced in version 10 is the ability to set the styling information for the tabs in the TabControl using the new ITEMSTYLE and ITEMSTYLES properties, and in this post we’ll explain how to use them.

TabStates and ItemStyles

Each tab in a TabControl can be in one of the following states at runtime:

  • Normal (Unselected tab)
  • Hot (Mouse is over a Normal tab)
  • Disabled
  • Selected
  • Hot Selected (Mouse is over the selected tab)

And for each one of these states you can specify the following styling information for the tabs:

  • ForeColor
  • BackColorFrom
  • BackColorTo
  • Bold
  • Italic
  • Underline
  • Translucency
  • CloseButton ForeColor
  • CloseButton BackColor

To do this at run-time you can use one of the following properties:

  • The ITEMSTYLE property
  • The ITEMSTYLES property

and we’ll take a look at each of these in turn.

 

The ITEMSTYLE property

   prevStyle = Get_Property( ctrlEntID, "ITEMSTYLE", itemState )
   currStyle = Set_Property( ctrlEntID, "ITEMSTYLE", newStyle, itemState )

This property allows you to get or set the ITEMSTYLE for a single state.  The property itself is an @fm-delimited array of styling information like so:

    <1> ForeColor             (COLORREF)
    <2> BackColor From        (COLORREF)
    <3> BackColor To          (COLORREF)
    <4> Bold                  (1/0)
    <5> Italic                (1/0)
    <6> Underline             (1/0)
    <7> Translucency          (0-100)
    <8> CloseButton ForeColor (COLORREF)
    <9> CloseButton BackColor (COLORREF)

Equates for these array positions can be found in the PS_TABCONTROL_EQUATES insert record:

   equ TCIS_POS_FORECOLOR$           to 1 ; * // COLORREF
   equ TCIS_POS_BACKCOLOR_FROM$      to 2 ; * // COLORREF
   equ TCIS_POS_BACKCOLOR_TO$        to 3 ; * // COLORREF
   equ TCIS_POS_BOLD$                to 4 ; * // Boolean
   equ TCIS_POS_ITALIC$              to 5 ; * // Boolean
   equ TCIS_POS_UNDERLINE$           to 6 ; * // Boolean
   equ TCIS_POS_TRANSLUCENCY$        to 7 ; * // UInt (0-100)
   equ TCIS_POS_CLOSEBTNFORECOLOR$   to 8 ; * // COLORREF
   equ TCIS_POS_CLOSEBTNBACKCOLOR$   to 9 ; * // COLORREF

You must also use the index parameter with the Get_Property and Set_Property to specify the tab state that you are setting, which is an integer between 1 and 5:

   equ TCIS_NORMAL$                   to 1
   equ TCIS_HOT$                      to 2
   equ TCIS_DISABLED$                 to 3
   equ TCIS_SELECTED$                 to 4
   equ TCIS_HOTSELECTED$              to 5

Example: Setting the Hot and Hot Selected styles

   $insert colors
   $insert logical

   // Set the mouseover text to change to red 
   itemStyle = ""
   itemStyle<TCIS_POS_FORECOLOR$> = RED$
   
   Call Set_Property_Only( ctrlEntID, "ITEMSTYLE", |
                           itemStyle,              |
                           TCIS_HOT$ )

   // Set the mouseover text for a selected item to change to red
   // and bold
   itemStyle = ""
   itemStyle<TCIS_POS_FORECOLOR$> = RED$
   itemStyle<TCIS_POS_BOLD$>      = TRUE$
   
   Call Set_Property_Only( ctrlEntID, "ITEMSTYLE", |
                           itemStyle,              |
                           TCIS_HOTSELECTED$ )

 

The ITEMSTYLES property

   prevStyles = Get_Property( ctrlEntID, "ITEMSTYLES" ) 
   currStyles = Set_Property( ctrlEntID, "ITEMSTYLES", newStyles )

This property is very similar to the ITEMSTYLE property except that it allows you to get or set the styles for all states at once.

The property itself is an @fm/@vm delimited array: each state is delimited by @fm, and the styling information for each state is delimited by @vm.

   <1> ItemStyle for the Normal State
   <2> ItemStyle for the Hot State
   <3> ItemStyle for the Disabled State
   <4> ItemStyle for the Selected State
   <5> ItemStyle for the Hot Selected State

(You will note these map onto the “TCIS_” state equates shown above)

For each one of these states the ItemStyle information is an @vm delimited array using the same structure as for the ITEMSTYLE property, i.e:

   <0,1> ForeColor             (COLORREF)
   <0,2> BackColor From        (COLORREF) 
   <0,3> BackColor To          (COLORREF) 
   <0,4> Bold                  (1/0) 
   <0,5> Italic                (1/0) 
   <0,6> Underline             (1/0) 
   <0,7> Translucency          (0-100) 
   <0,8> CloseButton ForeColor (COLORREF) 
   <0,9> CloseButton BackColor (COLORREF)

So you can use the “TCIS_POS_” equates shown above as well.

Example: Setting the Hot and Hot Selected styles using ITEMSTYLES

   $insert colors
   $insert logical

   itemStyles = Get_Property( ctrlEntID, "ITEMSTYLES" )

   // Set the mouseover text to change to red 
   itemStyles<TCIS_HOT$, TCIS_POS_FORECOLOR$> = RED$
   
   // Set the mouseover text for a selected item to change to red 
   // and bold
   itemStyles<TCIS_HOTSELECTED$,TCIS_POS_FORECOLOR$> = RED$
   itemStyles<TCIS_HOTSELECTED$,TCIS_POS_BOLD$>      = TRUE$
   
   Call Set_Property_Only( ctrlEntID, "ITEMSTYLES", itemStyles )

 

Setting ItemStyles in the Form Designer

Item styling for the tab control can also be specified at design time by using the “ItemStyles” property that is available when you select the tab control in the form designer.  When you click the button for this property you will see an ItemStyles editor dialog that lets you specify the styling information:

TabControl ItemStyles Editor

(Note that in the current release (10.0.6) you will not see this applied to the design control – this will be fixed in an upcoming release)

Tracking the SAVEWARN property

As veteran OpenInsight programmers know, the system uses a simple boolean flag (exposed as the SAVEWARN property) to determine if the contents of a data-bound form have changed.  This flag can be updated in several ways, the most common being:

  • From the LOSTFOCUS event of a control.
  • From the POSCHANGED, INSERTROW and DELETEROW events of an EDITTABLE control.
  • From setting a control’s DEFPROP property.
  • From the CLOSE event of a form when the control with focus is inspected to see if it has changed.

It is checked during the CLEAR and CLOSE events to see if it has been set and an “Unsaved Changes” warning issued to the user if so.  Most of the time this system works quite well, but (as anyone who has spent several years working with OI systems knows) sometimes it gets triggered when you least expect it, and you’re left with no clue as to why.

To help with this situation the next version of OpenInsight introduces SAVEWARN tracking, so you can see which parts of the system update the SAVEWARN property and when they actually do it. In previous versions the system updated the SAVEWARN flag directly (it’s a simple variable in the “window common area”) but this has been changed to use the Set_Property function so it can be monitored effectively from a single point.

To track SAVEWARN you have two choices:

  • Use the SYSMSG event
  • Use the System Monitor

 

Using the SYSMSG event to track SAVEWARN

Every time SAVEWARN is set a standard SYSMSG event is raised with a SAVEWARNINFO code; the system itself does nothing with this message, but it’s there for you to use if you wish.  This option is probably more suited for run-time tracing as it’s something you could add to your applications easily if you needed to.

The PS_EQUATES insert record defines the SAVEWARNINFO message number that you can intercept:

equ SYSMSG_SAVEWARNINFO$ to 21  ; // Save warn has been changed - null msg

The Auxiliary parameter passed to the  SYSMSG event contains information that describes why the SAVEWARN property was changed.

 

Using the System Monitor to track SAVEWARN

The SetDebugger() function has been updated to support a new method called “SAVEWARN” that enables SAVEWARN tracking so that changes are displayed in the System Monitor.  This option is probably more suited to development use rather than run-time.

From the System Monitor execute:

setdebugger savewarn 1

to turn on tracing, and:

setdebugger savewarn 0

to turn it off.

E.g:

SAVEWARN tracing in the System Monitor

SAVEWARN tracing in the System Monitor

Setting the SAVEWARN property

If you wish to set SAVEWARN yourself you may use the “index” parameter to pass a description for the change, so this can be picked up in any tracing scenario like so:

Call Set_Property_Only( @Window, "SAVEWARN", TRUE$, "From My Stuff" )

This description is then passed in the Auxiliary parameter of the  SYSMSG event as noted above.

 

Hopefully you will find this facility useful if you ever suffer from problems with SAVEWARN in the future.

EditTables – The Sub-Object Interface

One of the changes we wanted to make with EditTables in v10 was to expose all of their runtime functionality easily through the normal property/method API.  Some of this was already available in previous versions, but usually involved a method to set a plethora of style bits, which is not really satisfactory unless you’re a C++ programmer (as we have been reminded by various developers on several occasions!).

Besides the EditTable as a whole, there are essentially three other main programmable areas:

  1. Columns
  2. Rows
  3. Cells

Providing unique properties and methods to address the capabilities of these areas is not really practicable, as it leads to an “explosion” of property names: For example, accessing the “text” associated with each of these would require three new properties such as:

  • COLUMNTEXT
  • ROWTEXT
  • CELLTEXT

Of course that’s only three, but considering that each of the aforementioned areas has something like 30 properties, you would suddenly add 90+ new property names to the product!  Bear in mind also that columns, rows and cells each have many properties like TEXT in common, so a new name for each of these seems extremely wasteful and unnecessary.

(We could also have used something similar like the existing TEXTBYPOS method to achieve this, but then we’d have 30’ish new “BYPOS” methods instead, and methods aren’t properties anyway).

So, to keep the property namespace under control we decided to use this commonality and implement a set of  “sub-objects” instead, one for each area.  Unsurprisingly these are named:

  • COLUMNS
  • ROWS
  • CELLS  

Each of these sub-objects are indexed and can be used to access a specific column, row or cell in the EditTable.  They all share many common properties and methods, but also expose a few type-specific ones as well.   As an example, this is how to set the CUEBANNER property for each sub-object:

ctrlEntID  = @window : ".EDT_TEST"
cueBanner  = "Test"

// Set the CUEBANNER for the second column
call set_Property( ctrlEntID : ".COLUMNS", "CUEBANNER", cueBanner, 2 )
// Set the CUEBANNER for the third row
call set_Property( ctrlEntID : ".ROWS", "CUEBANNER", cueBanner, 3 )

// Set the CUEBANNER for the cell at column 5, row 7
call set_Property( ctrlEntID : ".CELLS", "CUEBANNER", cueBanner, 5 : @fm : 7 )

// And here's the same using Object Notation Syntax
@ctrlEntID.columns{2}->cueBannner = cueBanner
@ctrlEntID.rows{3}->cueBannner    = cueBanner
@ctrlEntID.cells{5,7}->cueBannner = cueBanner

We’ll take a look at each of these sub-objects in turn over the next few posts to examine their functionality in more detail.