Tag Archives: Properties

The SCALEFACTOR property

As we mentioned in our last post on High-DPI, the work needed to accommodate per-monitor DPI scaling in Windows 8.1 has also created the ability to scale OpenInsight forms to an arbitrary value outside of any system DPI settings.  This new functionality is exposed via the SCALEFACTOR property described below.

SCALEFACTOR property

This WINDOW property is a dynamic array comprising four fields:

<1> ScaleFactor
<2> Minimum ScaleFactor
<3> Maximum ScaleFactor
<4> ScaleFactor Increment

<1> ScaleFactor

This is a number that specifies how much to scale the form by.  A value of 1 means that the form has no scaling applied, a value of 1.5 scales the form to one-and-a-half times its normal size and so on.

Note that the scale factor is applied after any scaling applied for system DPI.  So, if your form runs on a 144 DPI monitor (150%) and has a scalefactor of 2 applied the actual scalefactor used is 3.0 (1.5 x 2.0).

<2> Minimum ScaleFactor

This specifies the minimum value that the ScaleFactor can be set to. By default it is set to “0.1”.  This value can be set at design time. See the note on “Scaling Restrictions” below.

<3> Maximum ScaleFactor

This specifies the maximum value that the ScaleFactor can be set to. By default it is set to “5.0”.  This value can be set at design time. See the note on “Scaling Restrictions” below.

<4> ScaleFactor Increment

If this field is set to a value other than 0 it allows the ScaleFactor to be adjusted via the  Mouse-wheel /Ctrl-key combination, or with a “pinch-zoom” gesture if running under a touch screen.  The increment value controls the rate at which the form grows or shrinks.  This value can be set at design time.

Example 1: Set a form’s scale to twice its designed size while allowing the user to adjust the scalefactor by the mouse or touchscreen:

* // Note that we ignore the min and max scalefactors, leaving them at their
* // defaults.
scaleFactor = ""
scaleFactor<1> = 2    ; * // twice normal size
scaleFactor<4> = 0.1  ; * // allow mousewheel/gesture - each wheel notch
                      ; * // adjusts the scalefactor by 0.1

Example 2: Comparing OpenInsight forms with a SCALEFACTOR of 0.5 and 1.0 respectively (both running on a 144 DPI desktop with DPISCALING disabled)

Comparing SCALEFACTOR 0.5 vs 1.0

Comparing SCALEFACTOR 0.5 vs 1.0

Example 3: Comparing OpenInsight forms with a SCALEFACTOR of 1.0 and 1.7 respectively (both running on a 144 DPI desktop with DPISCALING disabled)

Comparing SCALEFACTOR 1.0 vs 1.7

Comparing SCALEFACTOR 1.0 vs 1.7

DPI Image Lists and Image Scaling

In Example 3 above note the quality of the magnifying glass glyph on the buttons in the scaled form: it is much clearer and sharper on the Search button than it is on the Split button. This is because the Search button was designed using a “DPI Image List”, which means that an array of images, along with a corresponding array of DPI values, was specified for this glyph rather than just a single image. OpenInsight scans this DPI Image List looking for the closest match it can find when performing a scaling operation.  By contrast the Split button is using a single image designed for 96 DPI and stretched to fit, resulting in a blurry appearance.

(Note: We first mentioned this functionality in the section “Supporting images under High-DPI” in our original High-DPI post).

Or course, you may also find yourself in the position of not wanting a particular image scaled, and in this case we’ve added a new property to the Image API called IMAGEAUTOSCALE.  This is a simple boolean property that controls if an image is scaled by the system during the scaling process.  It’s default value is TRUE.

(We’ve also added a similar property to other areas of the system that use images as well, so there is a GLYPHAUTOSCALE property, a SPLITGLYPHAUTOSCALE property and so on).

 

Scaling Restrictions

The minimum and maximum size that a form can be rescaled to can be restricted by the minimum and maximum window sizes as defined by the OS.  As a general rule this size is usually slightly larger than the size of the entire desktop across all monitors (See the GetSystemMetrics() Windows API function along with the indexes SM_CXMAXTRACK, SM_CXMINTRACK, SM_CYMAXTRACK, and SM_CYMINTRACK for more details).

You can, however, override this behaviour if you set the TRACKINGSIZE property for a form, specifying values large enough to handle your desired scaling range.

 * // Example - Ensure the form will actually scale to the min and max factors
 * //           we've set
 
 winSize     = get_Property( @window, "SIZE" )
 scaleFactor = get_Property( @window, "SCALEFACTOR" )
 
 trackingSize    = ""
 trackingSize<1> = winSize<3> * scaleFactor<2>
 trackingSize<2> = winSize<4> * scaleFactor<2>
 trackingSize<3> = winSize<3> * scaleFactor<3>
 trackingSize<4> = winSize<4> * scaleFactor<3>
 
 call set_Property( @window, "TRACKINGSIZE", trackingSize )

 

