Premise [download] Automation Browser Controls

[123]

File Name: Automation Browser Controls
File Submitter: 123
File Submitted: 21 Dec 2011
File Updated: 24 Dec 2011
File Category: Premise
Author: 123
Contact: Premise Forum
Version: 2.3

ABControls introduces six new user-interface Controls into Premise's AutomationBrowser and corrects an error with the existing Image Control.

1. BoundPropertyInputBox
   
   Display and edit any Text, Integer or similar property using Premise's onscreen keyboard.
2. CheckBox
   
   Display and modify any Boolean property.
3. ChildrenListBox
   
   Display a list of selectable objects. The objects can be anything in Premise Space.
4. MultiValueListBox
   
   Display a list of selectable values for a MultiValue property (enumeration).
5. ScriptTextButton
   
   Create a simple, labeled button that executes a script.
6. ToggleTextButton
   
   Displays and controls the states of a Boolean property using a simple, labeled button.

The attached zip file also includes a Module, UIControlsDemo, that demonstrates the use of all six new Controls.

Click here to download this file

 

[123]

At long last, it's finished! Presenting six new Controls that make it easier than ever to create feature-rich user-interfaces for Premise Browser.

Until now, the only thing Premise's onscreen keyboard allowed you to do was rename an object or to supply a login password. Now you can use it to modify text, integer, and date/time values. You can now have a combo-box, or listbox, display any kind of object found in Premise Space. You can create buttons with simple text-labels as opposed to requiring images. These buttons can also be used to create tabbed pages. UIControlsDemo also demonstrates how to create a dialog-box using Premise's more flexible CompositeControlsPanel as opposed to PopupDialog.

 

[123]

The ChildrenListBox Control features an "ItemContainer" property. If you leave it blank, the Control assume the items to be listed are children of the current object (hence the name ChildrenListBox). In version 2.2, ItemContainer allowed you to specify other places to find the items like in a child-container, of the current object, or any other container in Premise Space. However, without going into the ugly little details, I wasn't happy with the way I implemented it and, although it worked, it seemed like a kludge and, as we all know, kludges work only under very specific conditions.

It didn't take long for me to bump into the limitations imposed by the kludge. Here's a simple failure scenario:

1. Your module creates a new Home object called Gizmo.
2. Upon its creation, Gizmo creates a folder called Gizmos, under Premise's existing Media folder (sys.Media.Gizmos).
3. You have a ChildrenListBox Control whose ItemContainer points to: sys.Media.Gizmos.
4. All seems well and works fine.

It all falls apart after you export the Module (and its Plugins) and then try to import it on another PC. The problem is that sys.Media.Gizmos does not exist on the new PC. It won't exist until your module is imported and the Gizmo Home object is created. Unfortunately, that's far too late in the game for the ChildrenListBox! The moment the module is imported, the ChildrenListBox's ItemContainer property demands to find sys.Media.Gizmos ... and fails. Premise displays the error as an Event and you're left scratching your head wondering how to fix the problem. V2.3 fixes it and then some.



ABControls V2.3 changes the ChildrenListBox's ItemContainer property in a way that solves the problem and makes it more flexible as well. In V2.3, ItemContainer doesn't point directly to the the desired container but to an ObjectRef property you create in your module. In turn, the ObjectRef property points directly to the desired container.

ChildrenListBox's ItemContainer ---> YourObjectRef ----> DesiredContainer

Since ItemContainer points to an ObjectRef in your module, it has nothing to carp about at the moment the module is imported; the ObjectRef exists at all times. I can hear you say, yeah but ItemContainer is not pointing to the container I want; it's pointing to an ObjectRef that points nowhere. When does the ObjectRef get pointed to the right place?

The answer is so simple and elegant it'll make you smile. Shortly after your module has created the desired container, set the ObjectRef property to point to the newly created contrainer! As a result, the ChildrenListBox's ItemContainer will be pointing to the newly created container. Neat.

An added benefit of this technique ('multiple indirection'), is that you can change what the ObjectRef points to 'on-the-fly'. That means the items listed by the ChildrenListBox can be modified as needed. Here's an example:

You have two ChildrenListBox Controls, one lists people and another lists the person's phone numbers. The data is stored in Premise like so:

Media
   Contacts
	 John
	   Cell
	   Home
	 Mary
	   Office
	   Cell

The children of Contacts are John and Mary.
The children of John are Cell and Home.
The children of Mary are Office and Cell.

