Tag Archives: Methods

The FILESYSTEM WATCHDIR method

We’ve already taken a look at the new FILESYSTEM object in a previous post, but this time we’re going to focus on a new method we’ve added called WATCHDIR.

This method allows you to monitor the contents of one or more directories on the system and be notified of any changes occurring within them.  It’s API is quite simple and takes up-to three arguments:

  1. The name of the directory to watch (required).
  2. A optional boolean flag denoting if you wish to include sub-directories. (defaults to FALSE$).
  3. An optional set of bit-flags detailing the kind of changes you are interested in.  By default WATCHDIR notifies you of file creation, changes to the name, and changes to the “Last-Write” time.

Example:

$insert msWin_FileNotify_Equates

// Only watch for files being created in the specified dir ...
watchFlags      = FILE_NOTIFY_CHANGE_CREATION$
bIncludeSubDirs = FALSE$
call exec_Method( "FILESYSTEM", "WATCHDIR", "c:\temp\incoming", |
                  bIncludeSubDirs, watchFlags )

When a change occurs the FILESYSTEM object raises a CHANGED event to notify you of the fact,  As with any other OI window or control you can write your own FILESYSTEM CHANGED event handler to respond to this – note that this event is per application, not per window.

Like the standard CHANGED event the relevant change information is passed in the “NewData” argument – in this case “NewData” contains a dynamic array with two fields:

<1> The name and path of the file being changed
<2> A code specifying the type of change

Example FILESYSTEM CHANGED event:

$insert msWin_FileNotify_Equates

changeFile = newData<1>
changeCode = newData<2>

info = ""

begin case
   case ( changeCode = FILE_ACTION_ADDED$ )
      info = "Added"
   case ( changeCode = FILE_ACTION_REMOVED$ )
      info = "Deleted"
   case ( changeCode = FILE_ACTION_MODIFIED$ )
      info = "Modified"
   case ( changeCode = FILE_ACTION_RENAMED_OLD_NAME$ )
      info = "Renamed From"
   case ( changeCode = FILE_ACTION_RENAMED_NEW_NAME$ )
      info = "Renamed To"
end case

call send_Info( info : " " : changeFile )

Technical note: The WATCHDIR method is based on the underlying ReadDirectoryChangesW Windows API function, details of which can be found here.

