Tag Archives: SYSTEM

Yield or Die!

When executing a long running process in a desktop environment, such as selecting records from a large table, it is important for the user to be able to interact with the application even though it is busy. A common example of this is displaying a dialog box that shows the progress of an operation and allowing the user to cancel it if they wish. Failure to provide this ability generally results in user frustration, or causes the dreaded “Window Ghosting” effect where Windows changes a form’s caption to “Not Responding” (this is never a good look, and usually ends in a quick visit to the Task Manager to kill the application).

In order to avoid this problem we have to allow the application to check for user interaction, a process usually referred to as “yielding” (hence the awful title of this post), and this time we’ll take a look at the various options available to accomplish this and the differences between them. Before we go any further however, here’s a little background information on how OpenInsight runs beneath the hood so that you can appreciate how messages and events are handled.

Under the hood

OpenInsight.exe (aka. the “Presentation Server”, or “PS”) has a main thread (the “UI thread”) with a Windows message loop that manages all of the forms and controls, and it also has an internal “event queue” for storing Basic+ events that need to be executed. The PS also creates an instance of the RevEngine virtual machine (“the engine”), which has its own thread (the “engine thread”) with a Windows message loop, and is responsible for executing Basic+ code.

When the PS needs to execute an event it passes it to the engine directly if possible, otherwise it adds the details to the event queue and then posts a message to itself so the queue can be checked and processed when the engine is not busy. When the engine receives the event data it is executed on the engine thread. Stored procedures such as Get_Property, Set_Property, and Exec_Method provide a way for the Basic+ event to communicate back to the PS to interact with the user interface controls and forms during its execution.

The key point to note here is that Basic+ event code runs in a different thread to the UI, so while the engine thread is processing the event, the UI thread is basically waiting for it to finish, and this means that it may or may not get chance to process it’s own message loop. This is where the problems can begin, and why the need for a yielding ability, because:

The engine thread needs to be paused or interrupted in some fashion so that the UI thread can check and process its own Windows message queue for things like mouse, keyboard and paint messages. If this queue is not checked at least every 10 seconds then Windows assumes that the PS is hung and the “Not Responding” captions are shown on the application forms.
While the engine is processing an event, the PS cannot pass it a new one, so it is added to the event queue. If we are waiting to process some Basic+ event code like a button CLICK to cancel the current operation, then we need some way for this to be retrieved and executed before the current event is finished.

So, now we know why “window ghosting” happens we can take a look at the various options to deal with it.

Options for yielding

MSWin_Sleep stored procedure

This is a direct call to the Windows API Sleep function, and it puts the engine thread to sleep for at least the specified number of milliseconds. However, while calling this will allow Windows to schedule another thread to run, there’s no guarantee that this would be the UI thread, so it’s not really a good solution.

WinYield stored procedure

This is a simple wrapper around the Windows API Sleep function, with a sleep-time of 10ms. This suffers from the same disadvantages discussed for MSWin_Sleep above (This function remains for backwards compatibility with early versions of of OI and Windows).

MSWin_SwitchToThread stored procedure

This is a direct call to the Windows API SwitchToThread function which forces Windows to schedule another thread for execution. Like MSWin_Sleep and WinYield there’s no guarantee that this would cause the UI thread to run, so again it’s not a great solution.

SYSTEM PROCESSEVENTS method (a.k.a Yield stored procedure)

This is a new method in version 10.1 that performs two tasks that solve the problem:

It explicitly tells the UI thread to process its message queue (which will avoid the “ghosting” issue), and
It allows the UI thread to process the event queue so waiting events can be executed as well.

One possible drawback here is that waiting events are also processed, and this might not be a desirable outcome depending on what you are doing. In this case there is another method called PROCESSWINMGS that should be used instead.

(FYI – The PROCESSEVENTS method is essentially a wrapper around the venerable Yield() stored procedure, but allows the same functionality to be called via the standard object-based method API rather than as a “flat” function. Yield() itself is still and will be fully supported in the product).

SYSTEM PROCESSWINMSGS method

This is a new method in version 10.1 that tells the PS to process it’s Windows message queue but it does not process any Basic+ events, i.e. it prevents the “ghosting” effect but does not cause events to fire before your application is ready for them.

Conclusion