The first ListBox contains John and Mary. The second ListBox contains the phone numbers of whoever you selected in the first ListBox. If you pick 'John', his phone numbers (Cell, Home) appear in the Phone ListBox. If you pick 'Mary', her phone numbers (Office, Cell) appear in the Phone ListBox.

For all of that to work, the Phone ListBox's ItemContainer has to change 'on-the-fly' based on the person selected in the People ListBox. Version 2.3 ChildrenListBox can handle that situation easily.

 

[etc6849]

This is very clever way to handle things... I like it!

 

[123]

Here's a checklist for using a ChildrenListBox's ItemContainer property.

1. In the main class of your module, create an ObjectRef property (call it what you will).
2. In the ChildrenListBox, manually set its ItemContainer property to the ObjectRef property you created in step 1.
3. Add code, typically in a Class Constructor method, that sets the ObjectRef property to point to the desired container.

The attached diagram comes from the documentation and is worth further elaboration here.

In the Home view we see a UIControlsDemo object with its children objects Widgets, and a 'Foos' container holding Foo objects. Following the dotted purple line to the left, we see a fragment of a UIControlsDemo object's appearance in Premise Browser. It contains a ChildrenListBox listing the Foo objects. The other dotted purple line leads down to the Modules view where we see a fragment of the UIControlsDemo class (i.e. where UIControlsDemo is defined). The UIControlsDemo module defines several classes including UIControlsDemo, Widget, FooFolder, and Foo.

In the Plugins view, we see the Controls that define the UIControlDemo object's appearance in Premise Browser. The dotted yellow line simply shows us a ChildrenListBox Control named Foo is responsible for the combo-box we see in Premise Browser. In the Properties pane of the Plugins view, we see that the Foo Controls is a ChildrenListBox whose ItemContainer property is set to an ObjectRef property in UIControlsDemo called FooFolderPtr (see line A). FooFolderPtr is created for the sole purpose of supporting the Foo ChildrenListBox's ItemContainer property.

In the Modules view, the UIControlsDemo class has a Class Constructor method called OnCreate. Being a Class Constructor, it runs the moment a UIControlsDemo object is created. When UIControlsDemo's OnCreate executes, it creates several Widgets and a FooFolder object named 'Foos' (line C). The Modules view also shows that the FooFolder class has its own OnCreate method and its contents are visible in the diagram (follow line B ). It does three things but the one of interest to us is that it makes FooFolderPtr point to the newly created FooFolder object (i.e. 'Foos') using one line of code:

set this.Parent.FooFolderPtr = this

At the moment 'Foos', a FooFolder object, is created it automatically sets FooFolderPtr to point to 'Foos'. All of the linkages are now in place:
Foo ChildrenListBox's ItemContainer ---> UIControlsDemo's FooFolderPtr ---> Home.UIControlsDemo.Foos

If the ChildrenListBox will be displaying child-objects of the current object, the ItemContainer property is simply left blank.

 

[123]

PROBLEM
Premise's onscreen keyboard eliminates the first single-quote in a string.

EXAMPLE
If you use it to enter the following:
Planning Fred's birthday party is Lucy's task.

Upon clicking the ENTER key, Premise's keyboard will return this:
Planning Freds birthday party is Lucy's task.

This was never a problem in the past because Premise's keyboard was only used to rename Premise objects. Since an object's name must comply with Visual Basic's naming rules, a single-quote is illegal anyway. However, now that the keyboard is used by the BoundPropertyInputBox Control, single-quotes are commonly used in phrases.

SOLUTION
You need to alter the JavaScript code that returns the typed phrase.

Using Windows Explorer, navigate to \Premise\sys\web\plugins\SYSConnector_default.htm and clear the file's Read-Only flag. Open the file with a text-editor and scroll to line 625. You're in the right place if you see this bit of JavaScript:

 case "ENTER":
  FE(g_kbdObject, "OnOk('" + myEdit.value + "')");
  HandleClose();
  ShowCombos();
  break;

Change this:

FE(g_kbdObject, "OnOk('" + myEdit.value + "')");

to this:

FE(g_kbdObject, "OnOk(\"" + myEdit.value + "\")");

Save and close the file. Enable its Read-Only flag. Restart Premise SYS Server so that it reloads the modified SYSConnector_default.htm file.

This modification will preserve the first single-quote in a phrase. However, it will not prevent the elimination of the first double-quote.