(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

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

Progress Bar controls

One of the new controls supported by OpenInsight 10 is the Windows Progress Bar control which is used to display the progress of lengthy operations.

Progress Bar

Windows 7 Aero Progress Bar

Windows XP Progress Bar

Windows XP Progress Bar

It is a fairly simple control and supports the following properties:

  • BORDER
  • ERRORCOLOR
  • MARQUEE
  • NORMALCOLOR
  • PAUSEDCOLOR
  • RANGE
  • SHOWTEXT
  • SMOOTH
  • STATE
  • STEP
  • SYNCTASKBAR
  • TEXT
  • TRANSLUCENCY
  • VALUE
  • VERTICAL

And the following methods:

  • DECREMENT
  • INCREMENT

BORDER property

Setting this boolean property to TRUE (“1”) draws a border around the control.  This is the default value.

XP Progress Bar without border

Translucent XP Progress Bar without a border

ERRORCOLOR property

This property is a standard color value and sets the color of the bar when it is in the “error” state (see the STATE property below).  Depending on the visual style in use this property normally defaults to a red color.

Red Progress Bar

Windows Classic smooth style Progress Bar with an ERRORCOLOR of 255 (red)

MARQUEE property

This property is an integer value that contains the time in milliseconds between marquee animation updates.  Setting it to 0 stops the marquee animation.

Progress Bar with marquee effect

Aero Progress Bar with a MARQUEE property of 50 (i.e. it animates every 50 ms)

XP Progress Bar with marquee effect

Windows XP Progress Bar with a MARQUEE property of 50

NORMALCOLOR property

This property is a standard color value and sets the color of the bar when it is in the “normal” state (see the STATE property below).  Depending on the visual style in use this property normally defaults to a green color, though in other schemes like “XP Olive” this defaults to an orange color instead.

Purple Progress Bar

Windows 7 Aero progress Bar with a purple NORMALCOLOR (255,0,255)

PAUSEDCOLOR property

This property is a standard color value and sets the color of the bar when it is in the “paused” state (see the STATE property below).  Depending on the visual style in use this property normally defaults to an amber or yellow color.

Windows 7 Aero paused progress bar

Windows 7 Aero segmented Progress Bar with a STATE of “3” (paused)

RANGE property

This property is an @fm-delimited array of two integers containing the upper and lower limits of the progress bar.

<1> Low limit
<2> High Limit

The VALUE property must be between these two values.

SHOWTEXT property

Setting this property to TRUE (“1”) will display the contents of the TEXT property in the center of the progress bar.  The default is FALSE ( “0”).

SMOOTH property

Setting this property to TRUE (“1”) causes the progress indicator to be drawn as a continuous bar rather than in the usual segmented style.

Smooth Progress Bar

Windows Classic Smooth Progress Bar – i.e. a SMOOTH style of TRUE (“1”)

Segmented Progress Bar

Windows 7 Aero segmented Progress Bar – i.e. a SMOOTH style of FALSE (“0”)

STATE property

This property sets the visual state of the progress bar.  It can be one of the following values:

  • “1” – Normal (green)
  • “2” – Error (red)
  • “3” – Paused (yellow)

Each of these states has a default color as indicated above but this can be changed by one of the bar color properties (NORMALCOLOR, ERRORCOLOR and PAUSEDCOLOR).

Examples:

Progress Bar Error

Windows 7 Aero Progress bar with a STATE property of 2

Progress Bar Paused

Windows 7 Aero Progress bar with a STATE property of 3

STEP property

This property is a simple integer and is used in conjunction with the INCREMENT method.  If the latter is called with no value the progress bar is incremented by the amount specified in this property.

SYNCTASKBAR property

When set to TRUE (“1”) the parent form’s taskbar button is automatically updated to mirror the state of the Progress Bar control (as per our previous post on Taskbar Integration).

Synchronized Progress Bar

Windows 7 Aero Progress Bar with SYNCTASKBAR set to TRUE (“1”)

This property has no effect unless the application is running on Windows 7 or higher.

TEXT property

This property is the same as the standard TEXT property.  However, any occurrences of the substring “%p%” within the text will be replaced with the current percentage complete.

Progress Bar with TEXT

Windows 7 Aero Progress Bar with a TEXT property of “%p% Complete”

TRANSLUCENCY property

This property specifies the transparency of the control’s background (i.e. the progress bar itself is not affected).  It is based on simple percentage amount, “0″ being fully opaque and “100″ being fully transparent (and therefore not visible).

Translucent Progress Bar

Windows 7 Aero Progress Bar with a TRANSLUCENCY of 50

VALUE property

This simple integer property sets the current value (position) of the progress bar.  It should be a value between the limits set by the RANGE property.

Progress Bar 25% complete

Windows 7 Aero Progress Bar with a RANGE of [0,200] and a VALUE of 50

VERTICAL property

Setting this property to TRUE (“1”) draws the progress bar in a vertical fashion – i.e. it increments from the bottom to the top.

Vertical Progress Bar

Windows 7 Aero Progress Bar with a VERTICAL property of TRUE (“1”)

DECREMENT method

exec_Method( ctrlEntID, "DECREMENT", amount )

This method decrements the progress bar by a specified amount.  If no amount is specified the bar is decremented by the value contained in the STEP property instead.

INCREMENT method

exec_Method( ctrlEntID, "INCREMENT", amount )

This method increments the progress bar by a specified amount.  If no amount is specified the bar is incremented by the value contained in the STEP property instead.

Further reading

More information on Progress Bars can be found on the MSDN site here, along with some user interface guidelines here.

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

Date and Time Picker controls

Another Windows Common Control exposed by OpenInsight 10 is the Date and Time Picker (DTP) control. This presents a simple interface for a user to enter date and/or time information in a standard or custom format.  It also provides an option to display a drop-down calendar for picking a date.

Date and Time Picker control

Date and Time Picker control

Date and Time Picker control with calendar

Date and Time Picker control with calendar

It supports the following properties:

  • CALALIGN
  • CALBACKCOLOR
  • CALFONT
  • CALFORECOLOR
  • CALMONTHBACKCOLOR
  • CALTITLEBACKCOLOR
  • CALTITLEFORECOLOR
  • CALTRAILINGFORECOLOR
  • CHECK
  • CHECKBOX
  • CUSTOMFORMAT
  • FORMAT
  • IDEALSIZE
  • MAXVALUE
  • MINVALUE
  • UPDOWN
  • VALUE

It supports the following method:

  • CLOSECAL

And the following events:

  • CHAR
  • CHANGED
  • CLOSEUP
  • DROPDOWN
  • GOTFOCUS
  • LOSTFOCUS

CALALIGN property

This property controls the alignment of the drop-down calendar and can be one of the following values:

  • “L” (Left – the default)
  • “R” (Right)

CALBACKCOLOR property

This property is an RGB color value that specifies the background color displayed between months of the drop-down calendar.  Setting this property has no effect if visual styles are enabled.

CALFONT property

This property specifies the font of the drop-down calendar – it has the same structure as the regular OpenInsight FONT property.  Setting this property has no effect if visual styles are enabled.

CALFORECOLOR property

This property is an RGB color value that specifies the text color of the drop-down calendar. Setting this property has no effect if visual styles are enabled.

CALMONTHBACKCOLOR property

This property is an RGB color value that specifies the background color displayed within the month of the drop-down calendar.  Setting this property has no effect if visual styles are enabled.

CALTITLEBACKCOLOR property

This property is an RGB color value that specifies the background color displayed in the title of the drop-down calendar.  Setting this property has no effect if visual styles are enabled.

CALTITLEFORECOLOR property

This property is an RGB color value that specifies the text color displayed in the title of the drop-down calendar.  Setting this property has no effect if visual styles are enabled.

CALTRAILINGFORECOLOR property

This property is an RGB color value that specifies the text color used to display the header day and trailing day text in the drop-down calendar.  Setting this property has no effect if visual styles are enabled.

CHECK property

This is a boolean value that specifies if the DTP checkbox is ticked.  It only applies if the DTP control contains a checkbox (see the CHECKBOX property below).

CHECKBOX property

This is a boolean value that specifies if a checkbox is shown within the DTP control. Normally the DTP control always contains a date/time value (i.e. it is never considered empty).  However if a checkbox is shown then it is only considered to contain a valid date/time if the checkbox is ticked (see the CHECK property above).

CUSTOMFORMAT property

By default the format of the date and time displayed by the DTP control is one of the standard formats as defined in the user’s Windows environment settings:

Windows date and time settings

Windows date and time settings

The FORMAT property (see below) can be used to specify one of these.

However, it is possible to use a custom format and this can be set using either a standard Windows format string or a standard Revelation Date and Time IConv/Oconv format (“D”, “DT”  and “MT”) which sets the underlying Windows format appropriately.

e.g.  “D4/E” will be translated to “dd/MM/yyyy” and so on.

FORMAT property

This property specifies the format of the date and time displayed in the control and can be one of the following values:

  • “0” – Custom format (set when using the CUSTOMFORMAT property – don’t set this yourself!)
  • “1” – Windows Long Date format
  • “2” – Windows Short Date format
  • “3” – Windows Time format

IDEALSIZE property

This get-only property returns the size needed to display the control without any clipping as an @fm-delimited array:

<1> Ideal width in pixels
<2> Ideal height in pixels

MAXVALUE property

Specifies the maximum date and time that can be entered in the control. This is a standard Revelation DateTime format of:

<date> : "." : <time>

Where date is the number of days elapsed since 31/12/1967, and time is the fraction (percentage) of the day that has elapsed.

MINVALUE property

Specifies the minimum date and time that can be entered in the control. This is a standard Revelation DateTime format of:

<date> : "." : <time>

Where date is the number of days elapsed since 31/12/1967, and time is the fraction (percentage) of the day that has elapsed.

UPDOWN property

By default the DTP control displays a button to access a drop-down month calendar for modifying the date.  Setting this property to TRUE (“1”) displays a Windows UpDown control to modify date-time values instead.

Date and Time Picker with an UpDown control

Date and Time Picker with an UpDown control

VALUE property

This property specifies the current value of the DTP control in the standard Revelation DateTime format of:

<date> : "." : <time>

Where date is the number of days elapsed since 31/12/1967, and time is the fraction (percentage) of the day that has elapsed.

While the TEXT property is supported the VALUE property should be used to access the DTP date-time values to avoid possible complications with custom formatting strings.

CLOSECAL method

This method simply closes a dropped-down month calendar. It takes no arguments.

call exec_Method( ctrlEntID, "CLOSECAL" )

Further reading

More information on the Date and Time Picker control can be found on the MSDN site here,

(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

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:

DPI Control Panel Applet

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 System Monitor – Part II

In a previous post we looked at some the enhancements to the version 10 System Monitor to make it a more user-friendly tool.  However, one of the features we didn’t mention was the addition of a Basic+ property API so you can interact with it from your own programs and tools if you wish.  This API is exposed via the new SYSTEMMONITOR object, which supports the following properties:

  • HANDLE
  • RESULTS
  • SIZE
  • TEXT
  • VISIBLE

And the following method:

  • RUN

HANDLE property

This property returns the window handle (HWND) of the System Monitor window.

RESULTS property

This property returns the contents of the results edit box in the System Monitor.

SIZE property

This property gets and sets the size and position of the System Monitor window.  It has the same format as the normal OpenInsight WINDOW SIZE property.

TEXT property

This property gets and sets the caption text of the System Monitor window.

VISIBLE property

This property gets and sets the visibility of the System Monitor window.  It has the same format as the normal OpenInsight WINDOW VISIBLE property

RUN method

This method executes a system monitor command.

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

The Image API

As promised in our last post this time we’re going to cover the new properties we’ve added to the Presentation Server to support the enhanced image capability:

  • IMAGEALIGN
  • IMAGECOLORKEY
  • IMAGEFRAMECOUNT
  • IMAGEFRAMENUMBER
  • IMAGESIZE
  • IMAGESTYLE
  • IMAGETRANSLUCENCY

We have also added the following new method:

  • SETIMAGE

IMAGEALIGN property

This property specifies how a clipped or scaled image is aligned within a client area.  It can be one of the following values:

  • “0” Top-Left
  • “1” Top-Center
  • “2” Top-Right
  • “3” Middle-Left
  • “4” Centered
  • “5” Middle-Right
  • “6” Bottom-Left
  • “7” Bottom-Center
  • “8” Bottom-Right

Examples:

IMAGEALIGN 4 (Centered)

IMAGEALIGN 6 (Bottom-Left)

IMAGEALIGN 6 (Bottom-Left)

IMAGESTYLE property

This property specifies how the image is rendered onto the window’s client area.  The following property values are supported:

  • “0” Clip – the image is not resized and is simply rendered onto the client area according to the IMAGEALIGN property (Note that the IMAGEORIGIN property will override the image alignment).
  • “1” Stretch – the image is resized to cover the entire client area of the window.
  • “2” Tile – the image is tiled across the entire client area.
  • “3” Scale – the image is resized but it’s proportions are kept constant: e.g. if the image is taller than it is wide the image height will be resized to the height of the client area, and it’s width scaled to keep the same proportions.  It will also respect the IMAGEALIGN property.

Examples:

IMAGESTYLE 1 (Tiled)

IMAGESTYLE 1 (Tiled)

IMAGESTYLE 2 (Stretched)

IMAGESTYLE 2 (Stretched)

IMAGESTYLE 3 (Scaled), IMAGEALIGN 5 (Center-Right)

IMAGESTYLE 3 (Scaled), IMAGEALIGN 5 (Center-Right)

IMAGECOLORKEY property

This property specifies the color to use as the transparent color when rendering the image as described in this post.  It basically replaces the current (and undocumented) IMAGETRANSPARENT and TRANSPARENTCOLOR properties, both of which have been deprecated with this release.

This property should be a valid RGB color value or one of the following special values:

  • “-1” Use the color of the top left pixel as the color-key.
  • “-2” Use the color of the top-right pixel as the color-key.
  • “-3” Use the color of the bottom-left pixel as the color-key.
  • “-4” Use the color of the bottom-right pixel as the color-key.
  • “-5” Do not use any color-keying.

IMAGEFRAMECOUNT property

Some image formats such a GIF and TIFF files can contain more than one image, held in series of frames.  This read-only property returns the number of frames in the image file.  Note that this is not the same as the IMAGECOUNT property, which applies to a single frame only.

Example:

Animated GIF with 12 frames

Animated GIF with 12 frames

IMAGEFRAMENUMBER property

This property gets or sets the current display frame for the image and could be used with a TIMER event to display an animated GIF file for example.  Note that this property is not the same as the IMAGENUMBER property which applies to a single frame only.

Examples:

Animated GIF with IMAGEFRAMENUMBER of 2

Animated GIF with IMAGEFRAMENUMBER of 2

Animated GIF with IMAGEFRAMENUMBER of 10

Animated GIF with IMAGEFRAMENUMBER of 10

IMAGESIZE property

This read-only property returns a dynamic array containing the size of the image in pixels:

<1> Width
<2> Height

Note that for a multi-frame image format it returns the size of a single frame, not all the frames combined.

IMAGETRANSLUCENCY property

This property specifies the transparency of the entire image as it is rendered onto the window. It is based on simple percentage amount, “0″ being fully opaque and “100″ being fully transparent (and therefore not visible).

Example:

IMAGETRANSLUCENCY of 70 with IMAGEORIGIN of 90,60

IMAGETRANSLUCENCY of 70 with IMAGEORIGIN of 90,60

SETIMAGE method

This method supersedes the existing IMAGE property and allows a image to be set by passing the raw image data rather than by passing a file or resource name as per the BITMAP property.  The OpenInsight property interface is text-based and does not support passing binary data with embedded null characters, whereas the method interface does, hence the reason for this change.

Other image-related properties

The following current image-related properties remain the same:

  • BITMAP
  • IMAGECOUNT
  • IMAGENUMBER
  • IMAGEOFFSET
  • IMAGEORIGIN

Deprecated properties

The following properties have been deprecated or removed in OpenInsight 10:

  • IMAGE – this property has been superseded by the SETIMAGE method.  It is now a synonym for the BITMAP property.
  • IMAGECLIP – this property has been superseded by the IMAGESTYLE property.
  • IMAGETRANSPARENT – this property has been superseded by the IMAGECOLORKEY property.
  • TRANSPARENTCOLOR – this property has been superseded by the IMAGECOLORKEY property.

(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

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:

  • REFLECT_PROPERTIES
  • REFLECT_METHODS
  • REFLECT_EVENTS

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

e.g.

buttonProperties = exec_Method( "SYSTEM", "REFLECT_PROPERTIES", "PUSHBUTTON" )
buttonMethods    = exec_Method( "SYSTEM", "REFLECT_METHODS", "PUSHBUTTON")
buttonEvents     = exec_Method( "SYSTEM", "REFLECT_EVENTS", "PUSHBUTTON" )

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

  • REFLECT_PROPERTIES 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).
  • REFLECT_METHODS returns the name of each method, along with a list of arguments the method accepts and the type of data each argument should contain.
  • REFLECT_EVENTS 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: 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 LOG_EVENT method

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 new FILESYSTEM object

As we mentioned earlier the decision was taken to deprecate the Utility function, but we still needed to provide the equivalent functionality by some other means. The obvious candidate to update here was the existing SYSTEM object, but rather than overloading it with a whole raft of new members, all of which were filing-system related, we took the decision to create a new object instead, and thus the FILESYSTEM object was born.

The FILESYSTEM object, like the SYSTEM one, is managed internally by the Presentation Server and simply exposes some common Windows Shell directory and file-based functionality to Basic+. As you’ll see below there are some new properties and methods that were not part of the old Utility function, but we’ve also taken the opportunity to enhance some of the existing methods as well – they now hook into the Windows API SHFileOperation function thereby offering better system integration, such as using standard Windows copy/move dialogs and exposing “Undo” functionality.

Here’s a summary of the FILESYSTEM object interface that you’ll find in the new version:

Properties

Property Dev Run Get Set Description
CURRENTDIR X X X Provides access to the current working directory.
DRIVELIST X X Returns a dynamic array of attached drive letters.
FILEOPRESULT X X Returns the most recent result code from a FILESYSTEM object method call.
SYSTEMDIR X X Returns the OS System directory.
TEMPDIR X X Returns the user’s Temp directory.
WINDOWSDIR X X Returns the Windows directory.

Methods

Method Description
COPYDIR Copies an entire directory and sub-directories to a new location.
COPYFILES Copies one or more files to a new location.
DELETEFILES Deletes one or more files.
DIREXISTS Checks to see if a directory exists.
FILEEXISTS Checks to see if a file exists.
GETABSOLUTEPATH Returns an absolute path from a relative path
GETLONGPATH Converts a short path to its long path form
GETRELATIVEPATH Returns a relative path from an absolute path
GETSHORTPATH Converts a long path to its short path (i.e. MS-DOS “8.3”) form
GETSPECIALDIR Returns the path to a “special” OS folder such as “My Documents”, AppData and so on.
MAKEDIR Creates a directory or nested directory path.
MOVEDIR Moves an entire directory and sub-directories to a new location.
MOVEFILES Moves one or more files to a new location.
REMOVEDIR Removes a directory.
RENAMEDIR Renames a directory.
RENAMEFILE Renames a file.

Of course this is probably not a final list, so please feel free to leave us a comment if you think of anything that would make a good addition here.