Version 10.1 has added more functionality to help you avoid the dreaded “Not Responding” message via the PROCESSWINMGS and PROCESSEVENTS methods, and hopefully, armed with the information above, this will help you to write better integrated desktop-applications.

The Saga of ShellExecute

Leave a reply

One of the most popular “raw” Windows API functions that OpenInsight developers have used over the years is the ShellExecute function, which allows you to launch an application via its filename association, e.g. you can launch Word by using a document file name, or Excel using a spreadsheet filename and so on.

However, because it was never really made an “official” part of the product (it was normally passed on in forums), developers were left to create their own DLL Prototype definitions in order to use it – this gave rise to many variations over the years, many of which were not compatible with others. For example, some use LPCHAR as an argument type, some use LPSTR or LPASTR, whilst others use LPVOID with GetPointer(); some definitions use the “Wide” version of the function, some the “Ansi” version, and there are many different aliases, with or without the “A/W” suffix too. The list goes on.

For OpenInsight 10 we decided that we couldn’t move forward with this as we would run the risk of conflicting with established applications, so we moved all of the DLL Prototypes we used into a new namespace called “MSWIN_” and claimed it as our own. This left developers to bring forward their own DLL prototypes into version 10 as and when needed, and therefore we didn’t supply a “ShellExecute” function as such, though we did supply “MsWin_ShellExecute” instead (see below).

Another decision we took was to try and move away from the need for developers to use raw Windows API function calls as much as possible, as some of them can be complex and require knowledge of C/C++ programming, which is not necessarily a skill set that everyone has the time or desire to learn. Ergo, we moved a lot of functionality into the Presentation Server (PS) and created some Basic+ wrapper functions around others to shield developers from the sometimes gory internals.

(We also chose to use the “W” versions of functions rather than the “A” versions where possible, because these would translate better when in UTF8 mode and remove the need for an extra “A”->”W” conversion in Windows itself.)

So, coming back to ShellExecute, and in light of the above, we have three “official” and supported ways of calling it in OpenInsight 10 as detailed below:

The SYSTEM object SHELLEXEC method
The RTI_ShellExecuteEx stored procedure
The MSWin_ShellExecute DLL Prototype stored procedure

The SYSTEM object SHELLEXEC method

If your program is running in “Event Context”, (i.e. it is executing in response to an event originating from the PS) then you may use the SYSTEM SHELLEXEC method which invokes ShellExecuteW internally.

RetVal = Exec_Method( "SYSTEM", "SHELLEXEC", OwnerForm, Operation, File, |
                      Parameters, WorkingDir, ShowCmd )

Parameter	Required	Description
OwnerForm	No	Name of a form to use as a parent for displaying UI messages.
Operation	No	Operation to be performed; “open”, “edit”, “print” etc.
File	Yes	File to perform the operation on.
Parameters	No	If File is an executable file this argument should specify the command line parameters to pass to it.
WorkingDir	No	The default working directory for the operation. If null the current working directory is used.
ShowCmd	No	Determines how an application is displayed when it is opened (as per the normal VISIBLE property).

The return value is the value returned by ShellExecuteW.

The RTI_ShellExecuteEx method

This stored procedure is a wrapper around the Windows API ShellExecuteExW function (which is used internally by ShellExecuteW itself), and may be used outside of event context – it can also return the handle to any new process it starts as a result of executing the document. As you can see it’s quite similar to the SHELLEXEC method:

RetVal = RTI_ShellExecuteEx( Hwnd, Verb, File, Parameters, |
                             Directory, nShow, hProcess )

Parameter	Required	Description
Hwnd	Yes	Handle of a window to use as a parent for displaying UI messages, or null (0) to use the desktop.
Verb	No	Operation to be performed; “open”, “edit”, “print” etc.
File	Yes	File to perform the operation on.
Parameters	No	If File is an executable file this argument should specify the command line parameters to pass to it.
Directory	No	The default working directory for the operation. If null the current working directory is used.
nShow	No	Determines how an application is displayed when it is opened (as per the normal VISIBLE property).
hProcess	No	Returns the handle to the new process.

The return value is the value returned by ShellExecuteExW.

The MSWin_ShellExecute DLL Prototype stored procedure

