Implementing a Dropdown Panel dialog

As mentioned in a previous post we added a new “dropdown-panel” dialog to the Database Toolpanel to allow the user to edit the viewing options:

Database Toolpanel Options dialog

Whilst this looked like a fairly simple job it did require a little bit of effort to get it right so we thought we’d share the method with you in case you wished to implement something similar in your own applications.

As this was dropdown panel we wanted it to behave as close as possible to the way that a dropdown list from a ComboBox works, i.e:

  • It appears when a “parent button” is clicked
  • It should appear underneath the parent button, right-justified
  • The parent button should have a pressed appearance while the panel is displayed, and return to it’s normal state when the panel is closed
  • The panel should close when it loses the focus (i.e. it becomes inactive)
  • The Database Toolpanel is updated as each CheckBox is clicked, so there are no “OK” or “Cancel” buttons for this dialog.

So, this seemed to be a fairly straightforward task:

  • On the Database Toolpanel:
    • The parent button’s CheckStyle property was set to True so that it behaves like a CheckBox and stays pressed when clicked, and then unpressed when clicked again.
    • A “SyncButton” OMNIEVENT handler was created for the Database Toolpanel that simply synchronizes the Check property of the button to True if the panel dialog exists, or False otherwise.
  • On the panel dialog:
    • The name of the parent button is passed to the dialog, and in the CREATE event it sets it’s own SYSTEMSIZE property relative to the SYSTEMSIZE of the parent button as required.
    • The INACTIVATED event closes the dialog.
    • When the dialog closes it posts the “SyncButton” OMNIEVENT to the Database Toolpanel

The problem

At first glance it appeared to work fine: the dialog appeared, you could update the view options, and when you clicked away from the panel it closed. Bravo.

The one remaining problem however, is that many users will click the parent button to close the dialog as well as open it – it’s just a natural action. In our case this actually had the effect of showing the dialog again, because the event sequence looked something like this (remember, by default all events in OpenInsight are executed asynchronously):

  • The user clicks the mouse button (down) on the parent button
  • The dialog deactivates and raises an INACTIVATED event
  • The INACTIVATED event executes and closes the dialog, which in turn posts a “SyncButton” OMNIEVENT to the Database ToolPanel
  • The “SyncButton” OMNIEVENT executes and, because the dialog no longer exists, it sets the parent button’s Check property to False
  • The user releases the mouse button (up) on the parent button raising a CLICK event and setting the Check property to True
  • The CLICK event executes and reloads the dialog again because the parent button’s Check property is True

The solution

To solve this we needed a way to jump into that sequence so we could set a flag to control how the synchronization logic behaves – we needed to stop it setting the parent button’s Check property to False if the user had clicked on it.

The solution was to use the parent button’s BUTTONDOWN event, because this runs after the INACTIVATED event, but before the OMNIEVENT, and before the mouse-up click changes the Check property. We made the following three changes:

  • In the BUTTONDOWN handler we set a user-defined property (“@_BUTTONDOWN”) on the parent button to True. This is just to flag the fact that the button was clicked on by the user.
  • In the “SyncButton” OMNIEVENT we check “@_BUTTONDOWN” – if it’s True then we don’t do anything else, otherwise we set parent button’s Check property to False (This means that if the user clicks away from the dialog it closes as normal).
  • In the CLICK event we set “@_BUTTONDOWN” back to False, then look at the parent button’s Check property. If it’s False we don’t do anything, but if it’s True then we reload the dialog.

With these changes the dropdown panel dialog now behaves in a familiar fashion, and closes correctly regardless of how it loses the focus.

Resizing the RevEngine window

The RevEngine window can sometimes be a helpful tool during the development process, especially when you’re trying to determine just what commands the engine is actually executing, but unfortunately it’s always been a fairly small fixed-size window which can result in a lot of tedious horizontal scrolling when trying to view the contents.

As there’s only so much H-scrolling a person can take, we finally bit the bullet for the next release and made the window resizable instead, so now you can change it to something more comfortable to use as illustrated here:

The incredible resizable RevEngine window

(As an added bonus it’s also DPI-aware so will scale properly to different monitors as needed)

Of course, the RevEngine window is normally not a part of the system that we expose to our users because their usual reaction is to try and close it, and this generally tends to hang or crash the application. In order to mitigate this we also included one more change – if you click the close button the engine will not terminate – it will simply become hidden instead, so even if your users do see the RevEngine window and attempt to close it, they will not crash your application (they will just have to try harder – you know what they’re like… )

However, if you do need to show or hide the RevEngine window in your system it’s as easy as this:

Declare Function GetEngineWindow
$Insert msWin_ShowWindow_Equates

Call MsWin_ShowWindow( GetEngineWindow(), SW_SHOWNORMAL$ )

Hopefully this update should make your applications a little more user-proof and make some development tasks a little easier.

The IMAGE Object API (Redux)

Once upon a time, in a blog post far far away, we looked at a very early incarnation of the version 10 Image API which described how images were used with OpenInsight forms and controls. Since then the API has changed quite a bit, so this post gives you a PDF link to a preview of the API documentation which covers the capabilities in the next release, some of which hasn’t been described before.