Scaling Interaction

In our next post we’ll take a look at the new SCALED event and discuss how to interact with the system during a scaling operation.

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

A last word on EditLines (for now)

We’ve taken a look over the last few posts at some of the new features we’ve added to EditLine controls, but before we leave them we’ll mention a few miscellaneous new properties that you might find useful:

  • AUTOSELECT
  • CUEBANNER
  • EXITCHARS
  • VALIDCHARS

 

AUTOSELECT Property

This is a simple boolean property.  When set to TRUE all text in the control will be selected when the EditLine is given focus.

CUEBANNER Property

This is a string property that contains the text to display when an EditLine has no data.  The text is normally displayed in a faded style to differentiate it from “real” text.  It is intended primarily to give the user a simple hint on the purpose of the EditLine, or on the format of the data it should contain.

EXITCHARS property

This property allows you to specify one or more characters as “Exit” characters, which means that if a user types any of them into the control the focus is automatically moved to the next control in tab-order as though they had hit the Tab key. This property is a simple string containing the Exit characters.

// Move to the next control if the user enters a "." or a space
exitChars = ". "
call set_Property( @window : ".EDL_IP1", "EXITCHARS", exitChars )

Note this property does not work if the PASSWORDSTYLE property is TRUE.

VALIDCHARS Property

This property allows you to specify one or more characters that are “Valid” characters, which means that the user can only enter these characters into the control. This property is a simple string containing the characters that are allowed.

// Only allow numeric characters in EDL_NUMBER
validChars = "0123456789"
call set_Property( @window : ".EDL_NUMBER", "VALIDCHARS", validChars )

Note this property does not work if the EDITMASK property is set or the PASSWORDSTYLE property is TRUE.

 

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

 

Edit controls and the Image API

In a previous post we mentioned that the EditLine control now supports the Glyph API, we’ve also extended the Image API to both EditLines and EditBoxes, along with gradient background colors and translucency.  Here are a few examples showing the results:

Gradient BACKCOLOR

EDIT Control with Gradient BACKCOLOR

EDIT Control with Gradient BACKCOLOR

TRANSLUCENCY Property

EDIT Control with TRANSLUCENCY of 50

EDIT Control with TRANSLUCENCY of 50

IMAGE Property

EDIT Control with background image

EDIT Control with background image

IMAGETRANSLUCENCY Property

EDIT Control with translucent background image

EDIT Control with translucent background image

 

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

EditLines and the Glyph API

As you know some controls in OpenInsight support a set of properties called the Glyph API, and this has now been extended to EditLine controls as well.  Of course it’s not the full API (see the supported properties below), as that wouldn’t make sense, but it does allow you to insert an image to the left or right of your text:

EditLine GLYPH

EditLine GLYPH with CueBanner

So now you can insert a handy search icon into your control, or perhaps a warning icon if the data in the control is invalid.

The following Glyph API properties are supported for EditLines:

  • GLYPH (similar to the BITMAP or IMAGE property)
  • GLYPHALIGN (Vertical and center settings are ignored)
  • GLYPHCOLORKEY
  • GLYPHCOUNT
  • GLYPHFRAMECOUNT
  • GLYPHFRAMENUMBER
  • GLYPHOFFSET
  • GLYPHORIGIN
  • GLYPHSIZE
  • GLYPHTRANSLUCENCY

 

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

EditLines and EditMasks

The ability to apply VALID and CONV properties to an EditLine control is a very powerful way to validate and format data entered in your applications, but this commonly relies on the user knowing how the data should be input without any visual clues being provided by the UI. Some formats like dates are fairly obvious, but others are not, and this can lead to user frustration when they are presented with a message box containing some cryptic and obscure error text from the depths of a custom Iconv() routine like this:

Cryptic IConv Message

Cryptic IConv Message

In order to improve this situation the EditLine control now supports a new property called EDITMASK, which allows you to specify the input format of the data in a visual manner, along with the type of character that may be entered at each character position, thus reducing the probability of typing errors and thereby leading to a smoother user experience.  For example here are two EditLine controls with an EDITMASK set for a phone number and a date respectively:

EDITMASK example

EDITMASK Phone and Date example

EDITMASK Property

This property is a dynamic array composed of three fields:

<1> The Input Mask
<2> The Format Mask
<3> The Default Character