This is the “raw” DLL function that is included with OI10, and the definition can be found in the MSWIN_SHELL32 DLLPROTOTYPE entity:

Shows the MSWIN_SHELL32 DLLPROTOTYPE entity

Because we’re using LPWSTR data types there is no need to null-terminate any of your variables so using it is quite simple:

RetVal = MsWin_ShellExecute( 0, "open", "stuff.docx", "", "c:\docs", 1 )

Migrating ShellExecute

Whilst you are free to use one of the methods outlined above, this may not be optimal if you are still sharing code between your existing version 9 application and your new version 10 one. In this case there are a couple of options you could use:

Define your preferred DLL prototype in v10.
Use a wrapper procedure and conditional compilation.

Defining your own prototype

This is probably the easiest option – you simply use the same prototype in v10 that you did in version 9, with the same alias (if any), and this way the code that uses it doesn’t need to be changed. The only downside to this if you’ve used any 32-bit specific data types instead of 32/64-bit safe types like HANDLE (this could happen if you have a really old prototype) – you must ensure that you use types that are 64-bit compliant.

Using conditional compilation

This is a technique we used when writing the initial parts of v10 in a v9 system so our stored procedures would run the correct code depending on the platform they were executing on (it was actually first used to share code between ARev and OI many years ago!).

The v10 Basic+ compiler defines a token called “REVENG64” which is not present in the v9 compiler – this means that you can check for this in your source code with “#ifdef/#ifndef” directives and write code for the different compiler versions.

For example, you could write your own wrapper procedure for ShellExecute that looks something like this:

Compile Function My_ShellExecute( hwnd, verb, file, params, dir, nShow )

#ifdef REVENG64
   // V10 Compiler - use RTI function
   Declare Function RTI_ShellExecuteEx
   RetVal = RTI_ShellExecuteEx( hwnd, verb, file, params, dir, nShow, "" )
#endif

#ifndef REVENG64
   // V9 Compiler - use existing "raw" prototype
   Declare Function ShellExecute
   RetVal = ShellExecute( hwnd, verb, file, params, dir, nShow )
#endif

Return RetVal

And then call My_ShellExecute from your own code.

So, there ends the Saga of ShellExecute … at least for now.

A focus on the FOCUS property

2 Replies

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.

The CHOOSEDIR and CHOOSEFILE methods

Leave a reply

In light of the Utility function being deprecated (as mentioned in this post) I was recently asked where the CHOOSEFILE and CHOOSEDIR methods had ended up. There was some discussion about this as the aforementioned article cited that they were moved to the SYSTEM object, and a case was made for moving them to the FILESYSTEM object instead.

In the end it was decided to move them to the FILESYSTEM object (as feedback indicated that was where they were expected to be), but to expose them from the SYSTEM object as well, meaning that we wouldn’t have to alter any existing code.

For future reference here are the official details of both methods:

FILESYSTEM CHOOSEDIR method

This method displays the common “Choose Folder” dialog box to allow a user to select a folder. It takes two arguments:

The name of an owner window
A @fm-delimited array of initialization data

<1> Dialog text
<2> Initial folder to select
<3> HideNewFolder flag: If TRUE$ then hide the "New Folder" button
<4> ShowFiles flag: If TRUE$ then show files in the dialog as well as folders

The CHOOSEDIR method is basically a wrapper around the Windows SHBrowseForFolder function.

Example:

dlgOptions    = ""
dlgOptions<1> = "Please select the destination RDK folder"
dlgOptions<2> = "c:\RevSoft\RDK"
dlgOptions<3> = FALSE$ ; * // allow new folders
dlgOptions<4> = FALSE$ ; * // don't show files

folderName = Exec_Method( "FILESYSTEM", "CHOOSEDIR", @window, dlgOptions )

// This works too...
folderName = Exec_Method( "SYSTEM", "CHOOSEDIR", @window, dlgOptions )

FILESYSTEM CHOOSEDIR method

This method displays the common “Choose File” dialog box to allow a user to open a folder. It takes two arguments:

The name of an owner window
A @fm-delimited array of initialization data

<1> Mode: If FALSE$ then show an "Open File" dialog, if TRUE$ then show 
    a "Save As" dialog instead.