An overview of the Image API

Many GUI types managed by the Presentation Server support images in one form or another; some have background images, some have glyphs, some have image lists and so on. However, many of these images have properties of their own, and in most cases these image properties are common to all.

Because of this most Presentation Server types that support images expose them as intrinsic “sub-objects”, thorough a model we refer to as the “Image Object API”. The image object’s lifetime is managed by the system and it cannot be programmatically destroyed from Basic+, but it can be manipulated by the Get/Set_Property and Exec_Method functions just like any other Presentation Server object.

The entire Image API is described in the linked PDF below but be aware that not all image objects support all of the API. For example, a PUSHBUTTON type does not support an “INDEX” property for its background image, and its SplitGlyph image doesn’t support an ALIGN property: All such exceptions are documented in the relevant sections that describe each object type.

Supported image types

The Presentation Server supports the following image types via the WIC (Windows Imaging Component) sub-sytem:

  • BMP
  • ICO
  • PNG
  • GIF
  • JPEG
  • TIFF

Image Object Properties

NameDescription
ALIGNSpecifies the horizontal and vertical alignment of the image
within its parent.
AUTOSCALESpecifies if the image should be scaled along with its parent
object.
COLORKEYSpecifies the color in the image that should be treated as the
“transparent color”.
COUNTSpecifies the number of sub-images within an image file.
FILENAMEReturns the name of the image file being displayed.
FILENAMESSpecifies an array of DPI-specific image files to display.
FRAMECOUNTReturns the number of “frames” within an image.
FRAMEDELAYReturns the delay time in milliseconds for a multi-frame image.
FRAMEINDEXSpecifies the frame to display within a multi-frame image.
INDEXSpecifies the index of the sub-image to display within a multiimage file.
OFFSETSpecifies the point within the image (not the object) to begin
drawing from.
ORIGINSpecifies the point within the object (not the image) to begin
drawing from.
SIZEReturns the width and height of the image in pixels
STYLESpecifies how the image is drawn into an object (Tiled,
Stretched, Clipped or Scaled).
TRANSLUCENCYSpecifies the degree of transparency applied to an image when
it is drawn

Image Object Methods

NameDescription
SAVETOFILESaves the current image to a file.
SETHBITMAPLoads an image from a Windows BITMAP handle (HBITMAP).
SETIMAGELoads an image from an array of “raw” image bytes.
SETREPOSIMAGESpecifies the image file(s) using an OpenInsight repository
IMAGE entity.

Here’s the link to the Image Object API PDF – adding animated GIFs to your applications has never been so easy!

Databinding in the Form Designer

Still on the topic of UI updates in the next release we also took a look at the Databinding dialog in the Form Designer, which had been in need of a make-over for some time. Based on user feedback we wanted to provide much more information when selecting columns and so applied this to the redesign, which now looks like this:

Updated Form Designer Databinding dialog
Redesigned databinding dialog

As you can see, there’s quite a few changes so here’s a brief description of the new features:

  • Typing in the Table box uses AutoComplete to provide a matching list of tables
  • Typing in the Column box auto-selects the first match in the list below
  • The list of columns includes the field position as well as the name
  • The list of columns can be sorted from options on the context menu:
Databinding context menu
Databinding context menu
  • Columns can be filtered by type (F or S)
  • Columns can be filtered so that only multi-valued columns are shown (this is the default for columns bound to an EditTable control)
  • Use the “No Column Selected” option to clear Databinding information from a control
  • The dialog is resizable and remembers the size between calls.
  • Summary information for each column can be seen in the grid control on the right (This is view-only and cannot be used to edit the details – this may change in a future update, but not this one).
    • Description, Formula, Validation and Heading can be expanded to see their full details
Databinding dialog and formula details
Databinding and expanded formula details

Hopefully this will provide a welcome improvement to working with data-bound forms in the next release.

LocateC, GSClear and Expendable

The next release of OpenInsight sees some updates to Basic+ with the addition of two new statements and the return of an old Arev compiler keyword.

The LocateC statement

A counterpart to the well-known IndexC function, the LocateC statement simply performs a case-insensitive “locate” operation on a string, using the normal Locate statement syntax like so:

LocateC substring In string Using delimiter Setting pos Then/Else

The GSClear statement

This statement clears down the internal GoSub return-stack of the currently executing program, so that a subsequent Return statement will return to the calling program rather than jump back to an originating GoSub statement as normal. This is usually used to handle severe error conditions where an “early return” to the caller is desirable and there is a need to pass a value back to the caller. E.g:

Compile Function Test( Void )

   GoSub DoTheThing

Return "The Thing Was OK"

DoTheThing:
   
   GoSub CheckTheStuff

Return

CheckTheStuff:

   If TheStuffIsReallyBad Then
      // Return directly to the caller
      GSClear 
      Return "The stuff is really bad!!!"
   End

Return

This is basically the same as performing an Abort operation, but allows you to return a value, which Abort does not.

The Expendable statement