The Input Mask is what the user sees in the control when no data has been entered.  The characters that they may edit are denoted by the “_” character, which is used as a placeholder. So, for a date the input mask could be “__/__/____”, meaning that they are allowed to edit the first two characters, the fourth and fifth character, and the last four characters. They will not be able to change either of the “\” characters.

The Format Mask controls the type of character that may be entered at each position where there is a placeholder “_” in the Input Mask. There should be one type specifier for each “_” character in the Input Mask, and a space character for the non-editable characters. The type specifiers are:

  • “D” – A digit
  • “d” – A digit or a space
  • “C” – An alpha character
  • “c” – An alpha character or space
  • “A” – an alphanumeric character
  • “a” – an alphanumeric character or space
  • “X” – a hexadecimal character
  • “x” – a hexadecimal character or space
  • “*” – any printable character
  • “+” – a “+” character, a “-” character, or space

So, for our date example we could have “dd dd dddd”. Note that the Format Mask must always be the same length as the Input Mask, otherwise the EDITMASK property will not work.

The Default Character is the character used for each invalid character in the user input. This defaults to an underscore (“_”).

To create the phone and date examples shown above you would set the following EDITMASK properties like so:

phoneMask =       " ddd ddd dddd"    |
          : @fm : "(___) ___-____"   |
          : @fm : "_"

dateMask  =       "Dd Dd dddd"        |
          : @fm : "__/__/____"        |
          : @fm : "_"

objxArray =        @window : ".EDL_PHONE"
propArray =        "EDITMASK"
dataArray =        phoneMask

objxArray := @rm : @window : ".EDL_DATE"
propArray := @rm : "EDITMASK"
dataArray := @rm : dateMask

call set_Property( objxArray, propArray, dataArray )

There are also some other supporting properties that can be used with the EDITMASK property:

  • GETMASKEDCHARSONLY
  • SETMASKEDCHARSONLY
  • MASKEDTEXT

GETMASKEDCHARSONLY property

This is a boolean property that affects how the TEXT property works when an EDITMASK property is applied.  When set to TRUE getting the TEXT property only returns the characters that can be entered by the user, ignoring any of the non-placeholder characters in the Format Mask.  By default this property is FALSE.

SETMASKEDCHARSONLY property

This is a boolean property that affects how the TEXT property works when an EDITMASK property is applied.  When set to TRUE setting the TEXT property only updates the characters that can be entered by the user, ignoring any of the non-placeholder characters in the Format Mask.  By default this property is FALSE.

MASKEDTEXT property

This property is essentially a wrapper around the normal TEXT property, behaves as if both GETMASKEDCHARSONLY and SETMASKEDCHARSONLY were set to TRUE, so in effect it is a “shorthand” way of accessing and updating the text that can be edited.

In the example below the EditLines on the right contain the MASKEDTEXT property of the EditLines on the left:

MASKEDTEXT example

MASKEDTEXT example

(EDIT: 21 Aug 15 – Corrected EDITMASK member positions)

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

Password-style EditLines

During the recent Antipodean roadshow a request was made for some new EditLine functionality typically found on mobile operating systems such as Android. Specifically this was to provide a way for a password-style edit control to allow each typed character to be shown briefly before being masked like so:

New Password Functionality

New Password Functionality

Thankfully this was a relatively simple request and we soon added two new properties to implement this:

  • PASSWORDSTYLE
  • PASSWORDPEEKTIME

 

PASSWORDSTYLE Property

This is a  boolean property that changes the EditLine into a password-entry style control when set to TRUE.  When set to FALSE the control acts as a normal EditLine. This property can be set at runtime to mask or unmask the entire password if desired.

PASSWORDPEEKTIME Property

This property contains the number of milliseconds to display an entered character before masking it.  When set to 0 the entered character is never displayed. This property also requires PASSWORDSTYLE to be set to TRUE, otherwise it has no effect.

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

The WRITEATRECORD property

The OpenInsight ATRECORD property is an easy way of updating data in your forms in a similar fashion to the way the “@Record” variable worked in Advanced Revelation, but it does suffers from one potential drawback: Any fields in the data record set via ATRECORD that are not bound to a control on the form are not updated when the form contents are saved.

Of course there is a reason for this: OpenInsight forms only update individual fields in a record when saving data rather than the entire record, and it is this capability that allows it to implement the “Ignore Self Locks” feature that means you can use more than one form to simultaneously edit data in the same record.

Still, not every scenario calls for this level of finesse, so Openinsight 10 introduces a new WINDOW property called WRITEATRECORD.  When set to TRUE$ all data set via the ATRECORD property is written to disk, just like “@Record” in Advanced Revelation.

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