<2> Filters: contains an "/" delimited list of filter items in the format:
    
       <displayText> "/" <filter> "/"

    Where <displayText> is the string to show in the filter dropdown list
    and <filter> is the string to apply to the selected folder.

<3> Filter Index: Specifies the index of the filters in <2> to be displayed.
<4> Default file name
<5> OFN (OpenFileName) flags. This is a bitmask number specifying the flags 
    to apply to the dialog. They are defined in the following insert record:
    
        MsWin_GetOpenFileName_Equates

<6> Initial folder to select
<7> Default extension: This is appended to the file name if the user fails 
    to type an extension. This string can be any length, but only the first 
    three characters are appended. The string should not contain a 
    period (.). 
<8> Dialog title

The CHOOSEFILE method is a basically wrapper around the Windows GetOpenFileName function.

Example:

$insert msWin_GetOpenFileName_Equates

* // Create a filter string for common image files
filters = "Bitmap Files (*.bmp;*.rle;*.dib)/*.bmp;*.rle;*.dib/" |
        : "GIF Files (*.gif)/*.gif/"                            |
        : "JPeg Files (*.jpg,*jpeg,*.jpe)/*.jpg;*jpeg;*.jpe/"   |
        : "PNG Files (*.png)/*.png/"                            |  
        : "All Files (*.*)/*.*/"

* // Create a bitmask of flags
ofnFlags   = OFN_READONLY$
ofnFlags   = bitOr( ofnFlags, OFN_HIDEREADONLY$ )
ofnFlags   = bitor( ofnFlags, OFN_FILEMUSTEXIST$ )

dlgOptions    = ""
dlgOptions<1> = FALSE$  ;* // "Open"
dlgOptions<2> = filters
dlgOptions<3> = 4       ; * // Pre-select the PNG filter
dlgOptions<4> = "example.png"
dlgOptions<5> = ofnFlags
dlgOptions<6> = ".\images"
dlgoptions<7> = ""
dlgOptions<8> = "Please select an Image"

imageName = Exec_Method( "FILESYSTEM", "CHOOSEFILE", @window, dlgOptions )

* // This works too ...
imageName = Exec_Method( "SYSTEM", "CHOOSEFILE", @window, dlgOptions )

(Disclaimer: This article is based on preliminary information and may be subject to change in the final release version of OpenInsight 10).

The IDLEPROC Queue

Leave a reply

One of the new features added to the SYSTEM object is the “IDLEPROC queue”. This is an enhancement to the existing IDLEPROC property as it allows you to queue multiple requests via the new SYSTEM ADDIDLEPROC method like so:

* // Run a process in the future 
procID   = "RUN_SOME_PROCESS"
procArg  = "42"
procTime = "12:00:00"  ; * // midday
procDate = oconv( date() + 1, "D4/" ) ; * // tommorrow

call exec_Method( "SYSTEM", "ADDIDLEPROC", procID, procArg, procTime, procDate )

* // Run a process ASAP...
procID = "RUN_SOME_OTHER_PROCESS"
procArg = "X43"
procTime = "" ; * // ASAP
procDate = "" ; * // ASAP

call exec_Method( "SYSTEM", "ADDIDLEPROC", procID, procArg, procTime, procDate )

The contents of the queue can be examined via the new SYSTEM IDLEPROCQUEUE property:

ipQ    = get_Property( "SYSTEM", "IDLEPROCQUEUE" )
xCount = fieldCount ( ipQ, @fm ) 
for x = 1 to xCount
   ip       = ipQ<x>
   procID   = ipQ<0,1>
   procArg  = ipQ<0,2>
   procTime = ipQ<0,3>
   procDate = ipQ<0,4>
next

The normal IDLEPROC property works just as it always has done with the following caveats:

Setting the IDLEPROC property will replace the entire contents of the queue (so you can use this to clear the queue if you wish).
Getting the IDLEPROC property will only return the first item in the queue if there are multiple items.

(Disclaimer: This article is based on preliminary information and may be subject to change in the final release version of OpenInsight 10).

OpenInsight and High-DPI

4 Replies

With the increasing popularity of high-resolution monitors, one of the biggest usability problems today is the display size of text and UI controls, because they appear smaller as the screen resolution increases. The recommended advice to overcome this is to increase the DPI (dots-per-inch) setting of the system, thereby enlarging these elements and making them easier to see and read. If you’ve been using Windows Vista and above you’ve probably already seen this Control Panel applet that allows you to easily change your DPI settings:

Windows 7 DPI Control Panel Applet

However, unless an application is designed to be DPI-aware this can result in some unsatisfactory results, such as over-large fonts, clipped controls and blurry windows. This is because many older Windows applications assume a constant DPI (96) when setting font and size coordinates and they do not apply any scaling to these values, thereby resulting in the aforementioned problems.

(NB. The “magic number” of 96 that you’ll see throughout this post is due to the fact that at 96 DPI one logical pixel is equal to one screen pixel – this is the “100%” setting in the Control Panel applet shown above).

In an effort to accommodate these applications Microsoft have introduced a couple of OS features over the years:

On Windows XP the system fonts and some system UI elements are scaled up at runtime, but this leads to the common problem of text appearing larger and being clipped as the actual size of the bounding control is usually not scaled.

On Windows Vista and above a feature called “DPI-virtualization” automatically scales windows belonging to an application not marked as “DPI-aware” – in effect they are rendered at 96 DPI to an off-screen bitmap, resized, and then drawn to the screen, but this can result in some blurry windows due to pixel stretching. OpenInsight 10 is marked as a DPI-aware application so will not be subjected to DPI-virtualization.

OpenInsight 10, High-DPI and automatic scaling.

OpenInsight 10 supports High-DPI by automatically scaling-up all GUI objects at runtime when created through the SYSTEM object’s CREATE method (formerly known as the “Utility CREATE service”). This affects the following two properties:

Size coordinates
Fonts

The actual scaling for coordinates is calculated by the following simple formula:

screenPixels = logicalPixels * ( currentDPI / 96 )

For example, if you create a control with a size of 200×100 and you are running at 144 DPI (i.e. 150% as per the Control Panel applet above) then the control will be created with an actual size of 300×150 pixels.

The font point size is similarly multiplied by the scaling factor (i.e. currentDPI / 96 ).

Supporting images under High-DPI

Another noticeable issue when running at high DPI settings are images, which are assumed to have been designed for 96 DPI and therefore have to be scaled up at runtime leading to a potential loss of quality due to the resize. To help with this the tool-set has been extended to allow repository BITMAP entities to specify multiple image files when being defined. The first will be used for 96 DPI (100%), the second for up to 120 DPI (125%), the third for up to 144 DPI (150%) the fourth for up to 192 DPI (200%) and so on, with further images being defined at 48 DPI (50%) increments (for future-proofing). When a control is created at runtime the system picks the appropriate image size and scales it as needed (preferably down where possible) before applying any other transformations.

Note that this does NOT apply to images set at runtime in code via the BITMAP property. In this case the developer is assumed to have selected the correct image file size regardless of the DPI setting.

Designing under High-DPI

If you design your forms when running under a High-DPI setting the Form Designer will save and compile all coordinate and font information as though you were developing at 96DPI, so the values will be scaled down appropriately.

Opting out of automatic scaling

Of course, we always try our best not to break existing applications so you can set an option in the RXI file to turn off the automatic DPI scaling if you wish (this option is exposed at runtime via the read-only SYSTEM DPISCALING property).

This same principle can also be applied to individual windows at design-time so you can use it selectively as needed (WINDOW objects also support the read-only DPISCALING property).

Further reading

If you want to find out more information on this topic please see the following link to Microsoft’s documentation on MSDN:

Writing High-DPI Win32 Applications

(Disclaimer: This article is based on preliminary information and may be subject to change in the final release version of OpenInsight 10).

The Reflection API

2 Replies

From a tool-developers point of view one of the weaker areas in the Presentation Server has always been the lack of a “reflection API”, i.e. a way to discover what properties, methods and events an object actually supports at runtime. This in turn has led to creating manual lists and records of object attributes, bringing with it with the inherent difficulty of keeping this information up-to-date as new features are added.

Primarily designed with the new PS-based Form Designer in mind, this shortcoming has been addressed in version 10 with the addition of the following new methods to the SYSTEM object:

REFLECTPROPERTIES
REFLECTMETHODS
REFLECTEVENTS

Each of these methods takes a single argument which is the type of object to query:

e.g.

buttonProperties = exec_Method( "SYSTEM", "REFLECTPROPERTIES", "PUSHBUTTON" )
buttonMethods    = exec_Method( "SYSTEM", "REFLECTMETHODS", "PUSHBUTTON")
buttonEvents     = exec_Method( "SYSTEM", "REFLECTEVENTS", "PUSHBUTTON" )

Each method in turn returns a dynamic array of information describing the requested attribute type:

REFLECTPROPERTIES returns the name of each property and the type of the data it represents. It also identifies the context that the property is valid for (Devtime/Runtime/Get/Set).
REFLECTMETHODS returns the name of each method, along with a list of arguments the method accepts and the type of data each argument should contain.
REFLECTEVENTS returns the name of each event the object type can raise along with the names and data types of arguments passed to an event handler.

Note that when these methods return the type of data for a property or argument there are some cases where only a broad hint is given – Basic+ is an untyped language so it is not really feasible to accurately describe some types using a simple set of flags – e.g. in the case where an argument is a complex dynamic array containing a variety of other core data types such a strings and numbers.

Whilst aimed mainly at developers who write development tools for OpenInsight, this API may still be of interest for those of you who like to write your own diagnostic and debugging tools – when a new property, method or event is added to the Presentation Server it is clearly exposed thereby reducing the likelihood of it remaining hidden and undocumented.

[Edit: 09 Jun 22 – Corrected method names (removed underscores)]

[Edit: 24 Apr 13 – Call_Method renamed to Exec_Method]

(Disclaimer: This article is based on preliminary information and may be subject to change in the final release version of OpenInsight 10).

The RXI Files – Part II

12 Replies

In the previous post where we introduced the new RXI files we mentioned some new command line switches added to OpenInsight 10. In this post we’ll take a look at them and describe what they do.

/TB (taskBarID)

Under Windows 7 and 8 multiple instances of an executable launched from the same directory are grouped under one icon on the taskbar, making navigating between them quite tedious. To allow an executable to override this behavior Microsoft introduced a new application property called the “Application User Model ID” – a simple string that can be applied to an executable instance to differentiate it from other sibling instances, thereby allowing them to be un-grouped.

Windows assigns a default value to this property at runtime based on the executable name and the starting directory. The OpenInsight /TB switch (or taskBarID element in an RXI file) allows you to set your own unique value for this property so that your application can be differentiated on the Windows taskbar (A read-only property called TASKBARID is exposed by the SYSTEM object at runtime to provide access to this value).

The Application User Model ID must be set before any forms are created by an executable which is why it can only be set via the RXI file or the command line switch.

If you wish to find out more details about the Application User Model ID please see the MSDN documentation about the SetCurrentProcessExplicitAppUserModelID function.

/SI (singleInstance)

This is a boolean (1/0) flag that ensures there is only one instance of the specified OI application executing on a workstation. Any other OI applications from the same executable are unaffected.

/EL (elevate)

This is a boolean flag (1/0) that specifies if the application requires Administrator privileges when it is launched. If this switch is set to “1” and the Windows user is not an administrator they will be asked to provide Administrator level credentials before they can continue (via the standard Windows UAC prompt).

/MD (minDisplaySecs)

When displaying a banner image file at startup this switch specifies the minimum number of seconds to display the banner for.

/EP (enginePath)

This switch specifies an alternative OpenEngine path (normally the Presentation Server expects to load OpenEngine from the same directory where it is located).

/2D (useD2D)

This is a boolean flag (1/0) that specifies if the system should use Direct2D technology for rendering when available. By default OpenInsight will attempt to use Direct2D where it can (Windows Vista SP2, Windows 7 and later), but it can be forced to use GDI rendering instead if this flag is set to “0”.

/DP (useDPIScaling)

This is a boolean flag (1/0) that specifies if the application should automatically scale coordinates when used on a high-DPI system.

[Edit: 01 Feb 13 – AM switch renamed to TB and taskBarID]

[Edit: 08 Jan 13 – Added DPI Scaling modifications]

(Disclaimer: This article is based on preliminary information and may be subject to change in the final release version of OpenInsight 10).

The LOG_EVENT method

Leave a reply