Marking a program as “expendable” was a useful feature in Advanced Revelation that instantly removed a program from the cached program array after it had finished executing. This was very useful in networked development scenarios where programs being edited could be loaded by different workstations – they could still get an updated version without having to restart the application or issue a manual GarbageCollect statement to clear the cache. This is a similar scenario to using a current tool like the OpenInsight EngineServer, where individual engines can cache programs during development – it can become tedious to force them to load an updated version after making changes.

To mitigate this the Expendable keyword has been reintroduced and is simply added to the program header declaration like so:

Compile Expendable Function( Param1 )
   // Do stuff
Return RetVal

or, if you don’t use the optional “Compile” keyword:

Expendable Function( Param1 )
   // Do stuff
Return RetVal

With this the engine now deletes the program from the cache after all references to it have been removed from the call stack, forcing it to reload from disk the next time it is called.

A tour around the updated IDE Database Toolpanel

Contrary to popular belief, or indeed the evidence of your own eyes, this blog is still actually alive, so in the next few posts we’ll try and look some of the work that’s been going on behind the scenes for the next release. In this post we’ll take a quick tour around the IDE Database Toolpanel that’s had a much-needed face-lift to improve it’s usability:

New Database Toolpanel
Updated IDE Database ToolPanel

As you can see it looks a little different now – we’ve updated the artwork, and you can see that different table types have different icons:

  • Dictionary tables have a purple book overlay marker
  • Index tables have a green book overlay marker
  • The different data-source types (RTP57, SysColumns, DSBFS etc) have their own icons

We’ve also changed the layout and size of the toolbar buttons so there are five that fit much better into the IDE. From left to right these are:

  • New table
  • Add table
  • Alias table
  • Save database definition
  • View options

The View options button loads a dialog as a “dropdown panel” that defines what you see in the table list:

Database Toolpanel View Options

Most of these are self evident, but the “Group by table name” option is new – it simply controls how tables are sorted in the list – when the box is checked the data, dictionary and index tables appear together, when unchecked they appear in proper ascending alphabetical order (Implementing this dialog as a “dropdown panel” is an interesting exercise in it’s own right and we covered this here).

The filter box remains the same – simply start typing to restrict the list to those table names starting with the same string:

Database Toolpanel Filter

We’ve also given the context menu an overhaul, both visually and in terms of making it more context aware based on the table that you right-click on (only enable index options for index tables, verify options for LH tables and so on):

Database Toolpanel Context-menu

Underneath the hood there are a few other changes – including how this toolpanel is updated based on changes to the database, and when warnings about saving the database definition are given. Hopefully you’ll find using this part of the IDE easier in the next release.

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!

What’s “this”?

As I’m sure many of you will know, when you’re working with object oriented languages like C++, JavaScript and VB , the compiler provides you with a keyword (e.g. ‘this’ or ‘Me’) that you can use as a reference to the specific instance of an object under which the code is currently executing.  This provides a neat and easy way to access details about the current context when responding to events and methods, and generally improves the clarity of the code.

However, a ‘this/Me’ construct is not something we’ve really had in OpenInsight, because when we write our event handling code the system explicitly passes the name of the current object as the first argument called “CtrlEntID”, so in our event scripts we can use that instead.  Obviously this works well enough, but over the years I’ve found some situations where it would be nice to go a little further:

  • In many of the OpenInsight training courses I’ve run, one of the most common questions I get asked from new students is: “what is the equivalent of ‘this’, or “where is the ‘Me’ keyword”?   Having some sort of “this/me” construct in Basic+ would make learning the system much easier for them, and the name “CtrlEntID” hardly seems slick!
  • With the trend away from using event scripts and moving code into commuter modules the name “CtrlEntID” is no longer enforced – it can be named anything the author of the commuter module wishes, leading to a possible loss of clarity (for example in my own commuter modules I always use the variable name “Object” in place of “CtrlEntID”, but that’s just my convention, and is something subsequent code maintainers must adopt).
  • As code becomes deeper and more nested passing the “CtrlEntID” variable to each subsequent procedure as an argument becomes more of a chore, and I’ve seen global variables used in place of this which can lead to code that is difficult to maintain.

Of course, we do have the “@Window” system variable, which contains the name of the parent WINDOW instance for the currently executing context, so we’re nearly there, but unfortunately that’s not the same as ‘this/Me’ unless you’re responding to a WINDOW event.

So, with the release of version 10.0.8 we’ve now gone the whole way and added a new system variable called:

@Self

When an event is triggered this variable contains the full name of the control instance under which the event code is executing, just like @Window contains the name of the parent WINDOW instance.

E.g:

// Using CtrlEntID
Name = Get_Property( CtrlEntID, "TEXT" )

// Using @Self
Name = Get_Property( @Self, "TEXT" )

We’ve also included two more system variable names as synonyms for @Self as well:

@This
@Me

You may use these in place of @Self if you’re more inclined to use names that are familiar from another language (@Self was chosen because it is already referenced in OpenInsight as a pseudo-variable name when defining QuickEvents).

Hopefully, moving forward, this small addition may help to maintain a cleaner code-base and make teaching new students a little easier.

 

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.