In an earlier post we took a very brief look at some of the new properties of the SYSTEM object, and this time we thought we’d take a closer look at one of it’s new methods called LOG_EVENT.

Simply put the LOG_EVENT method allows you to write a message to the Windows Event Log without the need for you to prototype and use any Windows API functions yourself. It’s very easy to use and takes three arguments:

1) Type Info: This is a dynamic array comprised of the following fields:

   <1> Message Type (Required) : "ERROR", "WARNING" or "INFO".
   <2> Event ID     (Optional) : Integer denoting the event. Defaults to 1.
   <3> Category ID  (Optional) : Integer identifying the category. Defaults to 0.

2) Source Info: This is a dynamic array comprised of the following fields:

   <1> Event Source (Required) : Name of the Event Source (See below).
   <2> Server Name (Optional)  : UNC Name of the system to post the message to.
                                 Defaults to the local workstation.

3) Message Text: This is simply the text of the message to post to the Event Log.

Example: Post an error message to the Event Log from the “RevPS” Event Source:

   x = exec_Method( "SYSTEM", "LOG_EVENT", "ERROR", "RevPS", "FOOBAR!!!!" )

The Event Source name

So far, so good. However if you simply execute the above code you will see the message you posted in the Application Event Log, but you’ll also see that Windows has prefixed your message with some of it’s own text which refers to a missing Event ID description like so:

The reason for this is that Windows expects to find a “registered Event Source” containing the description for the Event ID that you specified. A registered Event Source is actually a DLL containing a set of strings, each of which corresponds to an Event ID. Without this DLL you get the warning text you see above which doesn’t look very professional and gives the impression that something is missing from your application.

For OpenInsight v10 we have provided a generic DLL called RevEventMsg.dll that you can register on your system under your desired Event Source name – if you then use that name in your call to the LOG_EVENT method you will see your message without any of the warning text prefixed to it.

Registering the DLL is quite simple: you need to create a new key with the name of your Event Source (We used the string “RevPS” for this example) under this path:

HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\services\eventlog\Application\

… and set a couple of values like so (this can be automated easily via a .reg file):

Now if you call the LOG_EVENT method your Event Log entry will look like this:

Much better.

If you are interested in reading further on the subject of the Windows Event Log you can find full documentation on Microsoft’s MSDN website here,

[Edit: 24 Apr 13 – Call_Method renamed to Exec_Method]

(Disclaimer: This article is based on preliminary information and may be subject to change in the final release version of OpenInsight 10).

The SYSTEM object – some new properties

2 Replies

As the project moves along and work progresses you should see many new items added to the object interfaces in the Presentation Server. One of the main reasons for this is to try and reduce the amount of times you as a developer have to call the Windows API directly – we realize that most OI programmers aren’t C programmers and so we’re trying to save you the pain of dealing with static data types, C-structures and pointers wherever possible.

In light of this we’ve made some changes to the SYSTEM object: As well as bringing across many of the existing Utility services (mentioned previously here) there’s also some brand-new properties and methods too (and we’re not finished yet).

Here’s a quick look at some of the new SYSTEM properties we’ve added so far:

DPI property

This property returns the Windows DPI setting (96, 120 or 144) so you can handle custom scaling in your app if it’s running at a different DPI than the system you designed it on.

ENVVARLIST property

This property returns a list of OS environment variables (just as if you’d typed “set” at the DOS command prompt).

FONTLIST property

This property returns a list of font names that are available on the system.

INTERACTIVE property

This property returns TRUE$ if OpenInsight has been launched in an interactive Windows session (i.e. it has a “desktop”). It returns FALSE$ if OpenInsight has been launched in a non-interactive session such as from a Windows Service process.

MONITORLIST property

This property returns a dynamic array of monitor information. Each field in the array contains the following details for each monitor:

Monitor Handle
Monitor rectangle (left, top, right, bottom)
Monitor work area (left, top, right, bottom)
Flags
Device name.

TYPES property

This property returns a list of the object types that the Presentation Server supports (EDITBOX, LISTBOX, WINDOW and so on). We’ll cover this in more detail in a later post when we look at some of the properties that expose an object’s type-information to provide a “reflection” interface for the toolset.

That’s just a few of the new additions – we’ll post more as they appear. If there’s any others you think should be added please leave a comment and tell us.