Quartam Software - developing thoughts

StyledImageView custom control in LiveCode (part 2)

2011-11-06T05:02:00.001-08:00

In the previous post, we started to work on a StyledImageView custom control, inspired by chapter 10 of the book 'Objective-C and Cocoa: Up and running' by Scott Stevenson. Just as a reminder, here's the original we're trying to mimic:

How far did we get last time?

- A background gradient behind the image
- An image with a 4px white border
- A drop shadow below the image

And our custom control group has a behavior button script to handle resizing and toggling the display of the drop shadow. Now we come to the tricky part:

- A sheen over the image

Perhaps it's best to explain what a 'sheen' is: a visual effect that displays a glossy white overlay, clipped to a bezier curve, rendering the illusion of a light source in the upper-left corner of the image. Cute, but how does one implement it? Scott used a linear gradient (tilted slightly to enhance the illusion) to fill a path determined by the edges of the image and a bezier path. As LiveCode doesn't have bezier curves on offer, it was time to think a bit differently.

Let's start with the gradient. Linear gradients are not too difficult to implement; but we have to give it the right angle. Trigonometry has never been my best subject, but I remembered anough to figure out how to rotate the gradient by 10 degrees. And the LiveCode documentation came with example code for converting degrees to radians.
Here's an update for the "Create" button:


on mouseUp
   local tGroup
   CreateCustomControlGroup "StyledImageView", tGroup
   CreateBackgroundGraphic tGroup
   CreateViewImage tGroup
   CreateSheen tGroup
   set the behavior of tGroup to the long id of button "StyledImageView Behavior"
   set the showShadow of tGroup to true
end mouseUp

private command CreateCustomControlGroup pGroupName, @rGroupId
   -- same as before, omitting for brevity
end CreateCustomControlGroup

private command CreateBackgroundGraphic pGroup
   -- same as before, omitting for brevity
end CreateBackgroundGraphic

private command CreateViewImage pGroup
   -- same as before, omitting for brevity
end CreateViewImage

private command CreateSheen pGroup
   CreateSheenGradient pGroup
end CreateSheen

private command CreateSheenGradient pGroup
   reset the templateGraphic
   set the style of the templateGraphic to "Rectangle"
   set the rectangle of the templateGraphic to 30,130,370,310
   set the lineSize of the templateGraphic to 0
   set the opaque of the templateGraphic to true
   set the fillGradient["type"] of the templateGraphic to "linear"
   set the fillGradient["from"] of the templateGraphic to 30,130
   set the fillGradient["to"] of the templateGraphic to 61,307
   set the fillGradient["via"] of the templateGraphic to 207,99
   set the fillGradient["ramp"] of the templateGraphic to \
         "0.00000,255,255,255" & return & \
         "0.40000,255,255,255,51" & return & \
         "0.79999,255,255,255,13" & return & \
         "0.80000,255,255,255,0" & return & \
         "1.00000,255,255,255,0"
   create graphic "GradientGraphic" in pGroup
   reset the templateGraphic
end CreateSheenGradient

Delete the existing custom control group and hit the button again. You should see the gradient graphic on top of the image control.

We'll also have to update the resizing logic in our behavior script, but I'll leave that for later. Our next challenge is the bezier curve, and how we can construct a path to clip the gradient to it. And then it struck me: we can achieve the same effect (in this case) by creating an oval graphic and then clip that out of the gradient graphic.

Inspiration came from an old blog post by RunRev's Mark Waddingham. The original blog is no onger on the web, but thanks to the Wayback Machine internet archive, I was able to dig up this snapshot. Here's the gist: you take two control, comlbine them into a group, and then use different blend modes for the group and graphics to achieve soft clipping.
The only difference: Mark talks about clipping something down to a graphic shape, whereas I wanted to clip a graphic shape out of the original shape. But as it turns out to, this was as easy as picking a different blend mode for the clipping graphic. So let's use this knowledge to once more update the "Create" button:


on mouseUp
   local tGroup
   CreateCustomControlGroup "StyledImageView", tGroup
   CreateBackgroundGraphic tGroup
   CreateViewImage tGroup
   CreateSheen tGroup
   set the behavior of tGroup to the long id of button "StyledImageView Behavior"
   set the showShadow of tGroup to true
end mouseUp

private command CreateCustomControlGroup pGroupName, @rGroupId
   -- same as before, omitting for brevity
end CreateCustomControlGroup

private command CreateBackgroundGraphic pGroup
   -- same as before, omitting for brevity
end CreateBackgroundGraphic

private command CreateViewImage pGroup
   -- same as before, omitting for brevity
end CreateViewImage

private command CreateSheen pGroup
   local tSheenGroup
   reset the templateGroup
   set the rectangle of the templateGroup to 30,130,370,310
   set the lockLocation of the templateGroup to true
   set the margins of the templateGroup to 0
   set the ink of the templateGroup to "blendSrcOver"
   create group "SheenGroup" in pGroup
   put it into tSheenGroup
   reset the templateGroup
   CreateSheenGradient tSheenGroup
   CreateSheenClipping tSheenGroup
end CreateSheen

private command CreateSheenGradient pGroup
   -- same as before, omitting for brevity
end CreateSheenGradient

private command CreateSheenClipping pGroup
   reset the templateGraphic
   set the style of the templateGraphic to "Oval"
   set the rectangle of the templateGraphic to 10,10,10,10
   set the ink of the templateGraphic to "blendDstOut"
   set the lineSize of the templateGraphic to 0
   set the opaque of the templateGraphic to true
   create graphic "ClippingGraphic" in pGroup
   set the rectangle of it to -21,154,761,586
   reset the templateGraphic
end CreateSheenClipping

Delete the existing custom control group and hit the button again.

Getting there - now we just need to extend the behavior script with the logic to properly resize these new parts:


## engine message handlers

on mouseDoubleUp
   -- same as before, omitting for brevity
end mouseDoubleUp

on resizeControl
   -- same as before, omitting for brevity
end resizeControl

## property setters and getters

setProp showShadow pShowShadowBoolean
   -- same as before, omitting for brevity
end showShadow

setProp showSheen pShowSheenBoolean
   set the visible of group "SheenGroup" of me to pShowSheenBoolean
end showSheen

getProp showSheen
   return the visible of group "SheenGroup" of me
end showSheen

setProp imageFileName pFileName
   -- same as before, omitting for brevity
end imageFileName

getProp imageFileName
   -- same as before, omitting for brevity
end imageFileName

## private commands and functions

private command SIV_ReshapeControl
   local tImageRectangle
   SIV_DetermineImageRectangle tImageRectangle
   SIV_ReshapeBackground
   SIV_ReshapeImage tImageRectangle
   SIV_ReshapeSheen tImageRectangle
end SIV_ReshapeControl

private command SIV_DetermineImageRectangle @rImageRectangle
   -- same as before, omitting for brevity
end SIV_DetermineImageRectangle

private command SIV_ReshapeBackground
   -- same as before, omitting for brevity
end SIV_ReshapeBackground

private command SIV_ReshapeImage pImageRectangle
   -- same as before, omitting for brevity
end SIV_ReshapeImage

private command SIV_ReshapeSheen pImageRectangle
   set the rectangle of group "SheenGroup" of me to pImageRectangle
   local tImageWidth, tImageHeight
   put (item 3 of pImageRectangle) - (item 1 of pImageRectangle) into tImageWidth
   put (item 4 of pImageRectangle) - (item 2 of pImageRectangle) into tImageHeight
   --> reshape the gradient rect
   local tGradientRectangle, tGradientHeight, tFromPoint, tToPoint, tViaPoint
   put pImageRectangle into tGradientRectangle
   put trunc(tImageHeight * 0.75) into tGradientHeight
   put ((item 2 of tGradientRectangle) + tGradientHeight) into item 4 of tGradientRectangle
   put   (item 1 of tGradientRectangle), \
         (item 2 of tGradientRectangle) \
         into tFromPoint
   put   ((item 1 of tGradientRectangle) + trunc(SIV_SinInDegrees(10) * tGradientHeight)), \
         ((item 2 of tGradientRectangle) + trunc(SIV_CosInDegrees(10) * tGradientHeight)) \
         into tToPoint
   put   ((item 1 of tGradientRectangle) + trunc(SIV_SinInDegrees(80) * tGradientHeight)), \
         ((item 2 of tGradientRectangle) - trunc(SIV_CosInDegrees(80) * tGradientHeight)) \
         into tViaPoint
   set the rectangle of graphic "GradientGraphic" of group "SheenGroup" of me to tGradientRectangle
   set the fillGradient["from"] of graphic "GradientGraphic" of group "SheenGroup" of me to tFromPoint
   set the fillGradient["to"] of graphic "GradientGraphic" of group "SheenGroup" of me to tToPoint
   set the fillGradient["via"] of graphic "GradientGraphic" of group "SheenGroup" of me to tViaPoint
   --> reshape the clipping oval
   local tClippingRectangle, tXRadius, tYRadius
   put trunc(tImageWidth * 1.15) into tXRadius
   put trunc(tImageHeight * 0.9) into tYRadius
   put   ((item 3 of pImageRectangle) - tXRadius), \
         ((item 4 of pImageRectangle) - tYRadius), \
         ((item 3 of pImageRectangle) + tXRadius), \
         ((item 4 of pImageRectangle) + tYRadius) \
         into tClippingRectangle
   set the rectangle of graphic "ClippingGraphic" of group "SheenGroup" of me to tClippingRectangle
end SIV_ReshapeSheen

private function SIV_SinInDegrees angleInDegrees
   return sin(angleInDegrees * pi / 180)
end SIV_SinInDegrees

private function SIV_CosInDegrees angleInDegrees
   return cos(angleInDegrees * pi / 180)
end SIV_CosInDegrees

Delete the existing custom control group and hit the "Create" button again. Then double-click to select an image. I downloaded and selected the original image that Scott used - a public domain image from NASA.

I would say that this looks like the original StyledImageViewClass. Next time, we'll take this custom control a bit further, by turning it into a DropTool. Stay tuned...

StyledImageView custom control in LiveCode

2011-11-01T11:07:00.000-07:00

In an effort to get back into native development on MacOS X, I've been working my way through the book 'Cocoa and Objective-C: Up and running' by Scott Stevenson. Chapter 10 (Custom Views and Drawing) describes step by step how to build a StyledImageView class.
And I have to say it looks pretty nice:

Curious as ever, I started to wonder how this same effect could be achieved as a custom control in LiveCode. What do we have conceptually?
- A background gradient behind the image
- An image with a 4px white border
- A drop shadow below the image
- A sheen over the image
The first three items are quite straightforward; but the sheen proved more difficult.

Let's get started. Note that I'm doing all my control creation and property settings via script. Just drop a button onto a new stack, set its script, and click on the button to get the custom control group. The first thing we want is the group itself and gradient background; easy enough:


on mouseUp
   local tGroup
   CreateCustomControlGroup "StyledImageView", tGroup
   CreateBackgroundGraphic tGroup
end mouseUp

private command CreateCustomControlGroup pGroupName, @rGroupId
   reset the templateGroup
   set the margins of the templateGroup to 0
   create group pGroupName
   put it into rGroupId
   reset the templateGroup
end CreateCustomControlGroup

private command CreateBackgroundGraphic pGroup
   reset the templateGraphic
   set the style of the templateGraphic to "Rectangle"
   set the rectangle of the templateGraphic to 0,0,400,300
   set the lineSize of the templateGraphic to 0
   set the opaque of the templateGraphic to true
   set the fillGradient["type"] of the templateGraphic to "linear"
   set the fillGradient["from"] of the templateGraphic to 0,300
   set the fillGradient["to"] of the templateGraphic to 0,0
   set the fillGradient["via"] of the templateGraphic to 400,300
   set the fillGradient["ramp"] of the templateGraphic to \
         "0.00000,45,45,45" & return & "1.00000,89,89,89"
   create graphic "BackgroundGraphic" in pGroup
   reset the templateGraphic
end CreateBackgroundGraphic

Here's the result of clicking on the button:

Now let's add in the image. Something that initially trips up a lot of new LiveCode developers is that an image will happily jump back to its original size if you don't set the 'lockLocation' of the image to "true". Another quirk is that you can't set the borderColor of an image control directly. However, it does 'inherit' the borderColor from the chain of owners (the containing group if applicable, the card or the stack) so to make sure we get a white border, we need to set the borderColor of our custom control group. So the following update to the button script will do nicely:


on mouseUp
   local tGroup
   CreateCustomControlGroup "StyledImageView", tGroup
   CreateBackgroundGraphic tGroup
   CreateViewImage tGroup
end mouseUp

private command CreateCustomControlGroup pGroupName, @rGroupId
   reset the templateGroup
   set the margins of the templateGroup to 0
   set the borderColor of the templateGroup to "white"
   create group pGroupName
   put it into rGroupId
   reset the templateGroup
end CreateCustomControlGroup

private command CreateBackgroundGraphic pGroup
   -- same as before, omitting for brevity
end CreateBackgroundGraphic

private command CreateViewImage pGroup
   reset the templateImage
   set the rectangle of the templateImage to 30,30,370,270
   set the borderWidth of the templateImage to 4
   set the threeD of the templateImage to false
   set the showBorder of the templateImage to true
   set the resizeQuality of the templateImage to "best"
   set the lockLocation of the templateImage to true
   create image "ViewImage" in pGroup
   reset the templateImage
end CreateViewImage

Delete the existing custom control group, and hit the button again. Here's what you should see:

Next up is the drop shadow for the image. While we could do this by setting the properties in the 'CreateViewImage' command above, I think it's better of we don't repeat code, and put that in the custom control group script - after all, we want to be able to toggle it via script. So let's drop another button on the stack, set its name to "StyledImageView Behavior" and start scripting that button. Later on, we'll set the 'behavior' property of the custom control group.

The most important item in the behavor script is handling resizing. We want to leave a margin of 10% around the image so that we can see the gradient background, and we want to scale the image proportionately rather than stretch it out. While we're add it, we'll add some custom property setters and getters for the drop shadow and the image file name. And we'll add a 'mouseDoubleUp' handler to allow the user to select an image. Here is the first version of the behavior script:


## engine message handlers

on mouseDoubleUp
   answer file "Select an image to view"
   if it is empty then exit mouseDoubleUp
   set the imageFileName of me to it
   pass mouseDoubleUp
end mouseDoubleUp

on resizeControl
   SIV_ReshapeControl
   pass resizeControl
end resizeControl

## property setters and getters

setProp showShadow pShowShadowBoolean
   if pShowShadowBoolean is "true" then
      local tDropShadow
      put 0,0,0 into tDropShadow["color"]
      put 8 into tDropShadow["size"]
      put 6 into tDropShadow["distance"]
      put 90 into tDropShadow["angle"]
      put 0 into tDropShadow["spread"]
      put 255 into tDropShadow["opacity"]
      put "normal" into tDropShadow["blendmode"]
      put "box3pass" into tDropShadow["filter"]
      put true into tDropShadow["knockout"]
      set the dropShadow of image "ViewImage" of me to tDropShadow
   else
      set the dropShadow of image "ViewImage" of me to empty
   end if
   pass showShadow
end showShadow

setProp imageFileName pFileName
   set the fileName of image "ViewImage" of me to pFileName
   SIV_ReshapeControl
end imageFileName

getProp imageFileName
   return the fileName of image "ViewImage" of me
end imageFileName

## private commands and functions

private command SIV_ReshapeControl
   local tImageRectangle
   SIV_DetermineImageRectangle tImageRectangle
   SIV_ReshapeBackground
   SIV_ReshapeImage tImageRectangle
end SIV_ReshapeControl

private command SIV_DetermineImageRectangle @rImageRectangle
   -- 10% margin around the image while preserving the aspect ratio
   local tSourceWidth, tSourceHeight, tTargetWidth, tTargetHeight
   put the formattedWidth of image "ViewImage" of me into tSourceWidth
   put the formattedHeight of image "ViewImage" of me into tSourceHeight
   put (the width of me) * 0.8 into tTargetWidth
   put (the height of me) * 0.8 into tTargetHeight
   -- make sure we don't get divide by zero errors
   if tSourceWidth = 0
   then put 1 into tSourceWidth
   if tSourceHeight = 0
   then put 1 into tSourceHeight
   local tScaleFactor, tImageWidth, tImageHeight
   put min(tTargetWidth / tSourceWidth, tTargetHeight / tSourceHeight) into tScaleFactor
   put trunc(tSourceWidth * tScaleFactor) into tImageWidth
   put trunc(tSourceHeight * tScaleFactor) into tImageHeight
   local tLeft, tTop
   put (the left of me) + (((the width of me) - tImageWidth) div 2) into tLeft
   put (the top of me) + (((the height of me) - tImageHeight) div 2) into tTop
   put tLeft,tTop,(tLeft + tImageWidth),(tTop + tImageHeight) into rImageRectangle
end SIV_DetermineImageRectangle

private command SIV_ReshapeBackground
   set the rectangle of graphic "BackgroundGraphic" of me to the rectangle of me
end SIV_ReshapeImage

private command SIV_ReshapeImage pImageRectangle
   set the rectangle of image "ViewImage" of me to pImageRectangle
end SIV_ReshapeImage

So just a little tweak to our 'Create' button script is required to set the behavior and activate the drop shadow:


on mouseUp
   local tGroup
   CreateCustomControlGroup "StyledImageView", tGroup
   CreateBackgroundGraphic tGroup
   CreateViewImage tGroup
   set the behavior of tGroup to the long id of button "StyledImageView Behavior"
   set the showShadow of tGroup to true
end mouseUp

private command CreateCustomControlGroup pGroupName, @rGroupId
   -- same as before, omitting for brevity
end CreateCustomControlGroup

private command CreateBackgroundGraphic pGroup
   -- same as before, omitting for brevity
end CreateBackgroundGraphic

private command CreateViewImage pGroup
   -- same as before, omitting for brevity
end CreateViewImage

One more thing to do before we call it a day: handle the 'resizeStack' message in the card script, so that we automatically resize the custom control group as the user changes the stack size. Just plop the following into the card script:


on resizeStack pNewWidth, pNewHeight
   if there is a group "StyledImageView" then
      local tRectangle
      put the rectangle of group "StyledImageView" into tRectangle
      put pNewWidth into item 3 of tRectangle
      put pNewHeight into item 4 of tRectangle
      set the rectangle of group "StyledImageView" to tRectangle
   end if
   pass resizeStack
end resizeStack

Delete the existing custom control group and hit the button again. The embedded image control now has a nice drop shadow, which we can turn off and on using the message box or by scripting a simple checkbox button.

And when you double-click on the custom control, you can select an image file and the embedded image control automagically reshapes in order to display the chosen image file proportionately.

Looks good doesn't it? Next time, we'll tackle the sheen. It's tricky, but it can be done!

MacOSX standard artwork in LiveCode

2011-10-02T09:12:00.000-07:00

When you develop an application for Mac, users have certain expectations about how your app will look and behave. One of the often forgotten parts of your user interface is the icon artwork - it is very tempting to simply buy an icon collection and then use it everywhere in your cross-platform application. However, to help developers achieve a consistent user interface, across multiple versions of the operating system, Apple has been adding 'template' images to its Cocoa NSImage class.

Here are a few examples which I recently used in a project:

For a complete list of the available template images, look here.

Great stuff, but how are we going to get at it from LiveCode? Not directly, I'm afraid. But all is not lost: a while back, Apple's Java engineers added to their Java implementation on MacOS X 10.5 Leopard (and later) the ability to fetch these images using a simple call:

Toolkit.getDefaultToolkit().getImage("NSImage://NSColorPanel")

You can see where I'm heading with this: writing a helper Java class that you can execute with a simple 'shell' function call. So let's start by writing up the Java class code. We'll set it up with two parameters: the first parameter accepts either "*" (to say you want a complete set of images) or a comma-separated list of image names; the second parameter is the output directory where the available images will be saved in PNG format.


import java.awt.Graphics;
import java.awt.Image;
import java.awt.Toolkit;
import java.awt.image.BufferedImage;
import java.io.File;
import java.io.IOException;
import java.util.EnumSet;
import javax.imageio.ImageIO;

public class NSImageFetcher {

    public enum NSImageName {
        // Image Template Constants
        NSQuickLookTemplate,
        NSBluetoothTemplate,
        NSIChatTheaterTemplate,
        NSSlideshowTemplate,
        NSActionTemplate,
        NSSmartBadgeTemplate,
        NSPathTemplate,
        NSInvalidDataFreestandingTemplate,
        NSLockLockedTemplate,
        NSLockUnlockedTemplate,
        NSGoRightTemplate,
        NSGoLeftTemplate,
        NSRightFacingTriangleTemplate,
        NSLeftFacingTriangleTemplate,
        NSAddTemplate,
        NSRemoveTemplate,
        NSRevealFreestandingTemplate,
        NSFollowLinkFreestandingTemplate,
        NSEnterFullScreenTemplate,
        NSExitFullScreenTemplate,
        NSStopProgressTemplate,
        NSStopProgressFreestandingTemplate,
        NSRefreshTemplate,
        NSRefreshFreestandingTemplate,
        NSFolder,
        NSTrashEmpty,
        NSTrashFull,
        NSHomeTemplate,
        NSBookmarksTemplate,
        NSCaution,
        NSStatusAvailable,
        NSStatusPartiallyAvailable,
        NSStatusUnavailable,
        NSStatusNone,
        NSApplicationIcon,
        NSMenuOnStateTemplate,
        NSMenuMixedStateTemplate,
        NSUserGuest,
        NSMobileMe,
        // Multiple Documents Drag Image
        NSMultipleDocuments,
        // Sharing Permissions Names Images
        NSUser,
        NSUserGroup,
        NSEveryone,
        // System Entity Images
        NSBonjour,
        NSDotMac,
        NSComputer,
        NSFolderBurnable,
        NSFolderSmart,
        NSNetwork,
        // Toolbar Named Images
        NSUserAccounts,
        NSPreferencesGeneral,
        NSAdvanced,
        NSInfo,
        NSFontPanel,
        NSColorPanel,
        // View Type Template Images
        NSIconViewTemplate,
        NSListViewTemplate,
        NSColumnViewTemplate,
        NSFlowViewTemplate;
    }

    
    public static Image getNSImage(final NSImageName nsImageName) {
        return getNSImage(nsImageName.name());
    }
    
    public static Image getNSImage(final String nsImageName) {
        return Toolkit.getDefaultToolkit().getImage("NSImage://" + nsImageName);
    }

    public static void saveNSImage(final NSImageName nsImageName, final File outputFile) throws IOException {
        saveNSImage(nsImageName.name(), outputFile);
    }
    
    public static void saveNSImage(final String nsImageName, final File outputFile) throws IOException {
        final Image nsImage = getNSImage(nsImageName);
        if (nsImage != null) {
            BufferedImage bufferedImage = null;
            if (nsImage instanceof BufferedImage) {
                bufferedImage = (BufferedImage) nsImage;
            } else {
                bufferedImage = new BufferedImage(nsImage.getWidth(null), nsImage.getHeight(null), BufferedImage.TYPE_INT_ARGB);
                final Graphics bufImgGraphics = bufferedImage.getGraphics();
                bufImgGraphics.drawImage(nsImage, 0, 0, null);
            }
            if (!outputFile.exists()) {
                outputFile.createNewFile();
            }
            ImageIO.write(bufferedImage, "png", outputFile);
        }
    }
    
    public static void main(String[] args) throws IOException {
        // We can't run in headless mode or we get empty icons
        //    System.setProperty("java.awt.headless", "true");

        if (args.length != 2) {
            System.out.println("Usage: java NSImageFetcher <list of NSImageNames>,<output directory>");
            return;
        }
        final File outputDirectory = new File(args[1]);
        if ("*".equals(args[0])) {
            for (final NSImageName nsImageName : EnumSet.allOf(NSImageName.class)) {
                final File outputFile = new File(outputDirectory.getAbsolutePath() + File.separator + nsImageName.name() + ".png");
                saveNSImage(nsImageName, outputFile);
            }
        } else {
            for (final String nsImageName : args[0].split(",")) {
                try {
                    final File outputFile = new File(outputDirectory.getAbsolutePath() + File.separator + nsImageName + ".png");
                    saveNSImage(nsImageName, outputFile);
                } catch (IllegalArgumentException e) {
                    // ignore
                }
            }
        }
    }
}

And here's the LiveCode button script to put all the images into a subdirectory 'resources' in the directory where the stack is saved:


on mouseUp
   -- save settings
   local tOldDefaultFolder, tOldHideConsoleWindows
   put the defaultFolder into tOldDefaultFolder
   set the defaultFolder to StackFolderPath()
   put the hideConsoleWindows into tOldHideConsoleWindows
   set the hideConsoleWindows to true
   -- call the command line via shell
   local tShellCommand, tShellResult
   put "java NSImageFetcher" && \
         quote & "*" & quote && \
         quote & StackFolderPath("resources") & quote into tShellCommand
   answer tShellCommand & return & shell(tShellCommand)
   -- restore settings
   set the defaultFolder to tOldDefaultFolder
   set the hideConsoleWindows to tOldHideConsoleWindows
   -- go ahead and link
end mouseUp

function StackFolderPath pRelativePath
   local tPath
   put the effective filename of this stack into tPath
   set the itemDelimiter to slash
   if pRelativePath is empty then
      delete item -1 of tPath
   else
      put pRelativePath into item -1 of tPath
   end if
   return tPath
end StackFolderPath

Okay, MacOSX comes with a preinstalled Java runtime so the above should work on MacOSX 10.5 Leopard, MacOSX 10.6 Snow Leopard and even on MacOSX 10.7 Lion (since there's still a Java 6 'out of the box'). Naturally, the artwork may change between operating system versions. So my approach would be to:
- check if there is a '<MyCompanyName>/<MyAppName>/resources' directory in the user's preferences directory (by means of the 'specialFolderPath' function);
- if the directory is absent, create it and use the 'shell' function as above to fetch the images I need, and save the 'systemVersion' in a text file in the same directory
- if the directory is present, compare the current value of the 'systemVersion' with the one saved in said directory, and once again fetch the images if there's a difference

It's up to you to either use references to these .PNG images by setting the 'filename' property of an 'image' control; or to then import the .PNG files into a stack.

Note that this artwork is copyrighted by Apple, Inc. You shouldn't extract it and then use it in your apps on any platform other than MacOSX. Oh, and please head the warning "You should always use named images according to their intended purpose, and not according to how the image appears when loaded. The appearance of images can change between releases. If you use an image for its intended purpose (and not because of it looks), your code should look correct from release to release."

Determining the Aqua UI appearance on MacOS X

2011-09-25T11:46:00.000-07:00

Due to high workload at the day-job, I haven't been able to keep my schedule regarding the experiment building a Ribbon custom control for LiveCode. It's still going to happen, but is going to take a bit longer than planned. In the meantime, I will post some tidbits that are relevant to those that design custom controls for LiveCode.

In MacOS X, the Preferences application has a panel titled Appearance:

Yeah, I know I'm still on MacOS X Snow Leopard 10.6.8 - just waiting for Lion 10.7.2 before I upgrade.
Anyway, the Appearance option menu has two entries: Blue and Graphite.

Below that option menu, is the Highlight color option menu; and if we want to know this color in our LiveCode scripts, all we have to do is check the global 'hiliteColor' property. But there's no built-in way to access the Appearance. So how can we get this information? Do we have to write an external to find out whether we should have blue or graphite custom controls?

As it turns out, we can get at this system setting by using the 'defaults' command via the 'shell' function. Just plop the following in a button script:


on mouseUp
   local tVariant, tAppearance
   put word 1 to -1 \
       of shell("defaults read -g AppleAquaColorVariant") \
       into tVariant
   switch tVariant
      case 1
         put "Blue" into tAppearance
         break
      case 6
         put "Graphite" into tAppearance
         break
      default
         put "Unrecognized appearance variant [" & \
             tVariant & "]" into tAppearance
         break
   end switch
   answer tAppearance
end mouseUp

Click the button, and depending on your operating system and preferences setting, you'll see the appropriate message. It appears that at one point there were a few more appearances, but they were lost during a chopping frenzy in Cupertino. Be that as it may, you now have a way to check for the appearance setting in the preferences window.

Experimenting with ribbons in LiveCode (part 4)

2011-08-07T12:03:00.000-07:00

Four weeks ago, we kicked off an experiment to create a ribbon control for LiveCode. By now, we have a clear goal, derived an initial XML structure for our 'ribbonText' property, and in the previous post, we finally got some visual work done, implementing the ribbon background and tabs. The next logical step is to implement our ribbon groups.

There is actually more to a ribbon group than initially meets the eye:
- groups can have an associated dialog (e.g. to call up the classic font dialog)
- groups can be added to the quick access toolbar
- groups have rules for dynamic resizing

But we'll postpone these juicier bits until wev'e gotten around to actually adding buttons to our ribbon control. Right now, our goal is to turn the group definitions in our ribbonText property into controls. First we extend the ribbonText parser to also read the <Group> definitions from the XML structure, and then we add the necessary code to the 'qrtRexRibbonGroupsBehavior' script. Under our current (limited) interpretation, each ribbon group is nothing more than the label and the separator next to it.

Once more, I've opted for the approach of taking a slice from a screenshot to represent the separator, as I couldn't get the stroke and fill gradients of a graphic to exactly mirror the original. Maybe one of these days I'll throw out the images and replace them all with gradients anyway - but today is not that day. At any rate, with just two controls to add, it's pretty easy.

And by separating out the code that triggers the population of the nested RibbonGroups custom control group, we can easily switch ribbon group sets by handling the custom 'ribbonTabPick' event that is dispatched from the nested RibbonTabs custom control group which we implemented in the previous post.

Download the current revision here - next time we'll tackle the buttons.

Experimenting with ribbons in LiveCode (part 3)

2011-08-02T14:03:00.001-07:00

Three weeks ago, we kicked off an experiment to create a ribbon control for LiveCode. By now, we have a good plan, and we have an initial XML structure for our 'ribbonText' property. So let's go ahead and start putting together some code! Let's start with the ribbon background and header area, shall we?

I really wanted to do it all with only graphics, gradients and effects, but I couldn't quite get the details right. So eventually I went for the oldest trick in the book: I took a screenshot and then extracted three slices from the image: 2 pixels wide for the left and right edge, and then 1 pixel wide for the center. You can't use this slice as a pattern for another control, but you can just stretch that image as far as you need: because the original is only 1 pixel wide, the engine can stretch the image at a low cost, because there is no interpolation required.

Let's get a head start on the ApplicationMenu button: take some more screenshots while hovering and after clicking on it; then extract the images for each state of the ApplicationMenu; drop in a button and assign the appropriate image ids for the button's regular, hilited and hover icons. This is not the time for the menu itself, though, so let's move on to the ribbon tabs.

But before that, let's drop in a field "RibbonText" and a button to apply it to our ribbon group. It will make testing a whole lot easier as we go and add features.

Pop quiz: what is the fastest way to create a custom tab header in LiveCode?
Answer: why, a radio button group, of course!

I know what you're thinking: "Hold on, have you lost your marbles? Doesn't a group of radio buttons look like this?"

Well, sure - but by setting a few properties, you can turn that into this:

And that's accomplished without any scripting; once you start handling mouse event messages, you can dynamically apply graphic effects to even greater effect. But that won't suffice for our ribbon, I'm afraid, altough the principle stands: a group of 'radio buttons' can adequately implement our ribbon tabs, as long as they don't have to do it on their own...

There are several factors that determine a ribbon tab's appearance: whether or not the tab is hilited, whether or not the mouse is hovering over the tab, and whether the mouse is pressed or not. So we will enlist the help of some image controls to achieve each of these appearances.

Once again, we use an image editor to take three slices from a screenshot: one for the left edge, one for the right edge, and another to serve as a background, stretched accross the gap. Rinse and repeat for each appearance. The width of the tab can be calculated by taking the formattedWidth of the button, and adding another eighteen pixels, nine on each side, for good measure.

With our approach clearly outlined, we can code the creation of all the controls needed for the ribbon tabs, one tab at a time: first we create the three images for the tab, and then a heavily modified radio button; next, we determine the correct rectangle of our tab button, and adapt the rectangles of our three backing images to match; finally, we inject copies of the appropriate original images; and all the layers are as we would expect.

As soon as we have the tab creation working correctly, we can code the necessary engine event message handlers, property getters and setters, as well as a splash of private commands to make the ribbon tabs act like the real deal. I'd rather not paste the code into this blog post - just download the current revision here and take a good look at the scripts in the qrtRexBehaviors substack.

Next time, we'll tackle the creation of groups - and the weather is still a bit of a mess, so check back soon!

Experimenting with ribbons in LiveCode (part 2)

2011-07-24T12:14:00.000-07:00

In an earlier post, we kicked off a series on the construction of a ribbon using pure LiveCode. For now, we'll concentrate on the Windows 7 Wordpad look-and-feel, but future posts will refine it for cross-platform consistency. After looking into Ribbon components such as Infragistics NetAdvantage WinToolbars and Microsoft Ribbon for WPF, I pondered how a developer would define and customize our ribbon implementation.

For better or worse, I opted for the developer setting the 'ribbonText' property of our custom control group, and that this property would be an XML structure. So let's break the ribbon down into pieces, break those pieces down into other pieces, and so on. Initially, one would think that the ribbon is a set of tabs, each with their own groups, each with their own buttons. But there's a little more to the story: there are several types of buttons, and aren't we glossing over the application menu and quick access toolbar?
Plus, we need some centralized management for what these buttons, menuitems, etc. look like, what label they have, etc. Microsoft calls it a 'RibbonCommand', but since theseribbon items could also be toggle buttons, that spounded odd - so I think we'll stick with the Infragistics terminology of 'Tool' - far more neutral. This tool will also include a 'message' that is sent when the user clicks the button.

So here's a first example of our ribbonText XML structure:


<?xml version="1.0"?>
<Ribbon>
  <Tools>
    <Tool ToolId="CutTool" Label="Cut" Message="CutText"/>
    <Tool ToolId="CopyTool" Label="Copy" Message="CopyText"/>
  </Tools>
  <Tabs>
    <Tab TabId="HomeTab" Label="Home">
      <Groups>
        <Group GroupId="ClipboardGroup" Label="Clipboard">
          <GroupItems>
            <CommandButton ToolId="CutTool" />
            <CommandButton ToolId="CopyTool" />
          </GroupItems>
        </Group>
      </Groups>
    </Tab>
  </Tabs>
</Ribbon>

As you can see, the Tool entry defines the label and message, and the CommandButton instance referenes that Tool via its ToolId attribute. Now let's add two more things to the mix: DropMenuButton and SplitMenuButton - clicking on the former will drop down a menu, whereas clicking the latter has different results, depending on where you click: it either executes the main function, or drops down a menu.


<?xml version="1.0"?>
<Ribbon>
  <Tools>
    <Tool ToolId="CutTool" Label="Cut" Message="CutText"/>
    <Tool ToolId="CopyTool" Label="Copy" Message="CopyText"/>
    <Tool ToolId="PasteTool" Label="Paste" Message="PasteText"/>
    <Tool ToolId="PasteSpecialTool" Label="Paste special" Message="PasteSpecial"/>
    <Tool ToolId="InchesTool" Label="Inches" Message="SwitchToInches"/>
    <Tool ToolId="CentimetersTool" Label="Centimeters" Message="SwitchToCentimeters"/>
    <Tool ToolId="PointsTool" Label="Points" Message="SwitchToPoints"/>
  </Tools>
  <Tabs>
    <Tab TabId="HomeTab" Label="Home">
      <Groups>
        <Group GroupId="ClipboardGroup" Label="Clipboard">
          <GroupItems>
            <SplitMenuButton ToolId="PasteTool">
              <MenuItems>
                <CommandButton ToolId="PasteTool" />
                <CommandButton ToolId="PasteSpecialTool" />
              </MenuItems>
            </SplitMenuButton>
            <CommandButton ToolId="CutTool" />
            <CommandButton ToolId="CopyTool" />
          </GroupItems>
        </Group>
      </Groups>
    </Tab>
    <Tab TabId="ViewTab" Label="View">
      <Groups>
        <Group GroupId="SettingsGroup" Label="Settings">
          <GroupItems>
            <DropMenuButton Label="Measurement units">
              <MenuItems>
                <CommandButton ToolId="InchesTool" />
                <CommandButton ToolId="CentimetersTool" />
                <CommandButton ToolId="PointsTool" />
              </MenuItems>
            </DropMenuButton>
          </GroupItems>
        </Group>
      </Groups>
    </Tab>
  </Tabs>
</Ribbon>

I think this will do as a first draft of the ribbonText XML structure. Of course, an XML structure needs a good document type definition to verify that what is coming in is valid data; and since the XML structure is still evolving, we should define some specification version into the structure. So let's call the current structure SpecificationVersion 0.1 - and here's the DTD:


<!ELEMENT Ribbon 
          (Tools,Tabs)>
<!ELEMENT Tools (Tool)+>
<!ELEMENT Tool EMPTY>
<!ELEMENT Tabs (Tab)+>
<!ELEMENT Tab (Groups)>
<!ELEMENT Groups (Group)+>
<!ELEMENT Group (GroupItems)>
<!ELEMENT GroupItems 
          (CommandButton|SplitMenuButton|DropMenuButton)*>
<!ELEMENT CommandButton EMPTY>
<!ELEMENT ToggleButton EMPTY>
<!ELEMENT SplitMenuButton (MenuItems)>
<!ELEMENT DropMenuButton (MenuItems)>
<!ELEMENT MenuItems
          (CommandButton|SplitMenuButton|DropMenuButton)*>
<!ATTLIST Ribbon 
          SpecificationVersion CDATA #FIXED "0.1">
<!ATTLIST Tool 
          ToolId ID #REQUIRED
          Label CDATA #REQUIRED
          Message CDATA #IMPLIED
          SmallIcon CDATA #IMPLIED
          LargeIcon CDATA #IMPLIED>
<!ATTLIST Tab 
          TabId ID #REQUIRED
          Label CDATA #REQUIRED>
<!ATTLIST Group 
          GroupId ID #REQUIRED
          Label CDATA #REQUIRED>
<!ATTLIST CommandButton
          ToolId IDREF #REQUIRED>
<!ATTLIST SplitMenuButton
          ToolId IDREF #REQUIRED>
<!ATTLIST DropMenuButton
          Label CDATA #REQUIRED>

Since we added a required attribute to the Ribbon root tag, our example XML needs to be slightly amended to:


<?xml version="1.0"?>
<Ribbon SpecificationVersion="0.1">
  <Tools>
    <Tool ToolId="CutTool" Label="Cut" Message="CutText"/>
    <Tool ToolId="CopyTool" Label="Copy" Message="CopyText"/>
    <Tool ToolId="PasteTool" Label="Paste" Message="PasteText"/>
    <Tool ToolId="PasteSpecialTool" Label="Paste special" Message="PasteSpecial"/>
    <Tool ToolId="InchesTool" Label="Inches" Message="SwitchToInches"/>
    <Tool ToolId="CentimetersTool" Label="Centimeters" Message="SwitchToCentimeters"/>
    <Tool ToolId="PointsTool" Label="Points" Message="SwitchToPoints"/>
  </Tools>
  <Tabs>
    <Tab TabId="HomeTab" Label="Home">
      <Groups>
        <Group GroupId="ClipboardGroup" Label="Clipboard">
          <GroupItems>
            <SplitMenuButton ToolId="PasteTool">
              <MenuItems>
                <CommandButton ToolId="PasteTool" />
                <CommandButton ToolId="PasteSpecialTool" />
              </MenuItems>
            </SplitMenuButton>
            <CommandButton ToolId="CutTool" />
            <CommandButton ToolId="CopyTool" />
          </GroupItems>
        </Group>
      </Groups>
    </Tab>
    <Tab TabId="ViewTab" Label="View">
      <Groups>
        <Group GroupId="SettingsGroup" Label="Settings">
          <GroupItems>
            <DropMenuButton Label="Measurement units">
              <MenuItems>
                <CommandButton ToolId="InchesTool" />
                <CommandButton ToolId="CentimetersTool" />
                <CommandButton ToolId="PointsTool" />
              </MenuItems>
            </DropMenuButton>
          </GroupItems>
        </Group>
      </Groups>
    </Tab>
  </Tabs>
</Ribbon>

Next time, we'll work on actually turning such definitions into actual controls in our LiveCode custom control group, so stay tuned!

Experimenting with ribbons in LiveCode (part 1)

2011-07-10T09:42:00.000-07:00

In the previous post, we kicked off a series on the construction of a ribbon using pure LiveCode. For now, we'll concentrate on the Windows 7 Wordpad look-and-feel, but future posts will refine it for cross-platform consistency. Let's get started by creating a new stack "qrtRibbonExperiment" in LiveCode, with two substacks "qrtRexBehaviors" and "qrtRexTemplate" - the mainstack will be a launchpad whereas the substacks will each provide support for the experiment.

The stack qrtRexBehaviors will contain all the behavior scripts as a series of buttons. The stack qrtRexTemplate will be used to as a template to 'clone' isntance stacks from. This way, you have a skeleton of a document editor to learn from as well.

Peeking ahead at the actual ribbon custom control itself, we note that we'll need 5 areas, which we'll implement as subgroups, each with their own behavior script:
- the application menu in the topleft
- the tab items in the topright (minimize and/or help/customize)
- the ribbon tabs between these two blocks at the top
- the ribbon groups in the center
- the quick access toolbar at the bottom

First things first - the main stack:

It contains three simple buttons and some information about this experiment. Nothing spectacular there, so we'll move along to the behaviors stack:

As you can see, it contains seven buttons right now, aptly named after the different items they provide the behavior for. The number of buttons will expand as we add moire features, but this will do for now. Open each of the button scripts for editing and move on to the template stack.

We'll start by creating the menubar for the stack - even though it's only for Mac, it pays off to put it in straight away. Just go to the 'Tools' menu, and select the option 'Menu Builder' ; then click on the 'New...' button to create a menubar called 'qrtRexMenubar' ; not feeling particularly adventurous, we'll use the prefab set for now.
To make the next step easier, uncheck the 'Set as stack Menu bar' box. Now close the menu builder, and you'll see the menubar as part of your stack. When you set the menubar property of the stack, the stack content moves upward, and that's why I want to help you visualize where the controls end up. The menubar group should have its margins set to 4 and thus have a bottom of 22 - which wiill be our anchor point for the ribbon custom control group.

So now we'll add a rectangle graphic as background for our ribbon - just draw one, and set its rectangle using the property inspector to: -1, 21, 401, 161. Set its name to 'Ribbon_Background', make it opaque and set its fill color to a light gray (I picked 'Silver' from the Mac crayons color set).

Next we'll add the background rectangle graphics for each of the ribbon areas:
- ApplicationMenu_Background -> rect: -1, 21, 70, 46 | color: salmon
- TabHeaderItems_Background -> rect: 350, 21, 401, 46 | color: banana
- RibbonTabs_Background -> rect: 70, 21, 350, 46 | color: honeydew
- RibbonGroups_Background -> rect: -1, 46, 401, 137 | color: lavender
- QuickAccessToolbar_Background -> rect: -1, 137, 401, 163 | color: melon

In case you're wondering about the colors: of course they don't match the ribbon color scheme - but they'll help visualize errors in our resizing scripts. But before we start scripting, let's create the necessary custom control groups out of these background graphics.
Once you've grouped the graphic, set the containing group's lockLocation property to true and change its rectangle to clip to the edges of the window
- ApplicationMenu_Background -> group: ApplicationMenu | rect: 0, 21, 70, 46
- TabHeaderItems_Background -> group: TabHeaderItems | rect: 350, 21, 400, 46
- RibbonTabs_Background -> group: RibbonTabs | rect: 70, 21, 350, 46
- RibbonGroups_Background -> group: RibbonTabs | rect: 0, 46, 400, 137
- QuickAccessToolbar_Background -> group: QuickAccessToolbar | rect: 0, 137, 400, 163

Then take those five groups, and the rectangle graphic 'Ribbon_Background', and group everything once more; name that outer group 'Ribbon' and set its margins to 0 as well, before settings its lockLocation to true and its rectangle to 0, 21, 400, 163.
We end up with something like this:

Now we can start setting the behaviors and do some scripting at last. Open the message box, and execute the following seven lines one by one:

set the behavior of this stack to the long id of button "qrtRexStackBehavior" of stack "qrtRexBehaviors"
set the behavior of group "Ribbon" to the long id of button "qrtRexRibbonBehavior" of stack "qrtRexBehaviors"
set the behavior of group "ApplicationMenu" to the long id of button "qrtRexApplicationMenuBehavior" of stack "qrtRexBehaviors"
set the behavior of group "TabHeaderItems" to the long id of button "qrtRexTabHeaderItemsBehavior" of stack "qrtRexBehaviors"
set the behavior of group "RibbonTabs" to the long id of button "qrtRexRibbonTabsBehavior" of stack "qrtRexBehaviors"
set the behavior of group "RibbonGroups" to the long id of button "qrtRexRibbonGroupsBehavior" of stack "qrtRexBehaviors"
set the behavior of group "QuickAccessToolbar" to the long name of button "qrtRexQuickAccessToolbarBehavior" of stack "qrtRexBehaviors"

On to the script of the 'qrtRexStackBehavior' button:

##
on resizeStack pNewWidth, pNewHeight
   local tRectangle
   lock screen
   --> resize the ribbon group
   put the rectangle of group "Ribbon" into tRectangle
   put pNewWidth into item 3 of tRectangle
   set the rectangle of group "Ribbon" to tRectangle
   --> pass the message
   unlock screen
   pass resizeStack
end resizeStack
##

Next comes the script of the 'qrtRexRibbonBehavior' button:

##
on resizeControl
   local tRectangle
   lock screen
   --> resize the background graphic
   put the rectangle of graphic "Ribbon_Background" of me into tRectangle
   put (the width of me) + 1 into item 3 of tRectangle
   set the rectangle of graphic "Ribbon_Background" of me to tRectangle
   --> move the tab header items group
   set the right of group "TabHeaderItems" of me to the right of me
   --> resize the ribbon tabs group
   put the rectangle of group "RibbonTabs" of me into tRectangle
   put the left of group "TabHeaderItems" of me into item 3 of tRectangle
   set the rectangle of group "RibbonTabs" of me to tRectangle
   --> resize the ribbon groups group
   put the rectangle of group "RibbonGroups" of me into tRectangle
   put the width of me into item 3 of tRectangle
   set the rectangle of group "RibbonGroups" of me to tRectangle
   --> resize the quick access toolbar group
   put the rectangle of group "QuickAccessToolbar" of me into tRectangle
   put the width of me into item 3 of tRectangle
   set the rectangle of group "QuickAccessToolbar" of me to tRectangle
   --> pass the message
   unlock screen
   pass resizeControl
end resizeControl
##

Next comes the script of the 'qrtRexApplicationMenuBehavior' button:

##
--> TODO
##

Next comes the script of the 'qrtRexTabHeaderItemsBehavior' button:

##
--> TODO
##

Next comes the script of the 'qrtRexRibbonTabsBehavior' button:

##
on resizeControl
   local tRectangle
   --> resize the background graphic
   put the rectangle of graphic "RibbonTabs_Background" of me into tRectangle
   put (the width of me) + 1 into item 3 of tRectangle
   set the rectangle of graphic "RibbonTabs_Background" of me to tRectangle
   --> TODO: whatever needs to happen to the group content
   --> do not pass the message
end resizeControl
##

Next comes the script of the 'qrtRexRibbonTabsBehavior' button:

##
on resizeControl
   local tRectangle
   --> resize the background graphic
   put the rectangle of graphic "RibbonTabs_Background" of me into tRectangle
   put the right of me into item 3 of tRectangle
   set the rectangle of graphic "RibbonTabs_Background" of me to tRectangle
   --> TODO: whatever needs to happen to the group content
   --> do not pass the message
end resizeControl
##

Next comes the script of the 'qrtRexRibbonGroupsBehavior' button:

##
on resizeControl
   local tRectangle
   --> resize the background graphic
   put the rectangle of graphic "RibbonGroups_Background" of me into tRectangle
   put (the width of me) + 1 into item 3 of tRectangle
   set the rectangle of graphic "RibbonGroups_Background" of me to tRectangle
   --> TODO: whatever needs to happen to the group content
   --> do not pass the message
end resizeControl
##

Finally comes the script of the 'qrtRexQuickAccessToolbar' button

##
on resizeControl
   local tRectangle
   --> resize the background graphic
   put the rectangle of graphic "QuickAccessToolbar_Background" of me into tRectangle
   put (the width of me) + 1 into item 3 of tRectangle
   set the rectangle of graphic "QuickAccessToolbar_Background" of me to tRectangle
   --> TODO: whatever needs to happen to the group content
   --> do not pass the message
end resizeControl
##

Don't worry, there will be more to those scripts soon - bot for now this gives us a set of groups that resize correctly as the stack is resized. You have to start somewhere :-)

In the next installment, we'll build on this foundation by introducing the 'ribbonText' property - an XML structure that describes the content of the ribbon. In the meantime, you can download the first draft of our ribbon experiment here.

Experimenting with ribbons in LiveCode (prelude)

2011-07-10T09:06:00.000-07:00

It's a rainy summer afternoon here in Belgium - what better time to pick up on an old experiment, and share the thought process with you, my fellow LiveCode developers? As you may have guessed from this post's subject, we'll be building a cross-platform Ribbon control using only LiveCode controls and behaviors.
Ribbons were introduced by Microsoft in Office 2007, and replace the traditional menubar and toolbar combination with a single tabbed toolbar. The primary goal: provide a better structure for the myriad of available options, allowing the user to discover these options without becoming overwhelmed.

It's something Microsoft developers have been acutely aware of for a long time, but their past forays into this type of user experience had been a mixed success. Take adaptive menus: I'm sure I wasn't the only one to loathe the automatic hiding of unused options that first appeared around 2000.
Sure, there was a chevron widget to bring back the hidden options, but the whole approach was confusing as the user interface became unpredictable. Have you ever had to support an application where the user could completely customize the look-and-feel, including menus and toolbars? Then you know the sort of nightmare this can induce.

Anyway, be sure to check out The Story of the Ribbon by Jensen Harris, and his related series of blog entries on this topic: Why the UI?

Now let's take a look at some screenshots of the ribbon across different Microsoft applications. Here's the original Word 2007 edition:

Followed by the latest Word 2010 edition:

And here's WordPad as it first shipped with Windows 7:

Finally, a screenshot of Word 2011 for Mac:

But before we work on implementing it, what are the different parts of the ribbon?

Hmm, looking at all these screenshots, it's clear some compromises are inevitable to build our ribbon in pure LiveCode:

1. Application menu and quick access toolbar
- in Office 2007, the application menu (the Jewel or Orb as it's sometimes referred to) fuses with the quick access toolbar into the window titlebar.
- we could replace the standard window decorations with our own implementations, but this brings its own challenges (such as smooth window resizing)
- in later releases, Microsoft decided the application menu could be toned down a bit, and moved it into a button next to the ribbon tabs, so let's just skip this problem altogether and go for the Windows 7 WordPad approach
- that leaves us with the quick access toolbar in the window titlebar, but as this can also be displayed beneath the ribbon, we'll sidestep the issue and simply move the quick access toolbar to the bottom of the ribbon, shall we?

2. Application menu panel
- before Office 2010, the application menu panel wasn't constrained to the window but in its own layer
- this makes it a bit tricky, but we'll get to it in a future post

3. Windows vs. Mac
- while the Windows version dispensed with the menubar entirely, the Mac version still has a complete menubar, but no application menu button
- we just decided to move the quick access toolbar out of the window titlebar and to the bottom of the ribbon, but on Mac the user has no option to move this toolbar and it's always between the window titlebar and the ribbon tabs
- the ribbon group titles have different locations as well: at the bottom of the ribbon group on Windows, at the top on Mac

4. Out of scope
For various reasons, the following ribbon features won't be in scope for this experiment
- contextual tabs
- galleries
- enhanced tooltips

So we'll compromise, but should still have a pretty good ribbon implementation at the end of the experiment - not just a one-off ribbon implementation, but a generic one which you can modify from script. Here's what we're aiming for:

It won't be pixel-prefect, but we can get pretty close. In our first installment, we'll take care of the groundworks. Hang in there - I'll post it shortly.

In the meantime, you should definitely read up on these MSDN articles:
- Ribbon design process
- UX Guidelines - Ribbons

Quartam PDF Library 1.1.2 Available

2011-06-13T07:27:00.000-07:00

This maintenance update to Quartam PDF Library fixes a bug with clipping in combination with automatic page breaks.

The cross-platform .zip archive can be downloaded at: http://downloads.quartam.com/qrtpdflib_112_xplatform.zip
A web page with LiveCode Server / On-Rev demos is available at: http://quartam.on-rev.com/qrtpdfdemos.irev
New examples were added to demonstrate using form data to fill PDF documents and email them.

Quartam PDF Library for LiveCode - version 1.1 introduced support for transformations, transparency and blendmodes, gradients, clipping, text box fitting, inserting pages, compression, experimental support for including EPS files, as well as support for LiveCode Server and On-Rev. It is released as open source under a dual license (GNU Affero General Public License / Commercial License).

Leveraging Java from LiveCode - experiments with multi-threading

2011-05-30T12:53:00.000-07:00

For some time now, I've been promoting the idea of extending LiveCode using Java - both are wonderful cross-platform technologies, each with their own strengths and weaknesses. One area where Java has really made an impact is its built-in approach to multi-threading, by offering a way to split work into chunks that can be executed separately and simultaneously. In a world where chip makers turn to multiple cores to speed up processing, this is a very important technology to incorporate into our software designs.

LiveCode is single-threaded - well, mostly single-threaded: script execution happens on a single thread, but some parts, like socket communication, can be used with event callbacks. This means that when new data arrives, an event message is sent to a control and handled on the script execution thread; but the actual reading and writing can happen on other threads. This is a solid middle ground, as coders don't have to worry about data races and the other un-fun things that come with full-blown multi-threaded programming.

Now my earlier postrs on extending LiveCode with Java were based on a strategy of handing off some work to a Java process (via shell calls or process communication via pipes) and waiting for the result to come back. This is all nice and dandy if the work is done quickly, but what if the processing may take a long time to complete? One of the main reasons to employ multi-threading, after all, is to make sure we can update the user interface while some heavy processing continues in the background.

One approach could be to use the 'in time' variant of the 'read from process' command, and poll the other side for content, but I wanted to show a different approach, by wrapping our Java code in an ExecutorService. The basic idea: we can either 'call' a command immedialtely, or 'submit' it as a task to process in the background. Submitting a command returns a pending-result-id, which we can use to 'cancel' (if it hasn't started or finished yet), check on its 'status' (done, cancelled, pending) or even 'get' its result (waiting for the command to complete).

I know that's a lot of things in one paragraph, so let's put it in Java code:


import java.io.BufferedReader;
import java.io.IOException;
import java.io.InputStreamReader;
import java.util.HashMap;
import java.util.Map;
import java.util.concurrent.Callable;
import java.util.concurrent.ExecutorService;
import java.util.concurrent.Executors;
import java.util.concurrent.Future;
import java.util.concurrent.RejectedExecutionException;
import java.util.concurrent.atomic.AtomicInteger;


public class LiveCodeJavaExecutor {

 private final static String EXIT_COMMAND = "exit";
 private final static String CALL_COMMAND = "call";
 private final static String SUBMIT_COMMAND = "submit";
 private final static String CANCEL_COMMAND = "cancel";
 private final static String STATUS_COMMAND = "status";
 private final static String GET_COMMAND = "get";

 private final static ExecutorService EXECUTOR_SERVICE;
 private final static Map<Integer,Future<String>> PENDING_RESULTS;
 private final static AtomicInteger NEXT_PENDING_ID;
 
 static {
  EXECUTOR_SERVICE = Executors.newCachedThreadPool();
  NEXT_PENDING_ID = new AtomicInteger();
  PENDING_RESULTS = new HashMap<Integer,Future<String>>();
 }
 
 /**
  * @param args
  */
 public static void main(String[] args) {
  // Make sure to run in head-less mode
  System.setProperty("java.awt.headless", "true");

  String commandLine = "";  // the last received command line
  System.out.println("LiveCodeJavaExecutor started. Type the command you wish to execute (type 'exit' to stop):");
  final InputStreamReader isr = new InputStreamReader(System.in);
  final BufferedReader bir = new BufferedReader(isr);

  InfiniteLoop:
  while(!EXIT_COMMAND.equalsIgnoreCase(commandLine)) {
   try {
    commandLine = bir.readLine();
   } catch (IOException e) {
    continue InfiniteLoop;
   }
   final String[] commandParts = commandLine.split("\t");
   final String commandName = commandParts[0];
   if (EXIT_COMMAND.equalsIgnoreCase(commandName)) {
    System.out.println("LiveCodeJavaExecutor is shutting down");
    EXECUTOR_SERVICE.shutdown();
    System.out.println("LiveCodeJavaExecutor is exiting");
   } else if (CALL_COMMAND.equalsIgnoreCase(commandName)) {
    String result = "";
    final CallableCommand callableCommand = new CallableCommand(commandParts);
    try {
     result = callableCommand.call();
    } catch (Exception e) {
     result = e.getMessage().trim();
    }
    System.out.println(result);
   } else if (SUBMIT_COMMAND.equalsIgnoreCase(commandName)){
    String result = "";
    try {
     final CallableCommand callableCommand = new CallableCommand(commandParts);
     final Integer pendingResultId = Integer.valueOf(NEXT_PENDING_ID.incrementAndGet());
     final Future pendingResult = EXECUTOR_SERVICE.submit(callableCommand);
     PENDING_RESULTS.put(pendingResultId, pendingResult);
     result = pendingResultId.toString();
    } catch (RejectedExecutionException e) {
     result = "error - could not submit command";
    }
    System.out.println(result);
   } else if (CANCEL_COMMAND.equalsIgnoreCase(commandName)) {
    String result = "";
    try {
     final Integer pendingResultId = Integer.valueOf(commandParts[1]);
     final Future pendingResult = PENDING_RESULTS.get(pendingResultId);
     if (pendingResult != null) {
      result = String.valueOf(pendingResult.cancel(true));
     } else {
      result = "unknown pending result id: " + pendingResultId.toString();
     }
    } catch (ArrayIndexOutOfBoundsException e) {
     result = "invalid parameters - expected: cancel<tab><pending-result-id>";
    } catch (Exception e) {
     result = e.getMessage().trim();
    }
    System.out.println(result);
   } else if (STATUS_COMMAND.equalsIgnoreCase(commandName)) {
    String result = "";
    try {
     final Integer pendingResultId = Integer.valueOf(commandParts[1]);
     final Future pendingResult = PENDING_RESULTS.get(pendingResultId);
     if (pendingResult != null) {
      if (pendingResult.isCancelled()) {
       result = "cancelled";
      } else if (pendingResult.isDone()) {
       result = "done";
      } else {
       result = "pending";
      }
     } else {
      result = "unknown pending result id: " + pendingResultId.toString();
     }
    } catch (ArrayIndexOutOfBoundsException e) {
     result = "invalid parameters - expected: status<tab><pending-result-id>";
    } catch (Exception e) {
     result = e.getMessage().trim();
    }
    System.out.println(result);
   } else if (GET_COMMAND.equalsIgnoreCase(commandName)) {
    String result = "";
    try {
     final Integer pendingResultId = Integer.valueOf(commandParts[1]);
     final Future pendingResult = PENDING_RESULTS.get(pendingResultId);
     if (pendingResult != null) {
      result = pendingResult.get();
      PENDING_RESULTS.remove(pendingResultId);
     } else {
      result = "unknown pending result id: " + pendingResultId.toString();
     }
    } catch (ArrayIndexOutOfBoundsException e) {
     result = "invalid parameters - expected: get<tab><pending-result-id>";
    } catch (Exception e) {
     result = e.getMessage().trim();
    }
    System.out.println(result);
   } else {
    System.out.println("unrecognized command: " + commandLine);
   }
   System.out.println('.');
  }
 }

 private static class CallableCommand implements Callable<String> {
  private final String[] commandParts;
  public CallableCommand(final String[] commandParts) {
   super();
   this.commandParts = commandParts;
  }
  public String call() throws Exception {
   String result = null;
   result = dispatchCommand(commandParts);
   return result;
  }
 }

 public static String dispatchCommand(String[] commandParts) throws Exception {
  String commandName = commandParts[1];
  Thread.sleep(10000);
  return commandName;
 }

}

Admittedly, the actual command execution part is a bit silly to say the least: sleeping for ten seconds and then just returning the command name is not exactly business logic. But you can take a look at some of my previous examples, to put in code for concatenating PDF files, validating XML data using XSD schemas, image processing or anything else that could take quite a bit of time to finish processing.

Turning our attention to the LiveCode side, we would have a stack script looking something like this:


local sProcess

on JExecutor_StartHelper
   if sProcess is empty then
      local tDefaultFolder, tStackFolder
      put ImageIO_StackFolder() into tStackFolder
      put the defaultFolder into tDefaultFolder
      set the defaultFolder to tStackFolder
      put "java LiveCodeJavaExecutor" into sProcess
      open process sProcess for update
      set the defaultFolder to tDefaultFolder
      --> make sure we're speaking with the right helper
      read from process sProcess for 1 line
      if it begins with "LiveCodeJavaExecutor started." then
         --> good to go
      else
         close process sProcess
         put empty into sProcess
      end if
   end if
end JExecutor_StartHelper

on JExecutor_StopHelper
   write ("exit") & return to process sProcess
   close process sProcess
   put empty into sProcess
end JExecutor_StopHelper

command JExecutor_CallCommand pCommand
   write("call" & tab & pCommand) & return to process sProcess
   read from process sprocess for 1 line
   return line 1 of it
end JExecutor_CallCommand

command JExecutor_SubmitCommand pCommand
   write("submit" & tab & pCommand) & return to process sProcess
   read from process sprocess for 1 line
   return line 1 of it
end JExecutor_SubmitCommand

command JExecutor_CancelRequest pRequestId
   write("cancel" & tab & pRequestId) & return to process sProcess
   read from process sprocess for 1 line
   return line 1 of it
end JExecutor_CancelRequest

function JExecutor_StatusOfRequest pRequestId
   write("status" & tab & pRequestId) & return to process sProcess
   read from process sprocess for 1 line
   return line 1 of it
end JExecutor_StatusOfRequest

function JExecutor_GetResultOfRequest pRequestId
   write("get" & tab & pRequestId) & return to process sProcess
   read from process sprocess for 1 line
   return line 1 of it
end JExecutor_GetResultOfRequest

Now we have the commands and functions we need to start the separate Java process, 'call' commands, 'submit' commands, 'cancel' pending requests, checking the 'status' of pending requests, and fetching the result with a 'get'. Enough to control the lifecycle of such submitted commands a.k.a. pending requests.

If we're sure the command is just a small bit of work, we use the 'call' command and wait for the result to appear; but if it may take a long time to complete, we can 'submit' a command and use the returned 'pending request id' to track its progress - and while the Java side is churning away, we can update our LiveCode user interface with a lovely indeterminate progress display, polling every second or so until the 'status' returns "done" and then use 'get' to fetch the completed command output.

So perhaps the title was a little misleading, as I've only given you a skeleton. Hopefully it will inspire you to combine this technique with code that I posted previously, and actually use it in your own projects. Happy coding!

Quartam PDF Library 1.1.1 Available

2011-05-09T14:55:00.000-07:00

This maintenance update to Quartam PDF Library fixes two bugs specific to LiveCode Server environments, and extends the WriteTextTable command to allow more control over border drawing.

The cross-platform .zip archive can be downloaded at: http://downloads.quartam.com/qrtpdflib_111_xplatform.zip
A web page with LiveCode Server / On-Rev demos is available at: http://quartam.on-rev.com/qrtpdfdemos.irev

Quartam PDF Library for LiveCode - version 1.1 introduced support for transformations, transparency and blendmodes, gradients, clipping, text box fitting, inserting pages, compression, experimental support for including EPS files, as well as support for LiveCode Server and On-Rev. It is released as open source under a dual license (GNU Affero General Public License / Commercial License).

Presenting at RunRevLive.11 - the code

2011-05-08T08:12:00.000-07:00

As I mentioned earlier, I presented two topics at the RunRevLive.11 developer conference. After returning home, I got clobbered with a backlog of work at the day-job; but today, I finally got around to uploading the example code.

- Advanced databases (or: migrating from a single-user desktop application to a multi-user networked database application)
- Extending LiveCode with Java (or: leveraging Java libraries from within LiveCode scripts)

Enjoy - and don't forget that if you couldn't attend it in person and bought a SimulCast pass, you can see the whole presentation through the RunRevLive SimulCast - or wait for the DVD to come out :-)

Quartam PDF Library On-Rev Demos

2011-04-22T01:46:00.000-07:00

As announced yesterday, Quartam PDF Library for LiveCode is now a free / open source software project, available under the terms of the GNU Affero General Public License (AGPL).

One of the advantages of version 1.1.0 is that it comes with support for LiveCode Server and On-Rev. I just put up a page with demos so that you can see how straightforward it is to port your desktop PDF generation scripts to .irev scripts.

As it turns out, there are two bugs to address: loading images throws errors, and callback messages have problems as well. Unfortunately, I'm working frantically to finish my presentations for RunRevLive.11 - but now that it's an open source project, anyone can go and take a stab at fixing bugs. So I'm looking forward to your helping hand in finding solutions so we can put out an update soon.

Onwards!

Quartam PDF Library goes open source

2011-04-21T11:26:00.000-07:00

Today, Quartam Software is proud to announce the release of Quartam PDF Library for LiveCode version 1.1, as open source under a dual license. Quartam PDF Library allows LiveCode developers to go beyond 'print to pdf file' as it offers pin-point control, extensive graphics support and much more.

Where does Quartam PDF Library come from?

Back in December 2005, I started Quartam PDF Library as a research project for adding PDF export to Quartam Reports. It was spun off as a separate commercial product and used in a wide variety of LiveCode-based projects, such as BlueMango's ScreenSteps.

Although I had kept working on new features, more pressing matters (like my day-job) kept me from pushing ahead and wrapping up a new release. The advent of 'print to pdf' features in LiveCode 4.5 triggered a soul search and eventually led to the decision to release the new version as open source.

The end result: nearly 7300 lines of production quality code, ready for you to use in your LiveCode projects.

So what is new in version 1.1?

The code got a good cleanup, complies with the rules of variable checking, and replaces most string literals with constants to prevent bugs.

Plus, the following features were added:
- Transformations (scale, translate, rotate, skew, mirror)
- Transparency and blendmodes
- Gradients
- Clipping
- Text box fitting
- Inserting pages (ideal for building a table of contents with bookmarks)
- Compression
- Experimental support for including EPS files (Emulated PostScript)

And for the first time, we offer support for generating PDF documents in LiveCode Server scripts, including On-Rev!

Quartam PDF Library now requires Revolution 3.0 or later, with LiveCode 4.6 highly recommended.

How do you mean: open source under a dual license?

Although Quartam PDF Library is a free/open source software (F/OSS) project, giving you a lot of freedom and flexibility as to how you use it in your own projects, this doesn't mean you're free to do anything you want with it: you have to respect the GNU Affero General Public License (AGPL).

You can be released from the requirements of the AGPL license by purchasing a commercial license from Quartam Software.

Buying such a license is mandatory as soon as you develop commercial activities involving Quartam PDF Library without disclosing the source code of your own applications. These activities include: offering paid services to customers as an ASP, serving PDF documents generated dynamically in a web application, shipping Quartam PDF Library with a closed source product.

Such a commercial license releases you from the requirements of the copyleft AGPL license, which include: distribution of all source code, including your own product; licensing of your own product under the AGPL license; prominent mention of the Quartam copyright and the AGPL license; and disclosure of modifications to the library.

In addition, the commercial license releases you from the requirement not to change the PDF Producer line in the generated PDF document properties.

What about my previous commercial license for Quartam PDF Library version 1.0?

Of course you can keep using the closed source version 1.0 in your projects. And if your project is open source, you can use version 1.1 without an additional charge.

However, if you want to use version 1.1 in a commercial activity, you have to purchase an upgrade for USD 49 from the Quartam Software Online Store.

And if you never bought a copy of Quartam PDF Library, you can purchase the commercial license for USD 149 from the Quartam Software Online Store or the LiveCode Marketplace.

How can I contribute to the Quartam PDF Library project?

I'm glad you asked - the plan is to build a community around Quartam PDF Library in order to streamline the development of newer versions. If you can help with squashing bugs, researching new features, improving documentation, or any other way, you're more than welcome to join us.

All you need to do is download, sign and email back the Quartam Open Source Contributor Agreement so that your contributions can be incorporated into the project. Quartam Software has the role of project custodian, taking care of versioning and distribution.

One such contribution was made by John Craig (Splash21) to add compression support to the library, which is included in Quartam PDF Library version 1.1 - another contribution was made by Trevor DeVore (BlueMango) who offered code for writing LiveCode htmlText to a PDF document, which I have yet to integrate but looks really promising.

And I have some experimental code that I'd love to share and put into the project after review - so any reports of this library's death were greatly exaggerated.

So roll up your sleeves, download the new version and get stuck in!

Presenting at RunRevLive.11

2011-04-17T09:43:00.000-07:00

Next week I'll be at the RunRevLive.11 conference in sunny San Jose, California, giving two presentations: Advanced Databases and Extending LiveCode with Java. Here is a brief description for both sessions.

--

Advanced databases:
You've just finished a desktop application that stores its data in a local SQLite database. All works well, and now you're asked to make a multi-user version, so that other users can access and update the data as well. Unfortunately, you can't just load the data into a MySQL dataabse and be done with it: your data structures and business logic have to be ready as well!
In this presentation, I'll take a desktop SQLite application and turn it into a front-end for a networked MySQL database. Along the way, you'll get crucial tips to avoid the pitfalls of such a transformation.

Extending LiveCode with Java:
We all love LiveCode for its cross-platform abilities, combined with an elegant and productive scripting language. But the 200-pound gorilla in this space is indubitably Java. In this presentation we will see how we can leverage Java libraries from within LiveCode through process communication.
This allows us to extend our LiveCode desktop applications with Zeroconf discovery, XML schemas, PDF file enhancements and image processing.

--

Last but not least, you're invited to drop by the LiveCode Marketplace vendor area and ask me any questions you have regarding the Quartam developer tools for LiveCode. You might even get a sneak preview of Quartam Reports 1.2 :-)

Locale aware formatting in LiveCode using Java

2011-03-06T01:23:00.000-08:00

Recently on the Use-LiveCode mailing list, Peter Haworth asked how he could get a hold of the date/times/number/currency format preferences to ensure that data display corresponded to the user locale. For date and time, you can use 'the system date' and 'the system time' for quick formatting, and 'the dateFormat' to figure out some of the details. But formatting numbers is quite a different challenge. And even if you can get the 'system' information, what to do if you're building a text that shouldn't be in English or user formatting?

At the risk of sounding like a broken record: let's use Java - it has powerful formatting capabilities for all the required items, and its concept of Locale is robust. To avoid startup overhead and improve response time, we'll use the same approach as for the Zeroconf example: process communication to start a helper process, interact with it, and finally close it when we're done.

So let's write a helper class in Java that will (a) give us the default Locale, (b) list the available locales, (c) allows us to format a LiveCode number as currency, integer or decimal number, applying a given or the default locale, (d) allows us to format a LiveCode date as short, medium, long or full date, applying a given or the default locale, and (e) allows us to format a LiveCode time as short, medium, long or full time, applying a given or the default locale. Sounds like a lot to do, but it's actually quite straightforward to implement:

import java.io.BufferedReader;
import java.io.IOException;
import java.io.InputStreamReader;
import java.text.DateFormat;
import java.text.NumberFormat;
import java.text.ParseException;
import java.util.ArrayList;
import java.util.Collections;
import java.util.Date;
import java.util.HashMap;
import java.util.List;
import java.util.Locale;
import java.util.Map;

public class LiveCodeLocaleHelper {

  private final static String EXIT_COMMAND = "exit";
  private final static String LIST_COMMAND = "list";
  private final static String DEFAULT_COMMAND = "default";
  private final static String CURRENCY_COMMAND = "currency";
  private final static String INTEGER_COMMAND = "integer";
  private final static String NUMBER_COMMAND = "number";
  private final static String DATE_COMMAND = "date";
  private final static String TIME_COMMAND = "time";

  private static final Map LOCALE_MAP;
  private static final DateFormat LC_DATE_FORMAT;
  private static final DateFormat LC_TIME_FORMAT;
  
  static {
    Locale en_US_locale = null;
    LOCALE_MAP = new HashMap();
    for (Locale locale : Locale.getAvailableLocales()) {
      if ("en".equals(locale.getLanguage()) && "US".equals(locale.getCountry())) {
        en_US_locale = locale;
      }
      LOCALE_MAP.put(locale.toString(), locale);
    }
    LC_DATE_FORMAT = DateFormat.getDateInstance(DateFormat.SHORT, en_US_locale);
    LC_TIME_FORMAT = DateFormat.getTimeInstance(DateFormat.SHORT, en_US_locale);
  }
  
  public static void main(final String[] args) throws IOException {
    String commandLine = "";  // the last received command line
    System.out.println("LiveCodeLocaleHelper started. Type the command you wish to execute (type 'exit' to stop):");
    final InputStreamReader isr = new InputStreamReader(System.in);
    final BufferedReader bir = new BufferedReader(isr);
    
    while(!EXIT_COMMAND.equalsIgnoreCase(commandLine)) {
      commandLine = bir.readLine();
      final String[] commandParts = commandLine.split("\t");
      final String commandName = commandParts[0];
      if (EXIT_COMMAND.equalsIgnoreCase(commandName)) {
        System.out.println("LiveCodeLocaleHelper is exiting");
      } else if (LIST_COMMAND.equalsIgnoreCase(commandName)) {
        handleListCommand(commandParts);
      } else if (DEFAULT_COMMAND.equalsIgnoreCase(commandName)) {
        handleDefaultCommand(commandParts);
      } else if (CURRENCY_COMMAND.equalsIgnoreCase(commandName)) {
        handleCurrencyCommand(commandParts);
      } else if (INTEGER_COMMAND.equalsIgnoreCase(commandName)) {
        handleIntegerCommand(commandParts);
      } else if (NUMBER_COMMAND.equalsIgnoreCase(commandName)) {
        handleNumberCommand(commandParts);
      } else if (DATE_COMMAND.equalsIgnoreCase(commandName)) {
        handleDateCommand(commandParts);
      } else if (TIME_COMMAND.equalsIgnoreCase(commandName)) {
        handleTimeCommand(commandParts);
      } else {
        System.out.println("Unrecognized command: " + commandLine);
      }
    }
  }

  private static void handleListCommand(final String[] commandParts) {
    final List localeIdentifiers = new ArrayList(LOCALE_MAP.keySet());
    Collections.sort(localeIdentifiers);
    for (String localeIdentifier : localeIdentifiers) {
      System.out.println(localeIdentifier);
    }
    System.out.println(".");
  }

  private static void handleDefaultCommand(final String[] commandParts) {
    System.out.println(Locale.getDefault().toString());
  }

  private static void handleCurrencyCommand(final String[] commandParts) {
    double number;
    try {
      number = Double.parseDouble(commandParts[1]);
    } catch (NumberFormatException e) {
      System.out.println("Invalid number: " + commandParts[1]);
      return;
    }
    NumberFormat currencyFormat = null;
    if (commandParts.length > 2) {
      final String localeIdentifier = commandParts[2];
      currencyFormat = NumberFormat.getCurrencyInstance(LOCALE_MAP.get(localeIdentifier));
    } else {
      currencyFormat = NumberFormat.getCurrencyInstance();
    }
    System.out.println(currencyFormat.format(number));
  }

  private static void handleIntegerCommand(final String[] commandParts) {
    double number;
    try {
      number = Double.parseDouble(commandParts[1]);
    } catch (NumberFormatException e) {
      System.out.println("Invalid number: " + commandParts[1]);
      return;
    }
    NumberFormat integerFormat = null;
    if (commandParts.length > 2) {
      final String localeIdentifier = commandParts[2];
      integerFormat = NumberFormat.getIntegerInstance(LOCALE_MAP.get(localeIdentifier));
    } else {
      integerFormat = NumberFormat.getIntegerInstance();
    }
    System.out.println(integerFormat.format(number));
  }

  private static void handleNumberCommand(final String[] commandParts) {
    double number;
    try {
      number = Double.parseDouble(commandParts[1]);
    } catch (NumberFormatException e) {
      System.out.println("Invalid number: " + commandParts[1]);
      return;
    }
    NumberFormat numberFormat = null;
    if (commandParts.length > 2) {
      final String localeIdentifier = commandParts[2];
      numberFormat = NumberFormat.getNumberInstance(LOCALE_MAP.get(localeIdentifier));
    } else {
      numberFormat = NumberFormat.getNumberInstance();
    }
    System.out.println(numberFormat.format(number));
  }

  private static void handleDateCommand(final String[] commandParts) {
    Date date = null;
    try {
      date = LC_DATE_FORMAT.parse(commandParts[1]);
    } catch (ParseException e) {
      System.out.println("Invalid date: " + commandParts[1]);
      return;
    }
    int dateSize = DateFormat.SHORT;
    final String dateFormatString = commandParts[2];
    if ("medium".equalsIgnoreCase(dateFormatString)) {
      dateSize = DateFormat.MEDIUM;
    } else if ("long".equalsIgnoreCase(dateFormatString)) {
      dateSize = DateFormat.LONG;
    } else if ("full".equalsIgnoreCase(dateFormatString)) {
      dateSize = DateFormat.FULL;
    }
    DateFormat dateFormat = null;
    if (commandParts.length > 3) {
      final String localeIdentifier = commandParts[3];
      dateFormat = DateFormat.getDateInstance(dateSize, LOCALE_MAP.get(localeIdentifier));
    } else {
      dateFormat = DateFormat.getDateInstance(dateSize);
    }
    System.out.println(dateFormat.format(date));
  }

  private static void handleTimeCommand(final String[] commandParts) {
    Date date = null;
    try {
      date = LC_TIME_FORMAT.parse(commandParts[1]);
    } catch (ParseException e) {
      System.out.println("Invalid time: " + commandParts[1]);
      return;
    }
    int timeSize = DateFormat.SHORT;
    final String dateFormatString = commandParts[2];
    if ("medium".equalsIgnoreCase(dateFormatString)) {
      timeSize = DateFormat.MEDIUM;
    } else if ("long".equalsIgnoreCase(dateFormatString)) {
      timeSize = DateFormat.LONG;
    } else if ("full".equalsIgnoreCase(dateFormatString)) {
      timeSize = DateFormat.FULL;
    }
    DateFormat dateFormat = null;
    if (commandParts.length > 3) {
      final String localeIdentifier = commandParts[3];
      dateFormat = DateFormat.getTimeInstance(timeSize, LOCALE_MAP.get(localeIdentifier));
    } else {
      dateFormat = DateFormat.getTimeInstance(timeSize);
    }
    System.out.println(dateFormat.format(date));
  }

}

With the Java helper class written, we can turn our attention to the LiveCode side. Let's create a new stack:

As you can see, we have two buttons at the top for starting/stopping the helper process, along with an option menu to list the available locales and a field to show the default locale. Now put the following into the stack script:

local sProcess

on Locale_StartHelper
   if sProcess is empty then
      local tDefaultFolder, tStackFolder
      put Locale_StackFolder() into tStackFolder
      put the defaultFolder into tDefaultFolder
      set the defaultFolder to tStackFolder
      put "java LiveCodeLocaleHelper" into sProcess
      open process sProcess for update
      set the defaultFolder to tDefaultFolder
      --> make sure we're speaking with the right helper
      read from process sProcess for 1 line
      if it begins with "LiveCodeLocaleHelper started." then
         disable button "Start"
         enable button "Stop"
      else
         close process sProcess
         put empty into sProcess
      end if
   end if
end Locale_StartHelper

function Locale_AvailableLocales
   local tLocaleList
   write ("list") & return to process sProcess
   repeat forever
      read from process sProcess for 1 line
      if it begins with "." then exit repeat
      put it after tLocaleList
   end repeat
   delete char -1 of tLocaleList
   return tLocaleList
end Locale_AvailableLocales

function Locale_DefaultLocale
   write ("default") & return to process sProcess
   read from process sProcess for 1 line
   return it
end Locale_DefaultLocale

function Locale_FormatCurrency pAmount, pLocale
   if pLocale is empty then
      write ("currency" & tab & pAmount) & return to process sProcess
   else
      write ("currency" & tab & pAmount & tab & pLocale) & return to process sProcess
   end if
   read from process sProcess for 1 line
   return line 1 of it
end Locale_FormatCurrency

function Locale_FormatInteger pAmount, pLocale
   if pLocale is empty then
      write ("integer" & tab & pAmount) & return to process sProcess
   else
      write ("integer" & tab & pAmount & tab & pLocale) & return to process sProcess
   end if
   read from process sProcess for 1 line
   return line 1 of it
end Locale_FormatInteger

function Locale_FormatNumber pAmount, pLocale
   if pLocale is empty then
      write ("number" & tab & pAmount) & return to process sProcess
   else
      write ("number" & tab & pAmount & tab & pLocale) & return to process sProcess
   end if
   read from process sProcess for 1 line
   return line 1 of it
end Locale_FormatNumber

function Locale_FormatDate pDate, pSize, pLocale
   if pLocale is empty then
      write ("date" & tab & pDate & tab & pSize) & return to process sProcess
   else
      write ("date" & tab & pDate & tab & pSize & tab & pLocale) & return to process sProcess
   end if
   read from process sProcess for 1 line
   return line 1 of it
end Locale_FormatDate

function Locale_FormatTime pTime, pSize, pLocale
   if pLocale is empty then
      write ("time" & tab & pTime & tab & pSize) & return to process sProcess
   else
      write ("time" & tab & pTime & tab & pSize & tab & pLocale) & return to process sProcess
   end if
   read from process sProcess for 1 line
   return line 1 of it
end Locale_FormatTime

on Locale_StopHelper
   write ("exit") & return to process sProcess
   close process sProcess
   enable button "Start"
   disable button "Stop"
   put empty into sProcess
end Locale_StopHelper

function Locale_StackFolder
   local tStackFolder
   put the effective filename of this stack into tStackFolder
   set the itemDelimiter to slash
   delete item -1 of tStackFolder
   return tStackFolder
end Locale_StackFolder

The script for the Start button is easy enough:

on mouseUp
   disable button "Start"
   Locale_StartHelper
   put Locale_AvailableLocales() into button "AvailableLocales"
   put Locale_DefaultLocale() into field "DefaultLocale"
   enable button "Stop"
end mouseUp

And the script of the Stop button is equally trivial:

on mouseUp
   disable button "Stop"
   Locale_StopHelper
   enable button "Start"
end mouseUp

The script for the Default button in the Number formatting section looks like this:

on mouseUp
   local tNumber
   put field "Number" into tNumber
   put "Currency:" & tab & Locale_FormatCurrency(tNumber) & return & \
       "Integer:" & tab & Locale_FormatInteger(tNumber) & return & \
       "Number:" & tab & Locale_FormatNumber(tNumber) \
       into field "FormattedNumbers"
end mouseUp

And the script for the Available button in the Number formatting section looks like this:

on mouseUp
   local tNumber, tLocale
   put field "Number" into tNumber
   put the label of button "AvailableLocales" into tLocale
   put "Currency:" & tab & Locale_FormatCurrency(tNumber, tLocale) & return & \
       "Integer:" & tab & Locale_FormatInteger(tNumber, tLocale) & return & \
       "Number:" & tab & Locale_FormatNumber(tNumber, tLocale) \
       into field "FormattedNumbers"
end mouseUp

Likewise, the script for the Default button in the Date formatting section becomes:

on mouseUp
   local tDate
   put field "Date" into tDate
   put "Short:" & tab & Locale_FormatDate(tDate, "short") & return & \
       "Medium:" & tab & Locale_FormatDate(tDate, "medium") & return & \
       "Long:" & tab & Locale_FormatDate(tDate, "long") & return & \
       "Full:" & tab & Locale_FormatDate(tDate, "full") \
       into field "FormattedDates"
end mouseUp

Hence, the script for the Available button in the Date formatting section becomes:

on mouseUp
   local tDate, tLocale
   put field "Date" into tDate
   put the label of button "AvailableLocales" into tLocale
   put "Short:" & tab & Locale_FormatDate(tDate, "short", tLocale) & return & \
       "Medium:" & tab & Locale_FormatDate(tDate, "medium", tLocale) & return & \
       "Long:" & tab & Locale_FormatDate(tDate, "long", tLocale) & return & \
       "Full:" & tab & Locale_FormatDate(tDate, "full", tLocale) \
       into field "FormattedDates"
end mouseUp

Almost done - here's the script for the Default button in the Time formatting section:

on mouseUp
   local tTime
   put field "Time" into tTime
   put "Short:" & tab & Locale_FormatTime(tTime, "short") & return & \
       "Medium:" & tab & Locale_FormatTime(tTime, "medium") & return & \
       "Long:" & tab & Locale_FormatTime(tTime, "long") & return & \
       "Full:" & tab & Locale_FormatTime(tTime, "full") \
       into field "FormattedTimes"
end mouseUp

Finally, the logical extension for the Available button in the Time formatting section:

on mouseUp
   local tTime, tLocale
   put field "Time" into tTime
   put the label of button "AvailableLocales" into tLocale
   put "Short:" & tab & Locale_FormatTime(tTime, "short", tLocale) & return & \
       "Medium:" & tab & Locale_FormatTime(tTime, "medium", tLocale) & return & \
       "Long:" & tab & Locale_FormatTime(tTime, "long", tLocale) & return & \
       "Full:" & tab & Locale_FormatTime(tTime, "full", tLocale) \
       into field "FormattedTimes"
end mouseUp

Save the stack, and copy the compiled LiveCodeLocaleHelper.class file into the same directory where you saved the stack. Click the Start button, then play around with the rest of the user interface to enter different numbers, dates and times, clicking the buttons to see the formatting output, switching between the different available locales.

Download it here.

Quartam Reports 1.1.6 Available

2011-02-13T11:11:00.000-08:00

This maintenance update to Quartam Reports contains all the enhancements of versions 1.1.1 through 1.1.5, and improves error handling and behavior on MacOSX.

The MacOSX version can be downloaded at: http://downloads.quartam.com/qrtReports_116_MacOSX_Setup.dmg
The Windows version can be downloaded at: http://downloads.quartam.com/qrtReports_116_Windows_Setup.exe
The (expertimental) Linux version can be downloaded at: http://downloads.quartam.com/qrtReports_116_Linux_Archive.zip

Quartam Reports for LiveCode - version 1.1 introduced stretching data fields and relative positioning, added title and summary sections, brought data groups to everyone and extended the Professional edition with barcodes, 2D charts and export to HTML and Excel.
With Quartam Reports, LiveCode and just a little SQL, you can create professional reports - cross-platform and database-independent.

ZeroConf/Bonjour in LiveCode with JmDNS

2011-01-16T10:32:00.000-08:00

In the last few posts, we examined how LiveCode scripts can delegate work to Java classes using the shell function. Even though this generally works quite fast and reliably, the downside of this approach is that a new Java process is started every time.

In this post, we'll use process communication to start a helper process, interact with it, and finally close it when we're done. Our use case: ZeroConf / Bonjour registration and discovery of services. The JmDNS project offers a pure-Java implementation of Multicast DNS and DNS Service Discovery technologies.

LiveCode process communication revolves around opening a process (a.k.a. command-line interface application), writing data, reading data, and finally closing said process. But we'll get to that later; let's start by writing a LiveCodeJmDNSHelper class in Java. First download a copy of the JmDNS library - I picked version 3.0 as I was building this on an older Mac which can't run Java 6.

In the .zip file, you'll find a file 'jmdns.jar' which is all you need for the rest of this example. Copy it into your Eclipse project, add it to the Build path, and use the following code for the LiveCodeJmDNSHelper.java file:

import java.io.BufferedReader;
import java.io.IOException;
import java.io.InputStreamReader;
import java.util.HashMap;
import java.util.Map;

import javax.jmdns.JmDNS;
import javax.jmdns.ServiceInfo;


public class LiveCodeJmDNSHelper {
 
 private final static String EXIT_COMMAND = "exit";
 private final static String LIST_COMMAND = "list";
 private final static String REGISTER_COMMAND = "register";
 private final static String UNREGISTER_COMMAND = "unregister";
 
 private JmDNS jmdns;
 private Map<String, ServiceInfo> regMap; 
 
 public LiveCodeJmDNSHelper() {
  super();
 }
 
 public void start() throws IOException {
  this.jmdns = JmDNS.create();
  this.regMap = new HashMap<String, ServiceInfo>();
  String commandLine = "";  // the last received command line
  System.out.println("LiveCodeJmDNSHelper started. Type the command you wish to execute (type 'exit' to stop):");
  final InputStreamReader isr = new InputStreamReader(System.in);
  final BufferedReader bir = new BufferedReader(isr);
  
  while(!EXIT_COMMAND.equals(commandLine)) {
   commandLine = bir.readLine();
   final String[] commandParts = commandLine.split(" ");
   final String commandName = commandParts[0];
   if (EXIT_COMMAND.equalsIgnoreCase(commandName)) {
    System.out.println("LiveCodeHelper is exiting");
    System.exit(0);
   } else if (LIST_COMMAND.equalsIgnoreCase(commandName)) {
    handleListCommand(commandParts);
   } else if (REGISTER_COMMAND.equalsIgnoreCase(commandName)) {
    handleRegisterCommand(commandParts);
   } else if (UNREGISTER_COMMAND.equalsIgnoreCase(commandName)) {
    handleUnregisterCommand(commandParts);
   } else {
    System.out.println("Unrecognized command: " + commandLine);
   }
  }
 }

 private void handleListCommand(final String[] commandParts) {
  final String svcType = commandParts[1];
  final ServiceInfo[] svcInfos = this.jmdns.list(svcType);
  for (ServiceInfo svcInfo : svcInfos) {
   System.out.println(svcInfo);
  }
  System.out.println(".");
 }

 private void handleRegisterCommand(final String[] commandParts) {
  final String svcAlias = commandParts[1];
  final String svcType = commandParts[2];
  final String svcName = commandParts[3];
  final int svcPort = Integer.parseInt(commandParts[4]);
  final String svcText = commandParts[5];
  ServiceInfo svcInfo = ServiceInfo.create(svcType, svcName, svcPort, svcText);
  try {
   this.jmdns.registerService(svcInfo);
   this.regMap.put(svcAlias, svcInfo);
   System.out.println("Registered service '" + svcAlias + "' as: " + svcInfo);
  } catch (IOException e) {
   System.out.println("Failed to register service '" + svcAlias + "'");
  }
 }

 private void handleUnregisterCommand(final String[] commandParts) {
  final String svcAlias = commandParts[1];
  final ServiceInfo svcInfo = this.regMap.remove(svcAlias);
  if (svcInfo != null) {
   this.jmdns.unregisterService(svcInfo);
   System.out.println("Unregistered service '" + svcAlias + "'");
  } else {
   System.out.println("Failed to unregister service '" + svcAlias + "'");
  }
 }
 
 public static void main(String[] args) throws IOException {
  final LiveCodeJmDNSHelper helper = new LiveCodeJmDNSHelper();
  helper.start();
 }

}

The start() method goes into an infinite loop, waiting for a line of text as its input, parsing the command and executing it. You can 'list' the ServiceInfo data for a given service type, 'register' your own services, and 'unregister' those services again. All nice and dandy, but how do we talk to it from LiveCode? Let's start by creating a new stack.

So we have two buttons at the top, to Start and Stop the helper process. Then we have a button to Register a service of our own, with fields for the Alias, Type, Name, Port and Text. Next there is a button to Unregister our own service, given an Alias. Finally, there is a button to List all the services of a specific Type in a scrolling field below. With the user interface laid out, we can put the following code into the stack script:

local sProcess

on JmDNS_StartHelper
   if sProcess is empty then
      local tClassPath
      if the platform is "Win32" then
         put ".;jmdns.jar" into tClassPath
      else
         put ".:jmdns.jar" into tClassPath
      end if
      local tDefaultFolder, tStackFolder
      put JMDNS_StackFolder() into tStackFolder
      put the defaultFolder into tDefaultFolder
      set the defaultFolder to tStackFolder
      put "java -cp" && tClassPath && "LiveCodeJmDNSHelper" into sProcess
      open process sProcess for update
      set the defaultFolder to tDefaultFolder
      --> make sure we're speaking with the right helper
      read from process sProcess for 1 line
      if it begins with "LiveCodeJmDNSHelper started." then
         --> ready for interaction
      else
         close process sProcess
         put empty into sProcess
      end if
   end if
end JmDNS_StartHelper

function JmDNS_GetList pServiceType
   local tJmDNSList
   write ("list" && pServiceType) & return to process sProcess
   repeat forever
      read from process sProcess for 1 line
      if it begins with "." then exit repeat
      put it after tJmDNSList
   end repeat
   delete char -1 of tJmDNSList
   return tJmDNSList
end JmDNS_GetList

command JmDNS_RegisterService pAlias, pType, pName, pPort, pText
   write ("register" && pAlias && pType && pName && pPort && pText) & return to process sProcess
   read from process sProcess for 1 line
   return it
end JmDNS_RegisterService

command JmDNS_UnregisterService pAlias
   write ("unregister" && pAlias) & return to process sProcess
   read from process sProcess for 1 line
   return it
end JmDNS_UnregisterService

command JmDNS_StopHelper
   write ("exit") & return to process sProcess
   close process sProcess
   put empty into sProcess
end JmDNS_StopHelper

function JmDNS_StackFolder
   local tStackFolder
   put the effective filename of this stack into tStackFolder
   set the itemDelimiter to slash
   delete item -1 of tStackFolder
   return tStackFolder
end JmDNS_StackFolder

The script for the Start button is easy enough:

on mouseUp
   JmDNS_StartHelper
   disable button "Start"
   enable button "Stop"
end mouseUp

And the script of the Stop button is equally trivial:

on mouseUp
   JmDNS_StopHelper
   enable button "Start"
   disable button "Stop"
end mouseUp

The script of the Register button isn't too complicated either:

on mouseUp
   JmDNS_RegisterService field "Alias", field "Type", field "Name", field "Port", field "Text"
   answer the result
end mouseUp

Neither is the script of the Unregister button:

on mouseUp
   ask "Unregister which alias?" with field "Alias"
   if it is empty then exit mouseUp
   JmDNS_UnregisterService it
   answer the result
end mouseUp

Nor the script of the List button:

on mouseUp
   ask "List services of which type?" with field "Type"
   if it is empty then exit mouseUp
   put JMDNS_GetList(it) into field "List"
end mouseUp

Save the stack, and copy jmdns.jar as well as the compiled LiveCodeJmDNSHelper.class into the same directory where you saved the stack. Click the Start button, Register a service of your own, click the List button to make sure it shows up, click the Unregister button to remove it again, and then click the List button to make sure it's gone. If you want, you can launch some of the Java samples that come with JmDNS to see that both Java and LiveCode recognize the same services.

For the purists: no, I didn't do proper error checking or exception handling in this example. Because it is just that: an example. Never promised it was production-ready, did I? ;-)
Download it here.

XML validation using a Schema

2010-12-31T08:09:00.000-08:00

In earlier posts, I examined how we can use the built-in revXML library in LiveCode to validate XML data against a DTD, later refining it with a version check to match evolving requirements. Unfortunately, a Document Type Definition is quite a limited way of XML validation. So this time, we'll improve our defenses again, by incorporating XML Schemas.

Whereas a DTD is limited to defining the basic structure of the XML in terms of elements and attributes, XML Schemas allow you to define validation on the actual content of the elements and attributes. So you can be sure that an element defined as "xs:date" is actually a valid date, or that an attribute defines as "xs:positiveInteger" is actually a positive integer, etc. A full explanation of XML Schemas is beyond the scope of this post, you'll find plenty of information around the web - a good first stop is this W3Schools XML Schema tutorial.

This all sounds very good, but here's the rub: the revXML library offers no built-in support for XML Schemas. So yet again we turn to Java, with its built-in XML Validation API. We can easily execute Java code using LiveCode's shell function - so let's start by writing the XmlValidateSchema class:

import java.io.File;
import java.io.IOException;

import javax.xml.XMLConstants;
import javax.xml.parsers.DocumentBuilder;
import javax.xml.parsers.DocumentBuilderFactory;
import javax.xml.parsers.ParserConfigurationException;
import javax.xml.transform.Source;
import javax.xml.transform.dom.DOMSource;
import javax.xml.validation.Schema;
import javax.xml.validation.SchemaFactory;
import javax.xml.validation.Validator;

import org.w3c.dom.Document;
import org.xml.sax.SAXException;

public class XmlValidateSchema {
 public static void main(String[] args) throws SAXException, ParserConfigurationException, IOException {
  final File xmlFile = new File(args[0]);
  final File xsdFile = new File(args[1]);
  // Load the XML file
  final DocumentBuilderFactory docBuilderFactory = DocumentBuilderFactory.newInstance();
  final DocumentBuilder docBuilder = docBuilderFactory.newDocumentBuilder();
  final Document document = docBuilder.parse(xmlFile);
  // Load the XSD file
  final SchemaFactory schemaFactory = SchemaFactory.newInstance(XMLConstants.W3C_XML_SCHEMA_NS_URI);
  final Schema schema = schemaFactory.newSchema(xsdFile);
  final Validator validator = schema.newValidator();
  // Validate the XML document against the XSL schema
  final Source source = new DOMSource(document);
  validator.validate(source);
 }
}

In keeping with earlier Java examples, the code is a bit lazy when it comes to exception handling: if any exception is thrown, it will end up in the output of our shell function call. The only important thing to remember is that the first parameter is the XML file, and the second is the XML Schema Definition (XSD) file.

Let's go to LiveCode and create a new stack for the user interface.

As you can see, there's a field for the Schema text, a field for the XML text, and a button to Validate the XML against the Schema. Since it's perhaps a tad small, here's the content of the Schema field:

<?xml version="1.0"?>
<xs:schema 
    xmlns:xs="http://www.w3.org/2001/XMLSchema"
    targetNamespace="http://www.quartam.com" 
    xmlns="http://www.quartam.com"
    elementFormDefault="qualified">

<xs:element name="RootNode" type="RootNode"/>

<xs:complexType name="RootNode">
  <xs:sequence>
    <xs:element name="BranchNode" type="BranchNode" maxOccurs="unbounded"/>
  </xs:sequence>
  <xs:attribute name="SpecVersion" type="xs:string"/>
</xs:complexType>

<xs:complexType name="BranchNode">
  <xs:sequence>
    <xs:element name="LeafNode" type="xs:string" maxOccurs="unbounded"/>
  </xs:sequence>
</xs:complexType>

</xs:schema>

And here's the content of the XML field:

<?xml version="1.0"?>
<RootNode 
    xmlns="http://www.quartam.com"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xsi:schemaLocation="http://www.quartam.com schema.xsd"
    SpecVersion="1.0">
  <BranchNode>
    <LeafNode>The first leaf node</LeafNode>
    <LeafNode>The second leaf node</LeafNode>
    <LeafNode>The third leaf node</LeafNode>
  </BranchNode>
  <BranchNode>
    <LeafNode>The fourth leaf node</LeafNode>
    <LeafNode>The fifth leaf node</LeafNode>
  </BranchNode>
</RootNode>

After saving the stack, we copy the compiled XmlValidateSchema.class file into the same directory as the stack. Now we can write the script for the 'Validate' button:

on mouseUp
   --> write Schema and XML to temporary files
   local tSchemaFile, tXmlFile
   put the tempName into tSchemaFile
   put field "Schema" into URL ("file:" & tSchemaFile)
   put the tempName into tXmlFile
   put field "XML" into URL ("file:" & tXmlFile)
   --> assemble the shell command
   local tShellCommand
   put "java XmlValidateSchema" && \
          ShellPath(tXmlFile) && \
          ShellPath(tSchemaFile) \
          into tShellCommand
   --> execute the shell command
   local tHideConsoleWindows, tDefaultFolder, tShellResult
   put the hideConsoleWindows into tHideConsoleWindows
   set the hideConsoleWindows to true
   put the defaultFolder into tDefaultFolder
   set the defaultFolder to AbsolutePathFromStack()
   put shell(tShellCommand) into tShellResult
   set the defaultFolder to tDefaultFolder
   set the hideConsoleWindows to tHideConsoleWindows
   --> cleanup the temporary files
   delete file tSchemaFile
   delete file tXmlFile
   if tShellResult is not empty then
      answer error tShellResult
   end if
end mouseUp

function AbsolutePathFromStack pFileName
   local tAbsolutePath
   put the effective filename of this stack into tAbsolutePath
   set the itemDelimiter to slash
   if pFileName is not empty then
      put pFileName into item -1 of tAbsolutePath
   else
      delete item -1 of tAbsolutePath
   end if
   return tAbsolutePath
end AbsolutePathFromStack

function ShellPath pPath
   if the platform is "Win32" then
      put quote & pPath & quote into pPath
   else
      replace space with backslash & space in pPath
   end if
   return pPath
end ShellPath

This time around, we didn't have to fiddle with the Java classpath, as the XML Validation API is built-in. However, we had to write the XML and Schema to temporary files, to avoid length limitations in the shell command. If we now make a deliberate mistake, say change one of the 'LeafNode' elements into a 'BeafNode' element, we see this error:

Again, the image is a bit small, so here's the content of the error:

ERROR:  'cvc-complex-type.2.4.a: Invalid content was found starting with element 'BeafNode'. One of '{"http://www.quartam.com":LeafNode}' is expected.'
Exception in thread "main" org.xml.sax.SAXParseException: cvc-complex-type.2.4.a: Invalid content was found starting with element 'BeafNode'. One of '{"http://www.quartam.com":LeafNode}' is expected.
	at com.sun.org.apache.xerces.internal.jaxp.validation.Util.toSAXParseException(Util.java:109)
	at com.sun.org.apache.xerces.internal.jaxp.validation.ErrorHandlerAdaptor.error(ErrorHandlerAdaptor.java:104)
	at com.sun.org.apache.xerces.internal.impl.XMLErrorReporter.reportError(XMLErrorReporter.java:382)
	at com.sun.org.apache.xerces.internal.impl.XMLErrorReporter.reportError(XMLErrorReporter.java:316)
	at com.sun.org.apache.xerces.internal.impl.xs.XMLSchemaValidator$XSIErrorReporter.reportError(XMLSchemaValidator.java:429)
	at com.sun.org.apache.xerces.internal.impl.xs.XMLSchemaValidator.reportSchemaError(XMLSchemaValidator.java:3185)
	at com.sun.org.apache.xerces.internal.impl.xs.XMLSchemaValidator.handleStartElement(XMLSchemaValidator.java:1831)
	at com.sun.org.apache.xerces.internal.impl.xs.XMLSchemaValidator.startElement(XMLSchemaValidator.java:705)
	at com.sun.org.apache.xerces.internal.jaxp.validation.ValidatorHandlerImpl.startElement(ValidatorHandlerImpl.java:335)
	at com.sun.org.apache.xml.internal.serializer.ToXMLSAXHandler.closeStartTag(ToXMLSAXHandler.java:205)
	at com.sun.org.apache.xml.internal.serializer.ToXMLSAXHandler.characters(ToXMLSAXHandler.java:524)
	at com.sun.org.apache.xml.internal.serializer.ToXMLSAXHandler.characters(ToXMLSAXHandler.java:467)
	at com.sun.org.apache.xalan.internal.xsltc.trax.DOM2TO.parse(DOM2TO.java:229)
	at com.sun.org.apache.xalan.internal.xsltc.trax.DOM2TO.parse(DOM2TO.java:215)
	at com.sun.org.apache.xalan.internal.xsltc.trax.DOM2TO.parse(DOM2TO.java:215)
	at com.sun.org.apache.xalan.internal.xsltc.trax.DOM2TO.parse(DOM2TO.java:215)
	at com.sun.org.apache.xalan.internal.xsltc.trax.DOM2TO.parse(DOM2TO.java:121)
	at com.sun.org.apache.xalan.internal.xsltc.trax.DOM2TO.parse(DOM2TO.java:85)
	at com.sun.org.apache.xalan.internal.xsltc.trax.TransformerImpl.transformIdentity(TransformerImpl.java:615)
	at com.sun.org.apache.xalan.internal.xsltc.trax.TransformerImpl.transform(TransformerImpl.java:661)
	at com.sun.org.apache.xalan.internal.xsltc.trax.TransformerImpl.transform(TransformerImpl.java:300)
	at com.sun.org.apache.xerces.internal.jaxp.validation.ValidatorImpl.process(ValidatorImpl.java:220)
	at com.sun.org.apache.xerces.internal.jaxp.validation.ValidatorImpl.validate(ValidatorImpl.java:141)
	at javax.xml.validation.Validator.validate(Validator.java:82)
	at XmlValidateSchema.main(XmlValidateSchema.java:31)

Thanks to the combination of LiveCode and Java, we can develop cross-platform solution quickly, without having to give up the power of existing libraries. Unfortunately, loading Java every time for a shell call is not the optimal solution, so in another post, we'll investigate how we can run Java code using LiveCode's 'process' communication. Stay tuned...

Stamping PDF files

2010-12-30T05:38:00.000-08:00

In a previous post, I examined how we can use LiveCode and the Java-based iText library to concatenate a series of existing PDF files into a single PDF file. Now we will examine how we can 'stamp' a PDF file with an image using the same technique.

The first thing to code is the Java class that we will call using the shell function. Here's what I came up with:

import java.io.FileOutputStream;
import java.io.IOException;
import java.io.OutputStream;

import com.lowagie.text.DocumentException;
import com.lowagie.text.Image;
import com.lowagie.text.Rectangle;
import com.lowagie.text.pdf.PdfContentByte;
import com.lowagie.text.pdf.PdfReader;
import com.lowagie.text.pdf.PdfStamper;

public class StampPdfFile {
  public static void main(String[] args) throws IOException, DocumentException {
    final String inputFile = args[0];
    final String outputFile = args[1];
    final String imageFile = args[2];
    final String[] coords = args[3].split(",");
    final PdfReader inputReader = new PdfReader(inputFile);
    final OutputStream outputStream = new FileOutputStream(outputFile);
    final PdfStamper outputStamper = new PdfStamper(inputReader, outputStream);
    final int pageCount = inputReader.getNumberOfPages();
    final Image image = Image.getInstance(imageFile);
    final int left = Integer.parseInt(coords[0]);
    final int top = Integer.parseInt(coords[1]);
    final int right = Integer.parseInt(coords[2]);
    final int bottom = Integer.parseInt(coords[3]);
    final int height = bottom - top;
    final int width = right - left;
    image.scaleToFit(width, height);
    for (int pageIndex = 1; pageIndex <= pageCount; pageIndex++) {
      final PdfContentByte overContent = outputStamper.getOverContent(pageIndex);
      final Rectangle pageSize = inputReader.getPageSize(pageIndex);
      image.setAbsolutePosition(left, pageSize.getHeight() - bottom);
      overContent.addImage(image);
    }
    outputStamper.close();
  }
}

In a nutshell, the first parameter is the input file, the second the output file, the third the image file, and the fourth parameter is a comma-separated list of coordinates making up the target rectangle. As usual, the code is a tad lazy when it comes to faulty input parameters and exception handling - if there's a mistake you'll simply get the stacktrace as the output of the shell command.

The most important bit is in the loop over the pages, where we use the outputStamper.getOverContent() method to draw our image on top of the existing content. If you'd rather have the image in the back, as a watermark, you would use the outputStamper.getUnderContent() methopd instead. Also note that setting the image position coordinate system works from the bottomLeft of the page, so we have to use the original page height and subtract the bottom coordinate from it.

Now we can proceed with writing a LiveCode button script:

on mouseUp
   --> determine the input, output and image files
   local tInputFile, tOutputFile, tImageFile
   put ShellPath(AbsolutePathFromStack("demo1.pdf")) \
          into tInputFile
   put ShellPath(AbsolutePathFromStack("stamp.pdf")) \
          into tOutputFile
   put ShellPath(AbsolutePathFromStack("Template.png")) \
          into tImageFile
   --> determine the image target rectangle
   local tImageRect
   put quote & "10,10,103,87" & quote \
          into tImageRect
   --> determine the class path
   local tClassPath
   if the platform is "Win32" then
      put ".;iText-2.1.7.jar" into tClassPath
   else
      put ".:iText-2.1.7.jar" into tClassPath
   end if
   --> assemble the shell command
   local tShellCommand
   put "java -classpath" && tClassPath && \
          "StampPdfFile" && \
          tInputFile && \
          tOutputFile && \
          tImageFile && \
          tImageRect \
          into tShellCommand
   --> execute the shell command
   local tHideConsoleWindows, tDefaultFolder, tShellResult
   put the hideConsoleWindows into tHideConsoleWindows
   set the hideConsoleWindows to true
   put the defaultFolder into tDefaultFolder
   set the defaultFolder to AbsolutePathFromStack()
   put shell(tShellCommand) into tShellResult
   set the defaultFolder to tDefaultFolder
   set the hideConsoleWindows to tHideConsoleWindows
   if tShellResult is not empty then
      answer error tShellResult
   end if
end mouseUp

function AbsolutePathFromStack pFileName
   local tAbsolutePath
   put the effective filename of this stack into tAbsolutePath
   set the itemDelimiter to slash
   if pFileName is not empty then
      put pFileName into item -1 of tAbsolutePath
   else
      delete item -1 of tAbsolutePath
   end if
   return tAbsolutePath
end AbsolutePathFromStack

function ShellPath pPath
   if the platform is "Win32" then
      put quote & pPath & quote into pPath
   else
      replace space with backslash & space in pPath
   end if
   return pPath
end ShellPath

Click the button, and it happily takes the existing PDF files (demo1.pdf), paints the image (Template.png) on top of all pages, and writes a new PDF file (stamp.pdf) in the same folder as our stack. There we have it, another example of using iText from within LiveCode.

Concatenating PDF files

2010-12-29T01:11:00.000-08:00

Since the advent of LiveCode 4.5, developers have the ability to 'print' stack content directly to PDF files. And if you need pin-point control over what goes where, you can use Quartam PDF Library to generate PDF files from scripts. That's great if you are in full control of the content, but what if you need to work with existing PDF files? In the next few posts, we will examine how you can tap into the power of the Java-based iText library from LiveCode.
So let's start by downloading a copy of iText version 2.1.7 - do not use version 5.x as the API changed and the following example code won't work.

The first question is: how can we execute Java code from LiveCode? The simplest solution is the shell function: it allows you to execute DOS or Unix commands, as if you typed them in from the command line. Note that on Windows, using this function will show a DOS window, but you can control that by setting the hideConsoleWindows property before calling the shell function.
You can test it out by simply executing the following line from the message box:

  answer shell("java -version")

The second question is: what sort of Java code do we need to write? Well, I fired up a copy of Eclipse, started a new project, and created a new class 'ConcatPdfFiles' in the default package. Then I grabbed my paper copy of iText in action (first edition) and flipped to page 64 as this contains the examples for concatenating PDF files. A little bit of thinking, and I derived the following code:

import java.io.FileOutputStream;
import java.io.IOException;
import java.io.OutputStream;

import com.lowagie.text.Document;
import com.lowagie.text.DocumentException;
import com.lowagie.text.pdf.PdfCopy;
import com.lowagie.text.pdf.PdfReader;

public class ConcatPdfFiles {
 public static void main(String[] args) throws DocumentException, IOException {
  final String outputFilePath = args[0];
  final OutputStream outputStream = new FileOutputStream(outputFilePath);
  final Document outputDocument = new Document();
  final PdfCopy outputCopy = new PdfCopy(outputDocument, outputStream);
  outputDocument.open();
  for (int i = 1; i < args.length; i++) {
   final PdfReader inputPdfReader = new PdfReader(args[i]);
   final int pageCount = inputPdfReader.getNumberOfPages();
   for (int pageIndex = 0; pageIndex < pageCount; pageIndex++) {
    outputCopy.addPage(outputCopy.getImportedPage(inputPdfReader, pageIndex + 1));
   }
  }
  outputDocument.close();
 }
}

As you can see, the code is a bit lazy when it comes to exception handling: I just let the exceptions get thrown, and this will be the output of our shell call if something goes wrong. Note also that the first argument is the output file, followed by the input files that you want to concatenate into the output file.

More importantly, at this point in time, the code doesn't compile. The problem is, we haven't yet told Eclipse where that iText-2.1.7.jar library file is, so compilation fails. This is sometimes referred to as 'classpath hell' - you have to give Java a list of paths where it can find the necessary additional libraries, not just at compile time but also at runtime as we'll see later.
Because I like to keep everything together in my Java projects, I added a new 'lib' folder to my project, and copied the iText2.1.7.jar file into it. At that point, you can use the contextual menu on the iText.2.1.7.jar file, and add it to the Build Path. Now the code I showed earlier compiles just fine, and we can proceed to the next stage.

The third question is: how do we put everything together in LiveCode? We'll begin by putting all the necessary parts into a single folder: the iText-2.1.7.jar library file, the ConcatPdfFiles.class compiled file and two example PDF files (demo1.pdf and demo2.pdf). Then we fire up LiveCode, create a new stack 'ConcatPdfFiles' and save it in the same folder as the other files, naming it "ConcatPdfFiles.liveCode'. Now we can drop a button onto the stack and start scripting.

Now we need to determine the correct command to be executed by the shell function. It should look something like:

java -classpath <class-path> ConcatPdfFiles <output-file> <input-file-1> <input-file-2> ...

The java executable needs the correct classpath, and we need to pass in compatible file paths.

Let's start with the classpath. This is a list of places that java needs to look for its .class files - as separate files in folders, or stored together in a .jar file. And for extra fun, the separator character is a colon on Unix-based platforms, and a semicolon on Windows. You can have relative paths in this classpath, and '.' (period) is short for the current directory. So rather than building a long class path, we can circumvent the issue by setting the defaultFolder property to change the working directory before calling the shell function. Then our classpath can be as short as:

.:iText-2.1.7.jar

on MacOS X/Linux and

.;iText-2.1.7.jar

on Windows.

The next bit is compatible file paths. The good news: LiveCode uses a '/' (slash) as separator, regardless of the underlying platform, and Java is more than happy to accept '/' in a path, even when it's running on Windows. However, if there are spaces in the path, we need to save them by putting quotes around the path on Windows, and escaping the spaces with a backslash on Unix-based platforms.
And to determine the paths relative to the stack's location on your hard disk, we'll need a helper function that uses the effective filename property of our stack.

So finally, we have a button script as follows:

on mouseUp
   --> determine the input and output files
   local tInputFiles, tOutputFile
   put ShellPath(AbsolutePathFromStack("demo1.pdf")) && \
          ShellPath(AbsolutePathFromStack("demo2.pdf")) \
          into tInputFiles
   put ShellPath(AbsolutePathFromStack("output.pdf")) \
          into tOutputFile
   --> determine the class path
   local tClassPath
   if the platform is "Win32" then
      put ".;iText-2.1.7.jar" into tClassPath
   else
      put ".:iText-2.1.7.jar" into tClassPath
   end if
   --> assemble the shell command
   local tShellCommand
   put "java -classpath" && tClassPath && \
          "ConcatPdfFiles" && \
          tOutputFile && tInputFiles \
          into tShellCommand
   --> execute the shell command
   local tHideConsoleWindows, tDefaultFolder, tShellResult
   put the hideConsoleWindows into tHideConsoleWindows
   set the hideConsoleWindows to true
   put the defaultFolder into tDefaultFolder
   set the defaultFolder to AbsolutePathFromStack()
   put shell(tShellCommand) into tShellResult
   set the defaultFolder to tDefaultFolder
   set the hideConsoleWindows to tHideConsoleWindows
   if tShellResult is not empty then
      answer error tShellResult
   end if
end mouseUp

function AbsolutePathFromStack pFileName
   local tAbsolutePath
   put the effective filename of this stack into tAbsolutePath
   set the itemDelimiter to slash
   if pFileName is not empty then
      put pFileName into item -1 of tAbsolutePath
   else
      delete item -1 of tAbsolutePath
   end if
   return tAbsolutePath
end AbsolutePathFromStack

function ShellPath pPath
   if the platform is "Win32" then
      put quote & pPath & quote into pPath
   else
      replace space with backslash & space in pPath
   end if
   return pPath
end ShellPath

Click the button, and it happily concatenates the two PDF files (demo1.pdf and demo2.pdf) into a single PDF file (output.pdf) in the same folder as our stack. There we have it, our first use of iText from within LiveCode.

I went to the Devoxx 2010 conference and...

2010-11-21T08:43:00.001-08:00

and I got the t-shirt to prove it

100% Javaholic was the motto of this year's Java developer conference, organised by the Belkgian JUG and held in Antwerp.
Of course, I wasn't there to collect the t-shirt - unlike some others who shall remain unnamed and went from booth to booth to fetch a t-shirt, even if they weren't interested in the product. You know who you are :-p

and I met Bruno Lowagie

For those who don't know Bruno Lowagie, he's the primary developer behind the iText project, an open-source library for producing PDF files using Java. There must be something in the water around here, as he lives about 30 miles from my house - two Belgians, both writing PDF libraries - what are the odds?
As he was busy signing copies of iText in Action (second edition) the conversation was rather short, but he signed my copy of his book with "To a fellow PDF developer" - what a compliment :-)

and I managed to squeeze LiveCode onto a whiteboard

Given that someone actually added 'HyperTalk :-)' to the board right behind my entry, I think I wasn't the only guy there who knows LiveCode. Next time, poke me and I'll buy you a drink.

and had a very good time overall

Plenty of interesting sessions, friendly environment and excellent organization. I'll definitely go back next time I get the chance.

Revolution is now LiveCode

2010-09-20T11:54:00.000-07:00

Earlier today, RunRev announced the availability of LiveCode 4.5 - the new name and version for the development platform Revolution.

If you've come here and don't know what LiveCode/Revolution is: it is a cross-platform development tool for Windows, MacOSX and Linux, sporting a very-high-level-language that allows you to create working solutions in far less time than other tools and languages. The LiveCode Web browser plug-in works very similar to Flash and Silverlight. There are also pre-releases available of LiveCode Server (comparable to a PHP engine) and LiveCode for iOS (yep, IPhone, iPad and iPod Touch).

Whenever I get a chance, I'll use LiveCode to put together a quick tool for my own use, or a prototype/mockup for something that will eventually be developed in another language like Progress OpenEdge ABL or Java. I also offer Quartam Reports for LiveCode, the essential report generator, and Quartam PDF Library, for those occasions when you need to go beyond 'print to pdf file'.

Where Java is built around a relatively small platform-specific Virtual Machine implementation, with a huge bytecode library on top, LiveCode has a far more optimized yet surprisingly lean core implementation for each supported operating system, and a rich language that means you'll type fewer lines of code to accomplish the same result.

I like the name change and the clearer product line-up. And I like how this new version is faster than ever before. Cheers to the RunRev team for wrapping it up after the setback concerning the iPhone/iPad implementation. Combined with Apple's recent liberation of developer tools, the future looks decidedly LiveCode!

XML validation using a DTD and Versions

2010-09-12T09:19:00.000-07:00

In a previous post, I invetigated how we could validate an XML file in revTalk by using a DTD. As we all know, requirements evolve and our software needs to adapt likewise, especially at the integration end-points. So if we need to accept more data, we should (a) know that it's coming, and (b) make sure it's there before we process the incoming data.

How do we do that? Well, as we've seen beofre, we can check the structure of the XML file. And to make sure we check it correctly, we should introduce a specification version for our XML structure, and attach it to the root node of the document as an attribute. Then all we need to do is check the root node, extract its SpecificationVersion attribute, and we can apply the correct DTD validation.

Doesn't sound too complicated, does it? Let's expand our current stack design a bit so that it looks like this:

As you can see, the field "DTD" was renamed to "DTD 1.0" and another field "DTD 1.1" was added to hold the DTD for specification version 1.1; finally, I moved down the "Validate" button and modified its script:


constant kMaxVersion = 1.1

on mouseUp
   -- Load the XML into a local variable
   local tXmlText
   put field "XML" into tXmlText
   -- Parse the XML text into a Tree
   local tXmlTree
   put revCreateXmlTree(tXmlText, \
          false, \
          true,  \
          false) \
          into tXmlTree
   if tXmlTree is not an integer then
      answer error \
             "There is an error in the XML structure" & return & \
             tXmlTree  -- contains the full error message
   else
      -- Validate the root node
      local tRootNode
      put revXmlRootNode(tXmlTree) into tRootNode
      if tRootNode is not "RootNode" then
         answer error \
                "The XML root node should be 'RootNode'"
      else
         -- Validate the SpecVersion
         local tSpecVersion
         put revXmlAttribute(tXmlTree, tRootNode, \
                "SpecificationVersion") into tSpecVersion
         if tSpecVersion begins with "xmlerr" then
            answer error \
                   "The SpecificationVersion is missing"
         else if tSpecVersion > kMaxVersion then
            answer error \
                   "The SpecificationVersion " && tSpecVersion && \
                   "is newer than" && kMaxVersion
         else
            -- Load the corresponding DTD
            local tDtdText
            if tSpecVersion is 1.0 then
               put field "DTD 1.0" into tDtdText
            else
               put field "DTD 1.1" into tDtdText
            end if
            -- Validate the XML against the DTD
            local tValidationResult
            put revXmlValidateDTD(tXmlTree, tDtdText) \
                   into tValidationResult
            if tValidationResult is not empty then
               answer error \
                      "The XML structure does not conform" & \
                      return & tValidationResult
            else
               answer information "The XML conforms to the DTD"
            end if
         end if
      end if
      -- Cleanup
      revDeleteXmlTree tXmlTree
   end if
end mouseUp

So how does this new version work?
- first, it parses the XML document
- next, it verifies the root node
- next, it checks the specification version
- next, it loads the appropriate DTD
- finally, it validates the XML against the DTD

If we test it, it correctly informs us that the XML document conforms to our specification version 1.1. What happens if we change the SpecificationVersion to 1.2?

Then we get this error message:

And finally, what happens if we change the SpecificationVersion to the original 1.0?

Then we get this error message:

This is a much safer way to check the incoming data in XML format. Unfortunately, a Document Type Definition is quite a limited way of XML validation. So next time, we'll improve our defenses again, by incorporating XML Schemas.

XML validation using a DTD

2010-09-07T10:44:00.001-07:00

One of the positive aspects of the Extensible Markup Language XML is that it is a flexible way to structure data in a human-readable format, in a cross-platform and technology-independent way. No wonder it is widely used as a way to exchange data between applications, and forms the foundation for XML-RPC, SOAP and other Web Service methods.

But it would be naive to think that every XML document that we get is not only well-formed, but also in the format that we expect it to be, with the right elements and attributes. In this post, we'll examine a strategy to validate incoming XML data in our revTalk application, using a Document Type Definition - a.k.a. DTD.

Part of the XML specification since the very start, a DTD describes the structure of the XML elements and attributes. For more information, I advise you to study the excellent introductory tutorials on W3Schools.com. We're here to use it from revTalk, so let's start by creating a new stack for the user interface.

Simply drop two scrolling fields onto it, name them "XML" and "DTD" respectively, and then group each of them separately so we can put a nice group label on top (I have the memory of a goldfish so I might forget which-is-which ;-) ) Finally drop a button at the bottom of the stack and set its name to "Validate" - and now we're ready to start scripting the button.

First things first, we need to parse the XML text into an XML tree to use all the rev XML commands and functions.


on mouseUp
   -- Load DTD and XML into local variables
   local tDtdText, tXmlText
   put field "DTD" into tDtdText
   put field "XML" into tXmlText
   -- Parse the XML text into a Tree
   local tXmlTree
   put revCreateXmlTree(tXmlText, \
          false, \ -- must be well-formed
          true,  \ -- create a tree in memory
          false) \ -- no SAX parser messages
          into tXmlTree
   if tXmlTree is not an integer then
      answer error \
             "There is an error in the XML structure" & return & \
             tXmlTree  -- contains the full error message
   else
      -- Clean up resources
      revDeleteXmlTree tXmlTree
   end if
end mouseUp

We use the revCreateXmlTree function to parse the XML text into a tree structure. If the XML test is not well-formed then we report the error, otherwise we know we have a valid XML tree structure at our disposal - which we need to cleanup after we're done, using the revDeleteXmlTree command. Now that we have the basics covered, we can add the DTD validation to our script.


on mouseUp
   -- Load DTD and XML into local variables
   local tDtdText, tXmlText
   put field "DTD" into tDtdText
   put field "XML" into tXmlText
   -- Parse the XML text into a Tree
   local tXmlTree
   put revCreateXmlTree(tXmlText, \
          false, \  -- must be well-formed
          true, \ -- create a tree in memory
          false) \ -- no SAX parser messages
          into tXmlTree
   if tXmlTree is not an integer then
      answer error \
             "There is an error in the XML structure" & return & \
             tXmlTree  -- contains the full error message
   else
      -- Validate the XML against the DTD
      local tValidationResult
      put revXmlValidateDTD(tXmlTree, tDtdText) \
             into tValidationResult
      if tValidationResult is not empty then
         answer error \
                "XML structure does not conform to the DTD" & return & \
                tValidationResult  -- contains the full error message
      else
         answer information "The XML conforms to the DTD"
      end if
      -- Clean up resources
      revDeleteXmlTree tXmlTree
   end if
end mouseUp

If the XML conforms to the DTD, the revXmlValidateDtd function will return empty, otherwise its output contains the validation error. Pretty straightforward, so let's test this with a simple XML and DTD:

When we click the 'Validate' button, we get the message that the XML conforms to the DTD. Exactly what we were hoping for. Now let's change the XML somewhat to see if it fails when our XML text clearly does not conform to the DTD.

And here's the error message that we get on our screen:

With very little scripting, we have added a first layer of defense against incoming XML data that is not up to our specifications. Next time, we'll elaborate on this example and bolster our defenses.

Fun with detailed files - and stat

2010-08-18T10:08:00.001-07:00

In a previous post, I tried to find a way to convert Unix user and group ids into their corresponding names. After I reported my findings to the use-revolution mailing list, Andre Garzia stepped in, suggesting to take a look at the stat command.

Calling 'stat' through the shell function for every file would be costly and slow; using it to fetch the information for an entire folder in one go wouldn't be so bad, but if you already use the detailed files function built into revTalk, it would seem like a waste of cycles. So I decided to rewrite my work handlers, employing a caching mechanism for the id-to-name mapping, and using 'stat' to pick up the mapping information not available in the cache.

--> script-local 'static' variables

local sGroupIdMap, sUserIdMap

--> public functions and commands

command LoadIdMaps
  p_LoadGroupIdMap
  p_LoadUserIdMap
end LoadIdMaps

function GroupIdToName pGroupId, pFile
  local tName, tShellCommand
  put sGroupIdMap[pGroupId] into tName
  if tName is empty and the platform is "MacOS" then
    -- stat is only available on MacOS X
    put p_GetFileStat(pFile, "%Sg") into tName
    put tName into sGroupIdMap[pGroupId]
  end if
  return tName
end GroupIdToName

function UserIdToName pUserId, pFile
  local tName, tShellCommand
  put sUserIdMap[pUserId] into tName
  if tName is empty and the platform is "MacOS" then
    -- stat is only available on MacOS X
    put p_GetFileStat(pFile, "%Su") into tName
    put tName into sUserIdMap[pUserId]
  end if
  return tName
end UserIdToName

--> private functions and commands

private function p_GetFileStat pFile, pFormat
  local tName, tShellCommand
  -- make sure to escape spaces in the file name
  replace space with backslash & space in pFile
  put "stat -f" && pFormat && pFile into tShellCommand
  put word 1 of shell(tShellCommand) into tName
  return tName
end p_GetFileStat

private command p_LoadGroupIdMap
  if the platform is "Win32" then exit p_LoadGroupIdMap
  p_LoadFileIdMap "/etc/group", sGroupIdMap
end p_LoadGroupIdMap

private command p_LoadUserIdMap
  if the platform is "Win32" then exit p_LoadUserIdMap
  p_LoadFileIdMap "/etc/passwd", sUserIdMap
end p_LoadUserIdMap

private command p_LoadFileIdMap pFile, @pIdMap
  local tData, tLine
  put URL ("file:" & pFile) into tData
  set the itemDelimiter to colon
  repeat for each line tLine in tData
    -- skip empty and comment lines
    if tLine is empty \
        or char 1 of tLine is "#" then next repeat
    -- fill the id map
    put item 1 of tLine into pIdMap[item 3 of tLine]
  end repeat
end p_LoadFileIdMap

Armed with the above set of commands and functions, we can still use the detailed files function and obtain user and group names from a cache, calling into 'stat' as necessary. Let's update our sample button script:

on mouseUp
  local tOldFolder, tNewFolder, tDetailedFiles
  answer folder "Select a folder"
  if the result is "Cancel" then exit mouseUp
  put it into tNewFolder
  --> extract the detailed files information
  put the defaultFolder into tOldFolder
  set the defaultFolder to tNewFolder
  put the detailed files into tDetailedFiles
  --> load the group and user id maps
  LoadIdMaps
  --> build the extended file information
  local tDetailedFile, tExtendedFiles
  local tFile, tUserId, tGroupId
  repeat for each line tDetailedFile in tDetailedFiles
    -- skip hidden files
    if char 1 of tDetailedFile is "." then next repeat
    -- fill the extended file entry
    put urlDecode(item 1 of tDetailedFile) into tFile
    put item 8 of tDetailedFile into tUserId
    put item 9 of tDetailedFile into tGroupId
    put tFileName & tab & \
        UserIdToName(tUserId, tFile) & tab & \
        GroupIdToName(tGroupId, tFile) & return \
        after tExtendedFiles
  end repeat
  --> wrap things up
  set the defaultFolder to tOldFolder
  put char 1 to -2 of tExtendedFiles into field "Files"
end mouseUp

The more observant amongst you may think "If all you needed was a file's user and group name, why not just 'stat' and get it over with?" - well, the detailed files function returns a lot of useful information in one go, including the size of the resource fork of a file on MacOS systems.
Just one more thing: the 'stat' function was added in MacOS X 10.4 Tiger - so if your application still needs to support MacOS X 10.3 Panther, you're going to have to merge in the 'nireport' call from the previous post. Consider it an exercise for the reader.

On to the next challenge!

Fun with detailed files

2010-08-17T14:14:00.000-07:00

Earlier today, the following question was posted on the use-revolution mailing list: file owner & group names. Rev veteran Monte Goulding was wondering how to convert file owner and group ids into actual user and group names. I happily logged into the Solaris server at work and dug around a bit, finally replying that he could parse this information from the following two files:

/etc/group
/etc/passwd

And what would such a parsing script look like in revTalk? I'm glad you asked:

command LoadGroupIdMap @pGroupIdMap
  p_LoadFileIdMap "/etc/group", pGroupIdMap
end LoadGroupIdMap

command LoadUserIdMap @pUserIdMap
  p_LoadFileIdMap "/etc/passwd", pUserIdMap
end LoadUserIdMap

private command p_LoadFileIdMap pFile, @pIdMap
  local tData, tLine
  put URL ("file:" & pFile) into tData
  set the itemDelimiter to colon
  repeat for each line tLine in tData
    -- skip empty and comment lines
    if tLine is empty \
        or char 1 of tLine is "#" then next repeat
    -- fill the id map
    put item 1 of tLine into pIdMap[item 3 of tLine]
  end repeat
end p_LoadFileIdMap

Given that both files use a colon as item delimiter, and have the name as first item and the id as third item, I extracted the parsing into a separate private command. Put the above handlers in your stack script, and then fetch each id-to-name-mapping before interpreting the detailed files.
Here's a simple button script that uses the above commands:

on mouseUp
  local tOldFolder, tNewFolder, tDetailedFiles
  answer folder "Select a folder"
  if the result is "Cancel" then exit mouseUp
  put it into tNewFolder
  --> extract the detailed files information
  put the defaultFolder into tOldFolder
  set the defaultFolder to tNewFolder
  put the detailed files into tDetailedFiles
  set the defaultFolder to tOldFolder
  --> load the group and user id maps
  local tGroupIdMap, tUserIdMap
  LoadGroupIdMap tGroupIdMap
  LoadUserIdMap tUserIdMap
  --> build the extended file information
  local tDetailedFile, tExtendedFiles
  repeat for each line tDetailedFile in tDetailedFiles
    -- skip hidden files
    if char 1 of tDetailedFile is "." then next repeat
    -- fill the extended file entry
    put urlDecode(item 1 of tDetailedFile) & tab & \
        tUserIdMap[item 8 of tDetailedFile] & tab & \
        tGroupIdMap[item 9 of tDetailedFile] & return \
        after tExtendedFiles
  end repeat
  --> wrap things up
  put char 1 to -2 of tExtendedFiles into field "Files"
end mouseUp

Once I got home, I wanted to verify this on my MacOS X machine, only to discover that it wasn't properly mapping the uid and gid to user and group names. Intrigued, I dug a bit deeper and found out that MacOS X actually relies on a DirectoryService when it's not running in single-user mode. Lovely, but how can we get what we need using revTalk?
Well, it turns out you can use the nireport command via the shell function to fetch a list of the group and user names with id. So let's add another helper command to do things the MacOS X way, and update our existing commands to use the correct approach, depending on the platform.

command LoadGroupIdMap @pGroupIdMap
  if the platform is "MacOS" then
    p_LoadNireportIdMap "/groups gid name", pGroupIdMap
  else if the platform is "Linux" then
    p_LoadFileIdMap "/etc/group", pGroupIdMap
  end if
end LoadGroupIdMap

command LoadUserIdMap @pUserIdMap
  if the platform is "MacOS" then
    p_LoadNireportIdMap "/users uid name", pUserIdMap
  else if the platform is "Linux" then
    p_LoadFileIdMap "/etc/passwd", pUserIdMap
  end if
end LoadUserIdMap

private command p_LoadFileIdMap pFile, @pIdMap
  local tData, tLine
  put URL ("file:" & pFile) into tData
  set the itemDelimiter to colon
  repeat for each line tLine in tData
    -- skip empty and comment lines
    if tLine is empty \
        or char 1 of tLine is "#" then next repeat
    -- fill the id map
    put item 1 of tLine into pIdMap[item 3 of tLine]
  end repeat
end p_LoadFileIdMap

private command p_LoadNireportIdMap pParams, @pIdMap
  local tData, tLine
  put shell ("nireport ." && pParams) into tData
  set the itemDelimiter to tab
  repeat for each line tLine in tData
    put item 2 of tLine into pIdMap[item 1 of tLine]
  end repeat
end p_LoadNireportIdMap

This seemed to do the trick on my iMac PowerPC G5 running MacOS X 10.4 Tiger - but when I tried it on my MacBook Pro Intel running MacOS X 10.6 Snow Leopard, it failed as there is no "nireport" command available. As it turns out, Apple dropped NetInfo when MacOS X 10.5 Leopard came out. So my solution is not quite complete, unfortunately.

To be continued...

BorderLayout example - with resizing

2010-08-01T09:56:00.001-07:00

In a previous post, I examined how you can mimic Java's BorderLayout behavior in revTalk. At the end of that post, I promised to explain how you can add resizers to the West and East panels. Just as a reminder, here's what we had accomplished in the previous installment:

Before we get to the meat of the resizers, let's do some preparation work. To clearly show the user that he can drag around the resizers, we'll make a local copy of the vertical divide resize cursor that the RunRev team ships with the IDE. Open the message box and type:


copy image "vdividecursor.gif" of card id 1030 of stack "revMacCursors" to this card

We'll be using that as our cursor later, but it doesn't have to be visible for that to work - so you can hide it now. Next, we add a rectangular button, carefully placing it over the touching edges of the West and Center panels. Set the button's name to "WestResizer" and its width to 5, and make sure its height is the same as the West and Center panel. Here's what it should look like:

Before we add the script, we'll also add two custom properties to the West graphic:
-set the uMinWidth custom property to 75
-set the uMaxWidth custom property to 150

Now that we have the visuals worked out, let's script the resizer button:


local sIsResizing
local sMinX, sMaxX

on mouseEnter
   lock cursor
   set the cursor to the short id of image "vdividecursor.gif"
end mouseEnter

on mouseLeave
   unlock cursor
end mouseLeave

on mouseDown
   local tMouseOffset
   put item 1 of the mouseLoc - item 1 of the location of me \
       into tMouseOffset
   put the uMinWidth of graphic "West" + tMouseOffset into sMinX
   put the uMaxWidth of graphic "West" + tMouseOffset into sMaxX
   put true into sIsResizing
   pass mouseDown
end mouseDown

on mouseUp
   put false into sIsResizing
   pass mouseUp
end mouseUp

on mouseRelease
   put false into sIsResizing
   pass mouseRelease
end mouseRelease

on mouseMove x,y
   if sIsResizing is true then
      local tNewX
      put min(max(x, sMinX), sMaxX) into tNewX
      lock screen
      set the left of me to tNewX - 3
      set the widthFromLeft of graphic "West" to tNewX
      dispatch "resizeCenterPanel" to this card
      unlock screen
   end if
   pass mouseMove
end mouseMove

While it's not too long a script, some explanation is in order:
- the mouseEnter and mouseLeave messages are handled to update the cursor
- the mouseDown message is handled to setup a few script local variables:
-> the sIsResizing variable is used as a flag to track the status
-> the sMinX and sMaxX variables are calculated once, based on the offset between the mouse and the resizer button, and taking into account the minimum and maximum width we set earlier
-> calculating those once helps cut down on the math later on
- the mouseUp and mouseRelease messages are handled to turn off the sIsResizing flag
- the mouseMove message is handled to resize the West and Center panels
-> but only if the sIsResizing flag is true
-> it uses the sMinX and sMaxX variables to make sure we don't go too far either way
-> it updates the resizer button itself, the West panel, and the Center panel.

To make this work, we obviously also have to add a handler for our custom 'resizeCenterPanel' event. We'll add that to the card script in a bit, after we've finished the resizer for the East panel. So duplicate the WestResizer button, name the copy EastResizer and move it over to the right, placing it over the touching edges of the East and Center panels.

Before we add the script, we'll also add two custom properties to the East graphic:
-set the uMinWidth custom property to 100
-set the uMaxWidth custom property to 200

Next, update its script to:


local sIsResizing
local sMinX, sMaxX

on mouseEnter
   set the lockCursor to true
   set the cursor to the short id of image "vdividecursor.gif"
end mouseEnter

on mouseLeave
   set the lockCursor to false
end mouseLeave

on mouseDown
   local tMouseOffset
   put item 1 of the mouseLoc - item 1 of the location of me \
       into tMouseOffset
   put the width of this stack - \
       the uMinWidth of graphic "East" + \
       tMouseOffset into sMaxX
   put the width of this stack - \
       the uMaxWidth of graphic "East" + \
       tMouseOffset into sMinX
   put true into sIsResizing
   pass mouseDown
end mouseDown

on mouseUp
   put false into sIsResizing
   pass mouseUp
end mouseUp

on mouseRelease
   put false into sIsResizing
   pass mouseRelease
end mouseRelease

on mouseMove x,y
   if sIsResizing is true then
      local tNewX
      put min(max(x, sMinX), sMaxX) into tNewX
      lock screen
      set the left of me to tNewX - 3
      set the left of graphic "East" to tNewX
      set the widthFromLeft of graphic "East" to \
          the width of this stack - tNewX
      dispatch "resizeCenterPanel" to this card
      unlock screen
   end if
   pass mouseMove
end mouseMove

The difference with the WestResizer is that the EastResizer also has to take into account the width of the stack, but that's not too complicated. Finally we'll update the card script, adding a handler for the 'resizeCenterPanel' custom event, and we'll also take care of updating the resizer's location and height when the stack is resized. The new card script looks like this:


on resizeStack pNewWidth, pNewHeight
   local tCenterHeight, tCenterWidth
   --
   lock screen
   -- update the north and south panels
   set the widthFromLeft of graphic "North" to pNewWidth
   set the widthFromLeft of graphic "South" to pNewWidth
   set the bottom of graphic "South" to pNewHeight
   put the top of graphic "South" - \
       the bottom of graphic "North" \
       into tCenterHeight
   -- update the west and east panels
   set the heightFromTop of graphic "West" to tCenterHeight
   set the heightFromTop of graphic "East" to tCenterHeight
   set the right of graphic "East" to pNewWidth
   put the left of graphic "East" - \
       the right of graphic "West" \
       into tCenterWidth
   -- update the west and east resizers
   set the heightFromTop of button "WestResizer" to tCenterHeight
   set the heightFromTop of button "EastResizer" to tCenterHeight
   set the left of button "EastResizer" to \
       the left of graphic "East" - 3
   -- update the center panel
   set the widthFromLeft of graphic "Center" to tCenterWidth
   set the heightFromTop of graphic "Center" to tCenterHeight
   --
   unlock screen
   pass resizeStack
end resizeStack

--> custom event handlers

on resizeCenterPanel
   local tCenterWidth, tCenterHeight
   put the top of graphic "South" - \
       the bottom of graphic "North" \
       into tCenterHeight
   put the left of graphic "East" - \
       the right of graphic "West" \
       into tCenterWidth
   lock screen
   set the left of graphic "Center" to the right of graphic "West"
   set the top of graphic "Center" to the bottom of graphic "North"
   set the widthFromLeft of graphic "Center" to tCenterWidth
   set the heightFromTop of graphic "Center" to tCenterHeight
   unlock screen
   pass resizeCenterPanel
end resizeCenterPanel

--> helper property setters

setProp widthFromLeft pNewWidth
   local tRectangle
   --
   lock screen
   put the rectangle of the target into tRectangle
   put item 1 of tRectangle + pNewWidth into item 3 of tRectangle
   set the rectangle of the target to tRectangle
   unlock screen
end widthFromLeft

setProp heightFromTop pNewHeight
   local tRectangle
   --
   lock screen
   put the rectangle of the target into tRectangle
   put item 2 of tRectangle + pNewHeight into item 4 of tRectangle
   set the rectangle of the target to tRectangle
   unlock screen
end heightFromTop

And there we have it: a BorderLayout with resizers for the West and East panels.

Once you're happy with the way the resizers work, you can change the style of the WestResizer and EastResizer button to transparent. They'll continue to work just fine, but won't be visible. With a little more work, you can also add resizers for the North and South panels. But I'll leave that as an exercise to the reader...

BorderLayout example script

2010-07-26T12:58:00.000-07:00

As you may know, I spend quite a bit of my time in Java, not merely building back-end systems with message queues and raw socket communication, but also creating user interfaces in Swing. One of the most compelling features of Swing is its system of LayoutManagers - and certainly the easiest-to-use is the BorderLayout. Today, I'm going to explain how you can mimic this type of layout handling in revTalk.

The principle of the BorderLayout is quite simple: it divides the window into 5 panels: North, East, South, West and Center. As a picture says more than a thousand words, here's what this layout generally looks like:

The North panel is a good place to store a toolbar, the South panel usually plays host for a status area, while the West panel may show an outline, and the East panel a property grid, leaving the Center for the actual content.

For this example, I chose the easy route, creating a single rectangle graphic for each panel. I also picked distinct colors so you can more easily see the effect of resizing the window once the pieces of the puzzle fall into place. And it turns out it isn't that much work to implement, as I set the card script to:


on resizeStack pNewWidth, pNewHeight
   local tCenterHeight, tCenterWidth
   --
   lock screen
   -- update the north and south panels
   set the widthFromLeft of graphic "North" to pNewWidth
   set the widthFromLeft of graphic "South" to pNewWidth
   set the bottom of graphic "South" to pNewHeight
   put the top of graphic "South" - \
       the bottom of graphic "North" \
       into tCenterHeight
   -- update the west and east panels
   set the heightFromTop of graphic "West" to \
       tCenterHeight
   set the heightFromTop of graphic "East" to \
       tCenterHeight
   set the right of graphic "East" to pNewWidth
   put the left of graphic "East" - \
       the right of graphic "West" \
       into tCenterWidth
   -- update the center panel
   set the widthFromLeft of graphic "Center" to \
       tCenterWidth
   set the heightFromTop of graphic "Center" to \
       tCenterHeight
   --
   unlock screen
   pass resizeStack
end resizeStack

--> helper property setters

setProp widthFromLeft pNewWidth
   local tRectangle
   --
   lock screen
   put the rectangle of the target into tRectangle
   put item 1 of tRectangle + pNewWidth \
       into item 3 of tRectangle
   set the rectangle of the target to tRectangle
   unlock screen
end widthFromLeft

setProp heightFromTop pNewHeight
   local tRectangle
   --
   lock screen
   put the rectangle of the target into tRectangle
   put item 2 of tRectangle + pNewHeight \
       into item 4 of tRectangle
   set the rectangle of the target to tRectangle
   unlock screen
end heightFromTop

Let's see what is happening here. The script handles the resizeStack event, which has 4 parameters (new width, new height, old width, old height) of which we only use the first two.

As the North and South panels use up the entire width, I can simply set their width to the new width of the stack. However, setting the width of a control in revTalk works from the location of the control (which is the center, not the topleft).
So I use a fake helper property setter 'widthFromLeft' to update the rectangle of the control instead. Finally, we move the South panel to the bottom edge of the window, and calculate the distance between the top of the south panel and the bottom of the north panel, as this is the new height for our West, East and Center panels.

Armed with this information, I follow a similar path for the West and East panels, updating their height using a fake helper property setter 'heightFromTop', and moving the East panel to the right edge of the window, calculating the distance between the east and west panels to determine the new width of the Center panel. And now it is dead-easy to update the Center panel with the calculated width and height.

That's all there is to it! Admittedly, this example merely resizes 5 graphics, but you can extend this logic to groups, handling the resizeControl message in your group scripts to automatically update the layout of the group's contents.

Here's what it looks like when stretched horizontally.

And here's what it looks like when stretched vertically.

Straightforward to implement with very little code. Next time, I'll add some resizers for the West and East panels.

DataGrid Filter example - with sorting

2010-07-22T12:53:00.000-07:00

The other day I posted an example of how you can add a filter to a DataGrid in Revolution. At the end of that blog post, I remarked how I had deliberately turned off column sorting. Fear not, it is straightforward to add support for this, again thanks to the DataGrid lessons available on the runrev.com website.

Just as a reminder, here's a screenshot of the example stack:

So what do we need to do to allow the user to click on the column header and apply the sort and filter at the same time? It's quite a simple bity of scripting, but before we get to that, you need to make some minor modifications to the datagrid columns.
- Switch to the 'pointer' tool, and select the datagrid, then open the Object Inspector, and switch to the 'Columns' panel
-> select the column 'index' and set its Sort by column type to 'Numeric'
-> select the column 'name' and make sure its Sort by column type is 'Text'

Now edit the script of the datagrid, and set it to:


local sOriginalData
local sIndexMap
local sFilter

setProp dgData pData
  put pData into sOriginalData
  RebuildMap
end dgData

getProp dgData
  return sOriginalData
end dgData

setProp dgFilter pFilter
  put pFilter into sFilter
  RebuildMap
end dgFilter

getProp dgFilter
  return sFilter
end dgFilter

--> datagrid callbacks

on GetDataForLine pLine, @pData
  local tKey
  -- retrieve the original line of data
  put sIndexMap[pLine] into tKey
  put sOriginalData[tKey] into pData
end GetDataForLine

on SortDataGridColumn pColumn
  SortMap pColumn
  HiliteAndStoreSortByColumn pColumn
  dispatch "RefreshList" to me
end SortDataGridColumn

--> private commands and functions

private command RebuildMap
  local tKeys, tKey, tIndex
  put empty into sIndexMap
  put 0 into tIndex
  put the keys of sOriginalData into tKeys
  sort tKeys numeric
  repeat for each line tKey in tKeys
    if sFilter is empty \
    or sOriginalData[tKey]["name"] contains sFilter \
    then
      add 1 to tIndex
      put tKey into sIndexMap[tIndex]
    end if
  end repeat
  set the dgNumberOfRecords of me to tIndex
  SortMap
  dispatch "ResetList" to me
end RebuildMap

private command SortMap pColumn
  local tSortDirection, tSortType, tSortCaseSensitive
  local tSortCommand
  local tKeys, tKey, tNewIndex, tNewIndexMap
  -- works whether a column is specified or not
  if pColumn is empty then
    -- find the current sort column
    put the dgProps["sort by column"] of me into pColumn
    if pColumn is empty then
      exit SortMap
    end if
  end if
  -- assemble and do the sort command
  put the dgColumnSortDirection[pColumn] of me \
    into tSortDirection
  put the dgColumnSortType[pColumn] of me \
    into tSortType
  put the dgColumnSortCaseSensitive[pColumn] of me \
    into tSortCaseSensitive
  put "sort lines of tKeys" && tSortDirection \
    into tSortCommand
  switch tSortType
    case "numeric"
      put " numeric" after tSortCommand
      break
    case "international"
      put " international" after tSortCommand
      break
    case "datetime"
    case "system datetime"'
      put " dateTime" after tSortCommand
      break
  end switch
  put " by ColumnValueForLine(pColumn, each)" \
    after tSortCommand
  set the caseSensitive to \
    (tSortCaseSensitive is true)
  set the useSystemDate to \
    (tSortType is "system datetime")
  put the keys of sIndexMap into tKeys
  do tSortCommand
  -- rebuild the index map
  put 0 into tNewIndex
  repeat for each line tKey in tKeys
    add 1 to tNewIndex
    put sIndexMap[tKey] into \
      tNewIndexMap[tNewIndex]
  end repeat
  put tNewIndexMap into sIndexMap
end SortMap

private function ColumnValueForLine pColumn, pLine
  local tKey
  -- retrieve the original line of data
  put sIndexMap[pLine] into tKey
  return sOriginalData[tKey][pColumn]
end ColumnValueForLine

What's changed in comparison to the last implementation? Well, the bulk of the necessary work is done in the new private command SortMap, which reads the column sort properties and uses a custom sort function to get the filtered lines in the right order on the basis of the column value in the original lines of data. Then it builds a new IndexMap to replace the old one, and the regular refresh routines of the datagrid will "just work."

So what happens when we sort the data descending on the name, without applying a filter?

Looking good - does the filter still work? Let's type 'url' into the filter field.

You may have noticed that I also added getProp-handlers for dgData and dgFilter, making the above script easily reusable. With just a bit of lateral thinking and coding, you too can build just about anything, thanks to Revolution.

DataGrid Filter example

2010-07-19T12:21:00.000-07:00

One of the powerful additions to Revolution 3.5 is the DataGrid - a custom control group that allows you to display any type of data with astonishing flexibility. Recently, I had to add filtering capabilities to a data grid for one of my projects. In this post, I will explain how I accomplished it, thanks to the DataGrid lessons available on the runrev.com website.

Here's a screenshot of the example stack:

Execute the following steps, if you want to follow along:
- Create a new stack
- Drag a button to the topleft of the card and set its name to "Fill"
- Drag a text field to the topright of the card
- Drag a label field next to the text field and set its content to "Filter:"
- Drag a data grid onto the card and configure it using the Object Inspector
-> In the 'Basic Properties' panel, turn off the checkbox "Allow Text Editing"
-> Switch to the 'Columns' panel, and add 2 columns "index" and "name"
-> Edit the script of the DataGrid, and set it to the following:


local sOriginalData
local sIndexMap
local sFilter

setProp dgData pData
  put pData into sOriginalData
  RebuildMap
end dgData

setProp dgFilter pFilter
  put pFilter into sFilter
  RebuildMap
end dgFilter

private command RebuildMap
  local tKeys, tKey, tIndex
  put 0 into tIndex
  put the keys of sOriginalData into tKeys
  sort tKeys numeric
  repeat for each line tKey in tKeys
    if sFilter is empty \
    or sFilter is in sOriginalData[tKey]["name"] \
    then
      add 1 to tIndex
      put tKey into sIndexMap[tIndex]
    end if
  end repeat
  set the dgNumberOfRecords of me to tIndex
  dispatch "ResetList" to me
end RebuildMap

on GetDataForLine pLine, @pData
  local tKey
  put sIndexMap[pLine] into tKey
  put sOriginalData[tKey] into pData
end GetDataForLine

on SortDataGridColumn pColumn
  -- prevent column sorting
end SortDataGridColumn

The above data grid script will take care of filtering the data. Now it's just a matter of wiring up the text field.
-> Edit the script of the text field and set it to the following:


local sUpdateMsg

on keyUp pKey
  ScheduleUpdate
  pass keyUp
end keyUp

on deleteKey
  ScheduleUpdate
  pass deleteKey
end deleteKey

on backspaceKey
  ScheduleUpdate
  pass backspaceKey
end backspaceKey

on pasteKey
  ScheduleUpdate
  pass pasteKey
end pasteKey

on cutKey
  ScheduleUpdate
  pass cutKey
end cutKey

command ScheduleUpdate
  if sUpdateMsg is empty then
    send "UpdateFilter" to me in 100 milliseconds
    put the result into sUpdateMsg
  end if
end ScheduleUpdate

on UpdateFilter
  set the dgFilter of group "DataGrid 1" \
    to the text of me
  put empty into sUpdateMsg
end UpdateFilter

By trapping the different key events, we can update the data grid filter as we go along. Note that I used the ScheduleUpdate helper command to try and minimize the number of refreshes for quick typers. Play around with the interval until you find the sweet spot of responsive user interface.

Finally, it is time to fill the data gird with some data for testing, so edit the script of the button and set it to the following:


on mouseUp
  local tData, tIndex, tName
  put 0 into tIndex
  repeat for each line tName in the functionNames
    add 1 to tIndex
    put tIndex into tData[tIndex]["index"]
    put tName into tData[tIndex]["name"]
  end repeat
  set the dgData of group "DataGrid 1" to tData
end mouseUp

This simple script will fill our data grid with a list of the built-in functions that revTalk has to offer. Click the button, and type away in the filter text field to see the effect. Here's what happens when I type "cos":

Looks pretty good, doesn't it? It certainly was good enough for my use, but there are a few things to bear in mind about this implementation:
- I didn't have to edit the data in the grid.
- I didn't have to support sorting for my particular project.
Both of these limitations can be overcome, but I'll leave that for another time...

Forums moved over to quartam.on-rev.com

2010-07-18T13:41:00.000-07:00

Hi All,

After much deliberation, I have decided to move the forums over from ning.com to my new on-rev based website: http://quartam.on-rev.com/forums/index.php.
And here's an even shorter link: http://forums.quartam.com.

All posts were imported as plain text, and the topics were locked.
Unfortunately, you will have to re-register as a user on the new forum.

I apologize for any inconvenience, caused by this switch.

Best regards,

Jan Schenkel
--
Quartam Reports & PDF Library for Revolution
www.quartam.com

But the waiting makes me curious

2010-03-14T10:27:00.000-07:00

Be patient, is very good advice, but the waiting makes me curious.
It's a line from the song 'Very Good advice' written for the original Disney 'Alice in Wonderland' movie and recently remade by The Cure's Robert Smith for the 'Almost Alice' soundtrack. And I just couldn't think of a better introduction to this blog entry on the revTalk 'wait' command.

When your script is in a tight loop, screen updates my not happen until after the whole script is finished.

on mouseUp
  repeat with i = 1 to 5000
    put i into field "Output"
  end repeat
end mouseUp

Rather than continuously updating the content of the field, the field may only get updated after the repeat loop. While that's good enough in this silly example, it's not suitable for keeping the user updated on the progress of a real-world data crunching routine.

You can give the engine some breathing room by inserting a call to the 'wait' command.

on mouseUp
  repeat with i = 1 to 5000
    put i into field "Output"
    -- allow screen to redraw
    wait 0 milliseconds
  end repeat
end mouseUp

Now you'll see the content of the field refreshed regularly; but it also makes your loop much slower.

on mouseUp
  constant kRefresh = 25
  repeat with i = 1 to 5000
    put i into field "Output"
    if i mod kRefresh is 0 then
      -- allow screen to redraw
      wait 0 milliseconds
    end if
  end repeat
end mouseUp

By only redrawing the screen every 25th iteration, we can still refresh the screen with less impact on performance. Play with the 'kRefresh' constant value to find the right redraw/performance ratio.

But that's not all the 'wait' command can do: if used properly, you can give your users a way to 'cancel' out of a tight loop.

on mouseUp
  constant kRefresh = 25
  enable button "Cancel"
  set the uCancel of me to false
  repeat with i = 1 to 5000
    put i into field "Output"
    if i mod kRefresh is 0 then
      -- allow screen to redraw and user to cancel
      wait 0 milliseconds with messages 
      if the uCancel of me is true then
        answer "Are you sure you want to cancel?" \
            with "Yes" or "No"
        if it is "Yes"
        then exit repeat
        else set the uCancel of me to false
      end if
    end if
  end repeat
  disable button "Cancel"
end mouseUp

Now we add a button "Cancel" and give it the following script:

on mouseUp
  set the uCancel of button "TightLoop" to true
end mouseUp

And presto! Not only does the screen redraw, but we now allow the user to stop the time-consuming process in our tight loop. Of course you'll have to add your logic to 'revert' any changes you've made in the process, but the above provides you with a skeleton script for handling this sort of situation.

As with all good things in life, 'wait with messages' comes at a price: as the user can now click your button twice, or trigger other scripts, it is very important to disable those parts of your user interface that shouldn't be executed 'concurrently' - my favourite method is to switch to a 'limited' environment, disabling all controls, displaying a blended white overlay over them as well as the 'Cancel' button making it the only enabled control. After the loop, the stack returns to the 'unlimited' environment, hiding the overlay and enabling the controls.

Some of you may wonder what happens when a script issues 'wait 1 second with messages' and the user clicks on another button: the other button's script is executed first, and then the engine checks if the wait timeout has passed, and resumes the original script. This means that if your other button script takes 5 seconds to complete, your first button script will remain suspended - the revEngine is not multi-threaded. But with a little planning, you can provide a much better user experience.

In memoriam: Bill Marriott

2010-01-12T12:14:00.000-08:00

As usual after the Holidays, I had some catching up to do with emails on the use-revolution mailing list. It was quite a shock when I read the news that William Marriott, marketing director at RunRev, had passed away.

To the rev developer community, he was the guy who worked his way up from the trenches, growing from a vocal advocate of quality, to the man who held surveys to figure out who we were and what we wanted, and helped in so many ways to reshape the image of the RunRev company. For the revSelect third-party add-on developers, he was the guy who not only gracefully hosted the webinars, but was in general someone you could easily work with to get results (a character trait shared at RunRev HQ, I might add).

At the RunRevLive '08 conference in Las Vegas, I had the pleasure of taking up an afternoon of his time to talk about how I could improve my existing products, and exchange thoughts on an assortment of ideas. His combined marketing and programming skills, plus his sense of humour, make him a hard act to follow.

My condolences and thoughts are with his family. May he rest in peace, or find a way to smuggle his laptop into heaven.

Error handling in revTalk

2009-11-17T01:38:00.000-08:00

No matter how carefully we craft our code to do the right thing, there will always be error outside of our control: a disk may be full, we may not have sufficient privileges, the server connection is lost, etc. So how do we handle this sort of situation in revTalk? Depending on the situation, we check 'the result' after each potentially failing action, or we adopt the 'try-catch-throw' triad.

Personally, I favor the triad as it is common in languages such as Java or the .NET family. And that's why I used it extensively in Quartam PDF Library, throwing errors whenever something was wrong. Some people find this annoying, I feel that it keeps my code cleaner as there is no error checking all over my script, obfuscating what I'm really trying to accomplish.

The important thing to remember is that revTalk is a language which mixes the approaches: for a command like 'open file' you must check the result to see if it failed by any chance. However, if you try to set the 'angle' of an image to "foobar" it will throw an error as "foobar" is not an integer. It's probably due to the HyperCard heritage, where there was no try-catch-throw triad, but it's an inconsistency I'd rather see cleaned up.

Anyway, here's an example to get you started with the try-catch-throw paradigm. Just create a new stack, add a field named 'Log' and add a button with the following script:

on mouseUp
   try
      Foo
   catch tError
      Log "mouseUp: running catch block"
      answer error tError
   finally
      Log "mouseUp: running finally block"
   end try
end mouseUp

command Foo
   try
      Bar
   catch tError
      Log "Foo: running catch block (" & tError & ")"
   finally
      Log "Foo: running finally block"
   end try
   if tError is not empty then
      Log "Foo: rethrowing error (" & tError & ")"
      throw tError
   end if
end Foo

command Bar
   Log "Bar: before calling Snafu"
   Snafu
   Log "Bar: after calling Snafu"
end Bar

command Snafu
   answer "Continue, throw or exit to top?" with \
          "Continue" or "Throw" or "Exit to top"
   Log "Snafu: user picked (" & it & ")"
   if it is "Throw" then
      throw "Snafu: user decided to throw"
   else if it is "Exit to top" then
      exit to top
   end if
end Snafu

--

private command Log pText
   put pText & return after field "Log"
end Log

Click the button and pick the option 'Continue' - the following text should be in the log field:

Bar: before calling Snafu
Snafu: user picked (Continue)
Bar: after calling Snafu
Foo: running finally block
mouseUp: running finally block

As you can see, everything went smoothly, and the code in the finally blocks of both the Foo and mouseUp handlers were called. This is where you should handle any cleanup (such as closing the database, files, cursors,...)

Now click the button again and pick the option 'Throw' - the following text should appear in the log field:

Bar: before calling Snafu
Snafu: user picked (Throw)
Foo: running catch block (Snafu: user decided to throw)
Foo: running finally block
Foo: rethrowing error (Snafu: user decided to throw)
mouseUp: running catch block
mouseUp: running finally block

As you can see, the throw in the Snafu handler caused the catch block to be executed in the Foo handler, followed by its finally block. In this case, I decided to re-throw the error after the try block of the Foo handler, so that the catch block in the mouseUp handler would also be called, automatically followed by its finally block. Note that the Bar handler was immediately interrupted so no 'after' log line was written.

Now click the button once more and pick the option 'Exit to top' - the following text should appear in the log field:

Bar: before calling Snafu
Snafu: user picked (Exit to top)

Yes, that's right, this means that execution halts completely, and not even the finally blocks in the Foo and mouseUp handlers are called.

This last bit teaches us to be cautious and not try and mix the different approaches to error handling without testing out the consequences.

Some time for reflection?

2009-11-14T12:17:00.000-08:00

What do you do when you have two weeks off, after working hard for months to meet deadlines and ship a new module on time and per specification, with as only interruption: going to the RunRevLive'09 conference and doing three presentations? Well, I'm glad you asked - I started by catching up on sleep and doing the couch potato thing, watching Star Trek Enterprise season 3.

But along came the release of version 4.0 of the revPlatform, with the highly anticipated revWeb browser plug-in. A-ha, that means it's experiment time! So I sat down and made a little demo revlet, using nothing but graphics, gradients and a few lines of code to demonstrate one way of faking a reflection while playing a simple animation of three circles.

If you don't have the revWeb plug-in installed yet, get it here. Then open a new browser window to run the demo here. Click the 'Start' button to let the three circles roam around. I've included a link for you to download the original stack; if you don't yet have a copy of revMedia 4.0, you can download it here for free.

I'm sure the resident animation and graphics revGurus Ben Beaumont, Malte Brill or Scott Rossi could make it look so much better and smoother, but it's the result of playing around for about an hour, and I'm quite pleased with what I put together, given that my multimedia skills are virtually limited to stick figures.

The beauty of the revPlatform is its elegant language and extreme productivity. And now you can take revMedia for free and start creating revlets - no need to learn Flash ActionScript or JavaScript. Who can resist that?

Support questions and bug reports

2009-11-14T08:47:00.001-08:00

They're part of every-day life in the software business: users or colleagues encounter problems, and they need some way to find solutions. Sometimes a quick email is the answer, but generally speaking, there should be procedures in place to handle these items efficiently and transparently.

At my day-job, we have an internal application called MIA, which offers a complete environment for running a software business. Aside from the more mundane tasks of accounting, billing and license keys, it also keeps track of complaints, incidents, modifications and releases.
There is a web interface where customers can enter their issues, the support team picks these from the queue and tries to resolve them; if necessary, these incidents are escalated to a software engineer, which can result in a solution or a modification. The customer can track the status of the incident and if development is needed and scheduled, the planned version is added to the display as well.
We have corrective, functional and structural releases of our products and depending on the type of incident, it will be resolved in one of the next releases. Overall, it is an efficient system that our customers appreciate very much - even if they may not always like how long it takes to actually implement the change.

Of course, the situation is a little different for Quartam Software. It is mostly a one-man-show - apart from the external accountant who takes care of the taxes, and some help for the other accounting duties, I take care of everything: sending license keys, answering support emails, developing new features and fixing bugs, plus the information requests as well as the consulting and custom software jobs.
Unfortunately, that means I can't get to everything as quickly as I wish. I do try and get back to people in a reasonable time frame, and try to offer patch versions when some big problem pops up and the next functional release is still some time off. Sometimes, I fail to meet my own standards. But I, Jan Schenkel, am the person to send emails to, for everything.

In a larger organization, that is simply impossible to do: the manager is there to run the business and ensure the commercial success while the operations run smoothly. When procedures are in place, they should be followed to ensure that every item is handled correctly by the designated person. Only when things don't appear to be moving or important issues seem to get ignored, should you go one step higher, and involve management.
But please don't do it for every item that crops up, and be willing to compromise. The customer may be king, but the guy with the compiler is not a serf.

Revolution, Snow Leopard and AppleEvent handlers

2009-10-25T22:18:00.000-07:00

As you know, Macs have always sported a rather different operating system - in fact, MacOSX is quite good at hiding its powerful UNIX underpinnings from the average user, while still offering its full power to the more advanced computer user. But tossing out the old brittle 'cooperative multi-tasking' MacOS Classic, and swapping in the modern, robust NeXtStep with a new coat of paint, required that the Apple developers came up with a whole compatibility layer, named Carbon.

And one of the things that Carbon brought with it, was the system of Apple Events - added in System 7.0, this new type of event allowed Mac applicatiosn to talk to one another. Later, these Apple Events formed the underpinning of AppleScript, the system-wide scripting mechanism that is widely used for automating processes (and in turn, underpins the Automator tasks that allow you to point-and-click automation workflows in MacOSX).

What exactly is an Apple Event? An AppleEvent has a generic Class and Id, as well as associated data - and our rev stacks can handle these events by implementing an 'appleEvent' handler in our (stack) script. Alright, but why should I care as revDeveloper? Because if you want to write a decent Mac application, you had better implement the 'core' events. These are apple events of class 'aevt' and have an id of 'oapp' (open application), 'odoc' (open document), 'pdoc' (print document) or 'quit' (exit application).

Now, the revEngine is kind enough to handle the 'oapp' and 'quit' events for us, translating them into built-in events for us to handle, So we can concentrate on 'odoc' and 'pdoc' - and in fact, we only need to bother with these if we have some sort of 'editor' application. Of course, the Quartam Reports Layout Builder is exactly such an application. So I implemented a simple handler in my stack:

on appleEvent pClass, pId
  if pClass is "aevt" and pId is "odoc" then
    -- get the associated data
    request appleEvent data
    put it into tFilePath
    -- now handle opening the file somewhere else
    OpenFile tFilePath
  else
    -- let the revEngine handle other events
    pass appleEvent
  end if
end appleEvent

However, with the release of Snow Leopard, the format of the associated data appears to have changed rather dramatically. In previous releases, we would get a file path that we could use directly in file processing. For instance, your 'OpenFile' handler could look something like this:

on OpenFile pFilePath
  put URL ("binfile:" & pFilePath into tBinaryData
  -- go ahead and parse the content of the file
end OpenFile

For Snow Leopard, the good engineers at Apple have decided to change the format and where a file path from an 'odoc' event used to look something like "/My Big Project/Layouts/My First Layout.qrl", it now looks something like "file://localhost/My%20Big%20Project/Layouts/My%20First%20Layout.qrl" - presumabl, they're paving the way for other protocls than "file://" in the future, but this change has left our apps in the dust. I'm sure they were kind enough to update the Cocoa framework to translate this automatically, but what about us who don't drink the Objective-C Kool-Aid?

Well, the '%20' substitute for the space character, clued me in that there was some sort of URL encoding going on. So after a bit of fiddling, I came up with the following workaround for this prickly problem:

on appleEvent pCLass, pId
  if pClass is "aevt" and pId is "odoc" then
    -- get the associated data
    request appleEvent data
    put NormalizedPath(it) into tFilePath
    -- now handle opening the file somewhere else
    OpenFile tFilePath
  else
    -- let the revEngine handle other events
    pass appleEvent
  end if
end appleEvent

function NormalizedPath pFilePath
  put pFilePath into tNormalizedPath
  -- workaround change in Snow Leopard
  if char 1 to 7 of pFilePath is "file://" then
    set the itemDelimiter to slash
    delete item 1 to 3 of pFilePath -- remove "file://localhost" from front
    repeat for each item pFilePart in pFilePath
      put slash & urlDecode(tFilePart) after tNormalizedPath
    end repeat
  end if
  return tNormalizedPath
end NormalizedPath

Splitting off the NormalizedPath function means I can reuse it for the 'pdoc' Apple Event, if I ever were to support that. Plus, I can now add that to my 'generic' library that I share among all my applications. Anyway, I hope this blog post is of help to some fellow revDeveloper baffled by this problem.

Repeat loops, dialog boxes and aborting

2009-10-19T22:19:00.000-07:00

It's one of those things that happen to all revolution developers at one point: you have written a repeat loop, inserted some 'answer' dialogs to figure out the problem, only to discover you're stuck and can't abort the loop because the dialog box is in the way. The only way out is killing the process, which has as downside that you've lost all changes to your stack ince the last Save.

After you've been bitten once, you'll probably adopt the habit of inserting an escape plan in your loops. At the same time, you ought to prevent problems in your shipping code with these escape routes, but more on that later - a first escape route may look something like this:


repeat forever 
  add 1 to theCounter 
  answer theCounter 
  -- next block allows escape 
  if the cantAbort of this stack is false and the shiftKey is down then 
    answer "Are you sure you want to exit the loop after running" && theCounter && "times?" with "Continue" or "Exit" 
    if it is "Exit" then exit repeat 
  end if 
end repeat

The cantAbort property of a stack determines whether or not you can abort in the first place (something which you really ought to turn on in standalones) and there's a checkbox on the stack inspector so it's quite convenient.

Another option is to move that block of code into a separate handler at the stack level


on CheckForAbort pCounter 
  if the cantAbort of this stack is false and the shiftKey is down then 
    answer "Are you sure you want to abort execution of" && pInfo && "?" with "Continue" or "Exit" 
    if it is "Exit" then exit to top 
  end if 
end CheckForAbort

and then add a call to that handler in your loop


repeat forever 
  add 1 to theCounter 
  answer theCounter 
  CheckForAbort "TightLoop-" & theCounter 
end repeat

The downside of the second approach is that any cleanup code that comes after the repeat won't be called. Of course you can also rely on try-throw-catch exception handling, but some people find this awkward.

So just for completion, here's how you'd allow escape with cleanup via exception handling; first change the CheckForAbort handler to


on CheckForAbort pInfo 
  if the cantAbort of this stack is false and the shiftKey is down then 
    answer "Are you sure you want to abort execution of" && pInfo && "?" with "Continue" or "Exit" 
    if it is "Exit" then throw "Aborting execution of" && pInfo 
  end if 
end CheckForAbort

and then modify the script with the loop so that it resembles the following


try 
  repeat forever 
    add 1 to theCounter 
    answer theCounter 
    CheckForAbort "TightLoop-" & theCounter 
  end repeat 
catch tError 
  answer error tError 
finally 
  -- do your cleanup here 
  --> it will be called whether or not something throws an error 
end try

Hopefully, this will be of use to you at one point or another. Make sure to check out these entries in the documentation for more information about aborting running scripts: cantAbort stack property, allowInterrupts global property, interrupt function and of course the try-throw-catch triade for exception handling. Use them wisely, and provide your users with a safer envronment to work in...

Quartam Reports Webinar

2009-10-04T08:00:00.000-07:00

As announced in the revUp 79 newsletter for revAfficionados, I'll be hosting a webinar on Quartam Reports, sponsored by the revSelect third-party extension program.

What can you expect to see?
- a few slides to explain how Quartam Reports can help you revDevelopers
- some examples of what you can achieve with Quartam Reports
- a brisk walkthrough creating a report for an example application
- time for questions and answers at the end

Click here to register and join us on October 6, 2009 at 7pm BST (8pm for most of Europe, 2pm Eastern for US viewers) - if you can't make it, you can always watch the recording a few days later. I'll post the download link once available.

RunRevLive'09 Slides and Example Code

2009-10-04T07:54:00.000-07:00

Just a month ago, RunRev held their successful RunRevLive'09 conference in Edinburgh.

As I've blogged before, I had the honour of presenting on three topics:
- 'Working with Java Classes'
- 'Desktop Databases with SQLite'
- 'Basic Reports & Output'

By popular demand, I've made the slides and example code for these sessions available in the Downloads section on the quartam.com website.

Presenting at RunRevLive'09

2009-08-08T01:32:00.000-07:00

Edinburgh is the hometown of Runtime Revolution Ltd, the guys behind Revolution - and the scene of this year's RunRevLive conference. After the huge success of last year's conference in Las Vegas, it has the makings of yet aother groundbreaking conference, focusing on the revWeb browser plug-in, the new product line-up (revMedia for free, revStudio and revEnterprise for extremely affordable prices) and the unveiling of revServer (the engine behind On-Rev).

When the crew asked me to present at this conference, I jumped at the chance to not just be there as one of the many attendees, but share my experiences with the rest of the community - as I have done for years on the use-revolution mailing list and the official forums. After submitting proposals, I got the green light for three presentations: 'Working with Java Classes', 'Desktop Databases with SQLite' and 'Basic Reports & Output.'

'Working with Java Classes' (Day Zero) delves into the various ways Revolution applications can interact with Java classes: a half-hour rollercoaster ride along shell commands, process comunication, socket communication, web services, message queues and externals.

'Desktop Databases with SQLite' (Day One) will take you on a trip through a straightforward desktop application where the data is stored in an SQLite database. By the end, you should have a pretty good idea how to quickly develop a database front-end with revStudio or revEnterprise.

'Basic Reports & Output' (Day One) will use the same desktop application to demonstrate various ways of reporting: generating HTML and RTF documents, using Excel as reporting vehicle in multiple ways, sending stuff to the printer using the built-in commands, and (obviously) how you ca make your life easier with Quartam Reports and Quartam PDF Library for Revolution.

I'm looking forward to seeing you all at the conference, both familiar and new faces - there are few things better than finally meeting someone you've only known through exchanging emails, or going for drinks with someone you only get to see via these get-togethers. Plenty of good stuff, and no jet-lag for me as it's only a hop accross the channel :-)

revMedia 4 - a Revolution on the Web

2009-07-22T12:33:00.000-07:00

First announced last year at the runrevlive'08 conference in Las Vegas, the RunRev team has unveiled the first public alpha of their revWeb browser plug-in - the easiest way to create RIAs (Rich Internet Applications) for use on Mac, Windows and Linux. [click here to read the press release]

And to top it off, the revMedia toolkit will be absolutely free. No longer do you have to cobble together an AJAX-based RIA using JavaScript in the browser and PHP or something else on the back-end; you can stop wondering why the Flash designer tool just doesn't think like you and me; gone are the days of pondering if Microsoft is going to cripple Silverlight on other platforms; and you don't even have to place bets on whether or not JavaFX is really such a splendid idea from server-focused Sun (the beleaguered company that is soon-to-be-gobbled-up-by-Oracle, if you're not keeping tabs on that platform).

This is it: start of with revMedia, and deploy to the web; move up to revStudio when you need to build desktop applications that are native for each platform and don't require a 50 MB runtime download; and move up again to revEnterprise when you need Oracle or SSL; and when you need easy hosting that uses the exact same language to create dynamic websites, On-Rev is your platform of choice.

To be frank, I've always expressed my dismay regarding browsers as a deployment platform for 'real' business applications. Maybe if XUL had taken off, building a feature-rich application running inside a browser would have made more sense. But including miles and miles of JavaScript to try and mimick a desktop app, that was clearly an impressive workaround, but still a hobbled experience.

So I'm glad to see that the Revolution has hit the web, and we'll see a renaissance of good ol' HyperCard: easy to program and easy to run. Keep up the good work, RunRev team!

Another Batch of New Items on my Bookshelf

2009-05-23T02:15:00.000-07:00

Packt Publishing Ltd is celebrating its 5th Anniversay - and I couldn't resist their special deal of 5 books for 75 euros. So my book collection got expanded with the following titles.

Service Oriented Architecture with Java was the first book that caught my eye. It gives a broad overview of why SOA (Service Oriented Architecture) is a good approach to developing new and combining existing applications. It also does a good job explaining the difference between tradition EAI (Enterprise Application Integration) and SOA, and why using an ESB (Enterprise Service Bus) is a good idea to assemble all the parts.
Having finished this book the dame day as it arrived, I have to say I liked the content, but was a little confused by some of the sentence constructs; it doesn't help when both the authors and the reviewer are non-native English speakers; I had it a little easier since I worked with developers from India in a not-too-distant past. Even though a technical book doesn't have to read like poetry, an editor should prevent from adding to the complexity of the material.

Service Oriented Java Business Integration was the logical next item, as JBI is one of those items I have a particular interest in. Even though this book is centered around Apache ServiceMix, I'm sure I'll be able to apply its principles to the alternative Glassfish OpenESB open-source project backed by Sun. Especially when I combine its contents with what I learned from the book Building SOA-Based Composite Applications Using NetBeans IDE 6 that I picked up last year.

Java EE 5 Development with NetBeans 6 continues the theme of my desire to learn more about Java EE development with NetBeans and Glassfish. Currently about a third into this book, I find it a good companion to the book Java EE 5 Development using GlassFish Application Server by the same author, which I also picked up last year - naturally, there is some overlap, but I have the memory of a goldfish and the author really does a good job of explaining things.

EJB 3 Developer Guide wraps up the enterprise-oriented book tour. Packed with practical examples, it gets straight to business. When I want a more architectural point-of-view, I can always refer back to the book EJB 3 in Action, published by Manning, which is three times the size but also contains more of the theory and differences between EJB 3 and older versions - and how the introduction of Java EE 5 really did simplify development a lot.

Swing Extreme Testing may seem like the odd-one-out, but what's the use of building an enterprise application back-end, if no one can see the contents? Having built a number of Swing-based front-ends, I can attest it takes time to get it "right" - and I'm sure I'm still doing things wrong. I sure wish someone would publish a book that explains best practices for Swing user interface development like Effective Java does for the Java language.
But I digress. While I've gradually converted to using JUnit for writing unit tests for the classes that make up the domain model, I still have to decide on a framework for testing the user interface. Once I've worked my way through this book, I'll be sure to check out FEST (Fixtures for Easy Software Testing) as the online articles I've read are quite favorable to this framework.

Ah, so much to read, so many experiments to conduct - and only so little time...

Vive la Revolution!

2009-04-16T11:53:00.000-07:00

It has been a busy month of April at the Runtime Revolution HQ - last week we witnessed the release of Revolution 3.5, with its data grid and behavior scripting, and this week they've announced the On-Rev web hosting initiative.

Since the unveiling of the RunRev web strategy at the runrevlive '08 conference, last year in Las Vegas, Rev-afficionados around the globe have been eagerly anticipating the day where they can do away with the mix-and-match (or should that be 'mismatch'?) of technologies needed to build modern, Internet-enabled applications.
With customers and end-users requesting applications that work on desktops and web-browsers alike, developers have been forced to use combinations of JavaScript, Flash, .NET, Java and a myriad of frameworks to deliver solutions where not all features might have been fully implemented accross the different client interfaces.

With the Revolution of the Future, developers will finally be able to build those same solutions with a comprehensive technology stack based on one language, and have it work as a desktop application or in a web browser, backed by business logic with database access on the server-side.
Java promised us this 15 years ago, and then kinda-sorta forgot about this promise. Granted, Java SE 6u10 finally fixed the Applets experience, and Java EE 5 definitely simplified server-side development; but in their panic to provide an alternative to Flash, they produced JavaFX with a new scripting language that doesn't even work like Java.

In short, I think the RunRev team has a winner on their hands - and I am definitely looking forward to putting these new Revolution technologies to good use.

Behavior on the Grid

2009-03-26T14:38:00.000-07:00

Today, the good people of Runtime Revolution Ltd. presented an impressive webinar, showcasing the brand new Data Grid control that is a salivating new feature of Revolution 3.5 - in fact, this new control has given us a lot more than what most people would want from a table control. You can setup everything from a straightforward table with multiple alignments, to a spectacular form with dynamically resizing rows containing arbitrary controls with judicious use of template groups.

This crown jewel was developed using the other new big technological addition to Revolution: behaviors. This allows you to write a script once and apply it to several other controls at once - and when you update the original behavior script, all those controls adopt the change in behavior automatically.
Of course, if you're used to object-oriented programming, this sounds like simple inheritance. The xCard paradigm, pioneered over 20 years ago by Apple's HyperCard is traditionally object-based but not fully object-oriented; there's a limited set of built-in controls and you can 'specialize' these by adding a script.
Another typical OO design pattern, Chain of Responsibility, was the basis of the xCard message path, which allows developers to place handlers for events, command and function calls in a central place - if you needed to know where the event originated, you could use 'the target' property to work your magic from there.

Strictly speaking this was enough to build something like the Data Grid in the past, but the new 'behavior' feature makes it a lot easier. The 'me' object points to the 'target' rather than the button that contains the 'behavior' script - so we no longer have to subject ourselves to 'long id' shenanigans to make sure we're modifiying the right controls.
Experiments with the new 'behavior' scripting methods have me pondering how I can adopt this for all my Revolution projects and which controls I can rebuild and put together in a single library for reuse - and perhaps for others to use. Ah, if only there was a function to conjure a Time-Turner so I could do everything I want to do but fail to find the time for...

The 15 Minute Fix

2009-02-28T10:39:00.000-08:00

Every once in a while, you hear the infamous words "That should only take 15 minutes to fix" - often spoken by someone who isn't a professional software developer. While it is true that a number of bugs can be rectified rather quickly - think: typo or simple inversion of logic - the change in the source code is only a tiny part of the process.

At my day-job, we have to pay extreme attention to the accurate workings of our software. As we cater to the healthcare indsutry, the lives of patients may well depend on our software. The physicians need acuurate data to apply the best treatment, so it is our duty that we correctly handle all the input coming into our laboratory informaton system, as well as the output we produce in the form of reports or data exchange with the general hospital system.

This means we follow a strict procedure for every modification to the source code: analysis -> analysis review -> code -> code review -> unit test -> integration test -> documentation + localisation -> final review. Exhaustive test plans are executed at every release to ensure that the software is reliable and that one change doesn't have a hidden impact on another part of the system. And that's something which simply can't be done in a quarter of an hour.

Even then, you can never be sure that your program will doexectly what it's supposed to do. There are many internal and external variables at play - and even if a computer is supposed to be a deterministic system, where the exact same actions should have the exact same result, errors do occur that are sometimes hard to figure out. Computer software is a composition of many layers - hardware, operating system, frameworks, libraries - most of which are outside of our control.

Yet we all rely on technology and the building blocks we have, to build new functionality, patch existing code and sometimes make radical changes. And we hope that the person who built that underlying layer, is at least as smart as we are, and caught all the mistakes before that layer came to us for further use. Looking at the giant software companies' bug lists may leave you in a bit of a shock when you see thousands upon thousands of entries, some lingering for a decade.

Is it all gloom and despair though? Definitely not - there are plenty of good practices we as developers can and should apply. Where I used to only care about producing the code for the features, I now take the time to write tests for my code, and run my libraries and applications through a battery of manual tests before releasing them into the wild. That sure prevents a lot of frustration for testers and myself, yet even with all that care, sme things are bound to pop up in the field.

A quick internal build for test purposes may only take 15 minutes - but a real solution, fully tested and vetted, that can't be done in such a timeframe.

In memoriam: Eric Chatonet

2009-01-18T07:48:00.000-08:00

Today, as I was catching up with emails on the use-revolution mailing list, when I came accross a post La communauté Revolution est en deuil that informed the members of how Eric Chatonet had passed away.

Like many others, this news has left me with a deep sadness - for we, the members of the Revolution community, have all lost in Eric an extraordinary man - intelligent, generous, always helpful and armed with a wonderful sense of humour. I fondly remember meeting him in person at the Revolution Conference in Malta in 2006, exchanging ideas and experiences, and smoking cigarettes with him, Malte Brill, and Tariel Gogoberidze on the balcony of the hotel.

My condoleances and thoughts are with his family. Having unexpectedly lost my father 4 years ago, I have an idea of how his son must be feeling right now. May he rest in peace, with a glass of wine and a cigarette, enjoying the afterlife to its fullest. He certainly earned it.

Revolution newsletter articles

2009-01-03T23:17:00.000-08:00

One of the best things about Revolution is its strong-knit community - whether it's on the mailing list or on the forums, when you post a question there's bound to come an answer from one of the many users that have faced a similar problem. And soon enough, the newbies come of age and start replying to questions as well. This way, the good advice keeps getting spread over an ever-growing group of users.

Another important resource is the Revolution newsletter, where both the company's engineers and a variety of writers from the uer community share their knowledge and their solutions for challenges encountered while developing their applications. I just concluded a series of articles on using the 'merge' function, which got good reader feedback.

The 'merge' function is one of those extremely helpful weapons in the Revolution armoury, which every developer should know about and use, as it has many applications and can save you a lot of time. It goes through a text, and evaluates expressions that you've put in between [[...]] double square brackets, and executes statements that you've put in between <?...?> processing instruction brackets; and when it's done, it hands you back the end result.

This makes it an ideal tool for assembling HTML pages, RTF documents, XML files and other text-based file formats. But you can also use it as a preprocessor for templates, ranging from SQL queries to VBScript or AppleScript. One particular combination is to use Microsoft Word as a reporting system in two ways: merging an RTF template into a document, and then merging the necessary script to automate Word and print the document for you.

Here are links to the individual articles:
- The Power of Merge (revUp | Issue 55 | August 18th, 2008)
- The Word of Merge - part 1 (revUp | Issue 61 | November 20th, 2008)
- The Word of Merge - part 2 (revUp | Issue 62 | December 22nd, 2008)

Enjoy the articles and Revolution! And if you still have to make a New Year's resolution, make it something along the lines of 'I want to learn' - as education is the only path that leads to prosperity...

Future-proofing your Revolution scripts

2008-11-26T12:03:00.000-08:00

While I'm still not giving out details on the new features or release date for Quartam PDF Library 1.1, I would like to share some insights that I gained as part of my efforts on producing this new version. Back in September, the team of Runtime Revolution shipped version 3.0 of its cross-platform development tool Revolution.

Overall, Revolution 3.0 is an impressive release, with a revamped script editor, gradients, nested arrays and much-improved out-of-the-box experience thanks to the Start Center and Resource Center. One of the items that was also introduced, but not mentioned in the press release, was the new 'byte' chunk type.

If you're wondering what it's good for or why you would want to use it instead of the good old 'character' chunk type, then allow me to explain the underlying reason for its introduction. Back in the HyperCard days, not much attention was given to languages that didn't fall neatly in the ASCII-domain, based on the English alphabet, where one character takes up a single byte and thus there are 256 possible characters (a number of which are control characters that can't even be displayed on screen).

Naturally, this isn't quite enough room for a couple of thousand Chinese or Japanese characters, and that's where Unicode comes into play. This is a set of standards that govern how this much larger number of characters can be stored and should be interpreted. The UTF-8 standard still relies on single bytes as its main storage system, but uses special bit-settings to determine if the next character is a single byte or more than one byte.

My other favorite cross-platform technology Java embraced Unicode from the very first day, which made perfect sense given its goal of "write once, run anywhere" global software. And to make this easier, if less memory-efficient for those circumstances where you only have to deal with the ASCII characters, it uses UTF-16 everywhere.

When Revolution 2.0 saw the daylight, it introduced support for Unicode text entry and manipulation. Rather than jumping on the UTF-16 bandwagon, the engineers decided to implement a more flexible system that would use plain-old ASCII for everyday operations, while allowing the developer to use UTF-16 only when necessary.

While the implementation could still use some love and care, Revolution's technology director Mark Waddingham has big plans for it and wants to evolve to a system that is far less painful than anything else out there, but as resource-efficient as the current implementation. Which means that in the future, Revolution developers will be able to use the 'character', 'word', 'item' and 'line' chunks without having to care about the underlying encoding - the engine will know what constitutes a word or a sentence in the language of that piece of text and will take care of collation and all the gruesome details of Unicode.

Traditionally, the one-byte-is-one-character paradigm of xCard meant that developers could use the 'character' keyword, along with the 'charToNum' and 'numToChar' functions, to manipulate data at the byte-level. But with this equivalence fading away at some point in the future, the new 'byte' chunk type is our saviour!

Quartam PDF Library reads PNG and JPEG image files as byte streams, extracting information about the image height and width, bit depth and other binary-encoded information. To ensure that this and other binary-reading code will keep working correctly in the future, I've decided to make the necessary changes in version 1.1 to use the 'byte' chunk type rather than the 'character' chunk type.

While this means that the next version will require developers have Revolution 3.0 or higher, I feel this is a fair trade-off. In my experience, the new Revolution version performs well with less problems and quirks than ever. And if I compare my glacial speed of development with their feature-packed release momentum, I'm sure they will be shipping their next version before I do ;-)

Just in case you'd like to know how I updated and thus future-proofed my code, here are some pointers:
- replace 'open file theFilePath for read' with 'open file theFilePath for binary read'
- replace 'open file theFilePath for write' with 'open file theFilePath for binary write'
- replace 'length(theBinaryVariable)' / 'the number of chars in theBinaryVariable' with 'the number of bytes in theBinaryVariable'
- replace 'char x to y of theBinaryVariable' with 'byte x to y of theBinaryVariable'
- replace 'charToNum(char x of theBinaryVariable)' with 'byteToNum(byte x of theBinaryVariable)'
- replace 'numToChar(theNumber)' with 'numToByte(theNumber)'

That's it - no other changes required! The modification was straightforward and consistent, and everything works just fine. I know that my code will continue to work in future versions, and I can enjoy the same linear speed that I have now with the 'character' chunk type once that part is overhauled for Unicode embracing.

If only all requested or necessary changes were so easy to implement...

An Apparition

2008-11-11T01:32:00.000-08:00

If you have been wondering why it's been so quiet here lately, the answer is simple: a lot of work piled up, there was release pressure and the band that I sing in had its first gig - which ate up a lot of hours and energy. But things are slowly getting back to normal, and I'll have two weeks off from the day-job very soon - time which I'm going to spend relaxing and catching up on items that languished while I was busy. This blog is one of those bits that deserve attention. So let me start by finishing a post that I started to write back in August: 'The Programmer Syndrome'

The Programmer Syndrome

2008-08-07T10:43:00.000-07:00

No, it's not as if all developers exhibit the same behaviours or nervous tics - but a lot of us tend to suffer from two less-than-stellar character traits: the "Not Invented Here" syndrome and its nefarious cousin "I've always done it this way". Not exactly what you're looking for in an industry where there's a continuing debate about code reuse.

Of course it is a lot more fun to claim you're at the forefront of technology and innovation, but half of the time we're just rehashing the same technology - message queues are about as old as UN*X and let's not even talk about the Network Computer brouha. And sometimes this running in circles makes us blind and turn us into snooty stubborn time-wasters. If you're wondering what triggered this post, well twice this week have I been confronted with this near-pathological behaviour.

The first occasion was reading one colleague's analysis for a new logging system to better track changes at the record level. Obviously an important feature that should be done right, and in this case the idea was to extend the logging features currently present in the application - thumbs up in the reuse department. What struck me as odd about it, was that he didn't want to adopt the auditing system that was added to the underlying database system in a not too distant past. What really irked me about it, was that he didn't even mention it and didn't bother to express a good reason as to why we shouldn't use the built-in mechanism.

The second occasion was when a colleague started to explain how they solved a certain asynchronous data processing problem at his previous job, in what we can euphemistically call a 1980's solution: have an external process poll the database every minute. And he insisted that this was the only robust way to do it, and it worked fast because they had hundreds of these batch processes running on an IBM RS-6000. As the problem unfolded, he had to add more and more checks and balances to counteract concurrent modifications by different processes. When I suggested that for this particular situation a message queue might be more appropriate, he dismissed it as costly and overcomplicated. I don't know about you, but message queues are generally built by very smart people who have thought through the different corner cases, and I'll happily follow their path.

Naturally, as we have creative minds (and no, it's not because we express ourselves through code rather than music or painting that we shouldn't be considered "creative") we seek challenges and aim for the sky when we decide not to fix the code but rewrite it - paraphrasing Captain Jack Sparrow: "a bigger boat, a better boat, that boat." And it is extremely important to deliver something that we feel proud of, which is what drives us to work insane hours and then some more, just to get it done by this impossible deadline with more features than were in the requirements.

But aren't we sometimes overdoing it by completely ripping something apart and replacing it with an alternative that lives up to our current standards? None of us were born with programming experience, we all had to learn through "Hello, world!" in a dozen programming languages, and if all is right, we're still learning new things every day. Yet with an ever-growing to do-list and much longer to research-list, I prefer not to duplicate efforts. Which is why open source libraries, with the right licensing policy, are a great blessing.

Steering back to the topic, I feel this interview with Joshua Bloch is a must-read. Joshua Bloch is the author of Effective Java, considered by many to be among the best books on how to use the Java programming language. Here's the single-best quote from that interview: "In order to stay sane, most developers have a can-do attitude, and some take it too far. They say to themselves, 'Yes, there's a library, but I can do better.' Maybe you can, but that doesn't mean you should."

Mind you, when I recently rebuilt a monitoring tool, I did scrap nearly 90% of the existing code and replaced it with new code that made as much use as possible of new features added in recent versions of Java. So please do not read the above as a mindless "holier-than-thou" rant about short-sighted colleagues. What I really hope, is that you remember to keep an open mind, learn about what's waiting for you to use in your applications - either in the core of your development libraries or in what's available from the outside world. And if you do roll your own, at least make a list of the arguments pro and contra.

Service-Orientation vs. Object-Orientation

2008-07-31T10:27:00.000-07:00

What better way to fill an hour-long lunch-break than by reading up on various websites? Some people like to play cards and others take a stroll around the village. Lots of people leave breadcrumbs in their keybpoard as they read their private emails, but my daily ritual includes trips to MacWorld, MacUser, OreillyNet, Java.Net, JavaWorld and JavaLobby.

Today I bumped into this fresh post by Masoud Kalali on JavaLobby: Service-Orientation vs. Object-Orientation: Understanding the Impedance Mismatch. Even if your language of choice is Revolution and therefore not object-oriented (even if it's object-based, but we'll leave that for some other time) you'll still want to head over to the site and read the article. After all, a smart programmer keeps his horizons broad so he knows which is the right tool for a particular job, right?

Object-oriented programming has long established itself as a solid software development paradigm, improving on procedural programming by offering encaspulation, inheritance and polymorphism. Service-oriented architecture may still be surrounded by a lot of buzzwords,(often referred to as the SOA ALphabet Soup) but has clearly shown the way to seamless interoperability, regardless of development platform or operating system.

Both OOP and SOA promote reuse. And as more and more business models, developed using an object-oriented language like Java, need to expose their logic as services, it naturally becomes important to do it correctly: rather than just exposing all individually available procedures and functions as web services, you should take a step back and think very hard about exactly what services you seek to offer the outside world.

The innards of your system may be as tightly- or loosely-coupled as you prefer, the truth is that there's a lot of methods in your classes that you're only going to use internally. Services are better defined in terms of business processes, anyway: your 'order entry' service would be wise to offer both a high-level 'do it all in one go' service where an entire order can be created using a single XML structure that includes master and detail information, and a fine-grained 'do just one thing at a time' API to create/read/update/delete one part at a time.

So setting up your services becomes a matter of defining the sensible parts of a workflow, starting with a small area of your application and expanding as it makes sense, based on the feedback of the users of your services - which can be colleagues in the IT-department or external partners. In such an approach, services unsurprisingly have a lot in common with 'task oriented' user interfaces, where the user is guided through the different steps of the process - not in the sometimes belittling way of wizards, but as part of a way to empower the user by concentrating on his or her job.

Information Technology in general and software development in particular are in so many ways still in their infancy. And as we're growing up, we're relearning things from the past, re-inventing how combining existing and sometimes considered-obsolete technologies delivers new value and makes our applications more powerful while easier to use. It feels great to take part in all this...

Message in a Bottle

2008-07-22T11:56:00.000-07:00

Most people who have spent some time with me, are convinced that I am musically stuck in the eighties: The Cure, Siouxsie and the Banshees, The Sisters of Mercy and all those happy-sounding bands. But don't let the title of this post lead you to believe I'm talking about The Police. No, I'm talking about enterprise integration in the form of message queues.

In my last post, I talked about how interesting it would be if we could combine the easy-to-master power of cross-platform desktop software development tool Revolution with the heavy-weight champion in cross-platform development: Java. Well, the first way we can make these two technologies work together and play into one another's strengths, is by means of message queues.

Back in the old days, most application integration consisted of exchanging files: application A exported data into a file, and then application B would import the data from that file, usually at the click of two buttons. Convenient, even if you had to copy them to and from floppy disks. In the multi-user time-sharing Unix world, pipes have traditionally played an important role in data exchange, as one application connected its output pipe to the other application's input pipe and vice versa, and just wrote data to one another.

And of course, in the golden age of internetworked computers, you're bound to have enjoyed the miracles of TCP/IP and other networking protocols, as you surfed the web, exchanged instant messages and legally downloaded the occasional file. All thanks to the wonderful world of sockets that connected an application on your computer with an application running on another computer somewhere out there.

Sockets are also often used to let two applications talk to one another while running on the same computer - does the word 'localhost' ring a bell? The common theme in this type of information interchange is that both sides agree on the data format and talk to one another directly in one form or another. Now while that's pretty easy to put together as long as the two parties can come to an agreement, it gets complicated as you have to talk to more and more applications.

Think about it: if two apps talk to one another, you have one connection to develop; when a third app joins the party, two extra connections need to be made; a fourth app means adding three more to the mix. The mathematical formula is n x (n - 1) connections to interconnect n applications. And that's not such a strange scenario: nowadays, our applications can't sit there in their ivory towers - our users expect them to talk to one another seamlessly.

So, would you like to write an ever increasing number of connectors? Or would you prefer an approach that takes care of the plumbing? Enter message queues: think of them like a mass-mailing system for applications - you post a message to the queue and it will make sure that your message reaches all the applications that have declared their interest in receiving all or just certain types of messages. In this method, all you have to agree on is the message format and where it will be posted.

I'm sure you'll agree nothing is easier than speaking the same language and delegating the actual delivery of messages? Add to this the promise of delivering your messages to the applications that are hooked into the system - in order and exactly once! That's certainly a much better deal than people losing the USB-stick, deleting the email or forgetting to import those data exchange files, right? And how about this: when you change the data in one client application, you broadcast it via the message queue and all other clients pick up the message and refresh accordingly? Sounds good to me...

But enough theory, how can we do this in practice? The good news is that most Message Queue vendors have signed on to the Java Messaging System standard: JMS. Even better news is that in these days of open-source software development, we can pick up a solid implementation for free: Apache ActiveMQ - yes, from the makers of the server that's running most of the worldwide web. And the best news (not just for Revolution developers), is the STOMP project: a combination of a bridge and a standard protocol, which allows any socket-wielding application to talk to just about all JMS-enabled Message Queues.

You guessed it: the first way of combining Java and Revolution is using sockets to talk to a JMS-enabled Message Queue. Armed with the STOMP-specs and earlier experiments with socket communication, I put together a STOMP library in a few hours yesterday morning. Now don't rush over to the quartam.com website just yet, as it needs more testing and tweaking before it's ready for general use. But I can tell you that sending and receiving messages works like a treat. Yet another reason to add Revolution to your developer toolbox if you haven't done so already.

So where does the bottle come into this story? Well, I happily drank the rest of the bottle of dry white wine that I opened yesterday evening, while typing this post. Or maybe I was just trying to lure you in with the title of one of the most famous songs by The Police. Then again, wouldn't it be nice if all the messages we carefully wrote as a child at the beach, shoved in a coke bottle and threw into the sea, actually made it to their destinations?

More Items on my Bookshelf

2008-06-30T11:54:00.001-07:00

As a follow-up on my previous post, I have a confession to make. When I looked through my recent additions in Delicious Library, I realized that I had accidentally skipped one of my recent purchases. So in an effort to rectify that, here are some more items that recently found themselves added to my collection.

The item that I forgot to mention, was TCP/IP Sockets in Java. One of the tasks at my day-job is the maintenance of a monitoring service for diagnostics machines - also known as sample or specimen analyzers. The communication between our Laboratory Information System and these machines is of the utmost importance to our customers, and the laboratory staff need to be alerted when the analyzers fail to send their data because of a stalled translator service.
The monitoring system is basically divided in two parts: the service daemon which monitors communication, and the dashboard user interface that displays the status. Both of these are written in Java, enabling monitoring on multiple operating systems - the ubiquitous Windows workstations, as well as Mac, Linux, Solaris and other Unix-derivatives. The data exchange between these parts relies on multi-threaded socket communication, and that's why I bought this book, as I'm sure I'll need it when I go about rewriting portions of the engine to make it more scalable and alleviate the limitations that the current version is bumping into.

Which brings me to the next item on my bookshelf: Java Concurrency in Practice. As computers gain multiple cores and both operating systems and CPUs get ever smarter about dividing up the workload among the available resources, not to mention the fact that users don't like waiting around twiddling their thumbs while data is getting processed, it becomes more and more important to learn how to write multi-threaded applications.
Now Java was built from the start with multi-threading in mind. Over the years, the APIs have been improved, and Java 5 and Java 6 added classes that make concurrent programming a lot easier, shielding developers form the low-level plumbing needed to make it happen. And there's a lot more planned in Java 7 to help sorting and other tasks make better use of the processing powers offered by multi-core environments. This book gives you a lot better insight about the tricky little details of concurrency, explaining how processors, in an effort to maximize throughput, may shuffle instructions around in memory to optimize performance. If you're using Java and want to make optimal use of concurrency, this is a must-read.

The last item that I want to mention this time around, is Effective Java (2nd edition). Considered by many as the bible of properly using Java, this book was revised and updated for Java 6, exploring new design patterns and language idioms, showing the reader how to make the most of features ranging from generics to enums to annotations to autoboxing to (you guessed it) concurrency utilities.
As I'm spending more and more time with Java, I'm looking for a deeper understanding of the technology and the language, hoping to make my code clearer, more correct, more robust, and (fingers crossed) more reusable. Don't worry, I'm still using Revolution as often as I can - it's the language that I jump back to whenever I get a chance. It makes things so much easier and with the upcoming browser plug-in, I can avoid the un-fun of Java applets, AJAX, Flash and Silverlight.

But it is equally important to look around, learn from the available technologies and then pick the best tool for the job. Revolution is a wonderful solution for desktop applications that both need to look good and connect to databases and the internet. But when it comes to building highly-scalable multi-threaded applications, there's no replacement for Java. Ah, if only we could marry these two cross-platform technologies. Or maybe we can? That will have to wait for another post, however.

New Items on my Bookshelf

2008-06-23T11:43:00.000-07:00

One of the defining characteristics of Information Technology, is that it is constantly shifting, and that you need to spend a lot of time just to keep up with the topics that you focus on. Not to mention the pet projects that you hope you'll eventually get around to but have already bought some books on for that magical moment when have time to actually read them.

And maybe I should wait to buy these books until I have that copious free time needed to properly digest their contents, but hey, what better motivation to move things along than a growing stack of books that you convince yourself have to be read before the end of the summer? A little pressure never hurt anyone, right?

On with the show - what did I recently add to my collection?

The Definitive ANTLR Reference - if you've ever dreamt of building domain-specific languages, ANTLR is the tool to get if you're not already knee-deep in LEX and YACC. Now why on earth would you need that? Well, if you're building business applications, this sort of embedded scripting languages can make a world of difference when it comes to customizing the workflow of your application.

Granted, if your focus is exclusively on MacOS X, you're better off making your application OSA-scriptable, so that your users can interact with your application via AppleScript. Or go one step further, and embed Automator actions. But if you're not that lucky, and you need cross-platform scripting, ANTLR and the visual grammar development environment ANTLRWorks will make your life a heck of a lot easier - producing code that is actually readable, rather than the undecipherable state machine mess that you get from YACC.

And now that we're talking about MacOS X (ooh, there was a smooth transition to the next book) - I just got my copy of Cocoa Programming for MacOS X by Aaron Hillegass. The just-released third edition was updated for MacOS X Tiger and Leopard, including coverage of XCode 3, Objective-C 2, Core Data, the garbage collector and Core Animation.

While I also have a copy of the Wrox-book Beginning MacOS X Programming, this will be the one that gets me going with Cocoa (that's my story and I'm sticking to it!) as the last Mac-specific development I did was using Think Pascal and the first 5 books of the original Inside Mac series, back in the day when Macs used Motorola 680x0 processors and we were happy to get System 7.

The last book I want to mention is The Art of SQL. Now I may live and breathe databases but you can never learn enough tricks of the trade. In this book, the author aims to teach people who are no longer novices how to write good SQL code from the start and most importantly, to have a view of SQL code that goes beyond individual SQL statements.

Remember the days when developers managed to fit entire accounting applications, including the data, onto a set of floppy disks or (gasp, we will never fill that up) 10 megabyte hard disks, running in 128 kilobyte RAM or less? With the way database sizes are exploding nowadays, you need to plan ahead and employ a different strategy - so I'm definitely looking forward to getting more in-depth than ever.

And just in case you're wondering: no, I don't always cuddle up on the sofa with a mug of hot cocoa and this type of book. Whenever I get a chance, I'll read books by Raymond E. Feist, Tad Williams, David Eddings, Margaret Weis and Tracy Hickmann. Hmm, another stereotypical geek trait: fantasy and science fiction. Ah well, when the shoe fits :-)

UI Design Essentials

2008-05-25T12:23:00.001-07:00

My design skills are limited to stick figures - and even then, people will react "Is that a MacBook the guy is holding?" - "No, that's a chihuahua peeking out of her purse..." Nevertheless, as a commercial software developer, I need to somehow be both a programmer and a designer, at the same time.

And when you cater to the Mac market, you're talking about the platform where applications have to bleed coolness - often with ground-breaking user interfaces, like Delicious Library or Apple's iApps. Following the platform's interface guidelines is only half the work: your job is to provide an elegant user interface that conveys information in an efficient manner, interacting in a compelling way at the same level as your target user.

Granted, I make database front-ends for a living. The boring kind of applications: accounting, order processing, and all that happy fun stuff that involves storing data in and loading it back from a database, and providing reports and statistics so that the end users can do their job. In my time, I have seen plenty of applications that were built from a developers' point of view. Which means it's logical, in a way, though not necessarily matching the user's line of thinking.

If you're lucky, the team that built the thing in the first place, took the time to read up on human-computer interaction, and tried to learn from the other applications out there. And if you're really lucky, they had someone on their team smart enough to say: "It's not enough to have menus and windows and buttons, but we should make sure that all elements in our application work consistently, as this will cut down on user training and support calls."

But I didn't mean to step onto the soapbox here - I just wanted to point you over to this entry on the Theocacao website - a blog for Mac developers, written by Scott Stevenson, who also maintains the Cocoa Dev Central learning center. You can fetch the slides of his UI Design Essentials talk as well as a movie recording. It may take a while to download the 532MB QuickTime HD file, but it is well worth it.

He talks about the history of developers and designers in software development, and although he can't make you a designer in as short a timeframe as an hour, he does make excellent points and offers practical advice. Specific topics touched include: the basics of iterative design and usability testing, the use of whitespace and partitioning, correct labels and prompts, as well as fonts and language design, covering inspector palettes and icons in the process.

He also ran through a real application that someone was brave enough to submit, pointing out design flaws that turn this functionally excellent application into something users can get to work by themselves, but could be so much better and easier to use by making a number of tweaks. In the wrap-up, he mentions a number of 'model citizens' that we should look at. Some of the best bits came up during the Q&A session at the end, which is only available in the video recording, unfortunately.

As you wait for the download to make its way to your computer, you may also want to chase down these books:

Designing Interfaces by Jenifer Tidwell (O'Reilly)
About Face 3 by Alan Cooper, Robert Reimann and David Cronin (Wiley)

While the latter is a very theoretical book which goes through great lengths to match up the implementation and mental models of developers and users respectively, the first book has great tips on how to improve the user interface of your desktop as well as web applications, filled with screenshots and explanations in a very readable format.

Of course, there are other resources out there, but I'm not going to add much more to this post - instead, I would like to encourage you to go out and look at applications that you use every day, and write down what you find annoying and what you like about the way it interacts with you as a user. And the n try to repeat what thery do right, and avoid what they do wrong.

While Quartam Reports works the way it does, as it was modeled after the Report Builder that shipped with Foxpro, it's not going to stay that way forever. I've already been prototyping a complete overhaul for a while now, and hope to make it a reality for version 2.0 - balancing between the "let's just get it over with" mindset of a developer who has to develop 189 of those pesky things, and the mindset of someone who is perhaps less-seasoned in the raw developing process, but has a good idea of the end-product and how it should turn mere facts into empowering information.

In the meantime, there's plenty to learn and consider and tweak, as usual... Not to mention plenty of code to toss and rewrite... It just never ends, does it?

Revolution Live '08 - redefining the web

2008-05-14T11:26:00.000-07:00

Now that I'm back home, caught up on sleep a bit and am starting the happy-fun return of my internal body clock to the Central European Time Zone, it seemed like a good opportunity to blog about the announcements at the Revolution Live Conference.

The great news for Revolution customers around the globe, is that their web offerings are shaping up really well: a PHP-style server module for creating web applications, plus a web browser plug-in - talk about a slam-dunk by the Runrev team!

This is the perfect answer to Adobe's trying to bring Flash to the desktop: anyone can now build Internet-enabled applications without having to struggle with ActionScript and tools that were meant for designers. Not that designers are illogical people - if they were clueless about putting two and two together, they wouldn't be able to pull off that AJAX stuff.

Boy, am I glad I won't have to continue struggling with that HTML+CSS+JavaScript batter mix either, if I want to build a Rich Internet Application... Let's check how Revolution stacks up against all these technologies that are trying to win the next round of browser wars:

AJAX is an interesting use of existing technologies, but in the end it's just another way to stretch what a browser can do. The fact of the matter is: the browser needs updating for it to ever become a true universal application platform.
Flash started life as a way to animate vector graphics, and whatever people may tell you, that's still what it is - they don't even have real buttons, it's all simulated. Thank you, please don't come again.
JavaFX is an interesting idea, but suffers from one major flaw: it is not Java. Which means that Java developers have to learn a whole new thing just to be with the times. If they really wanted it to become popular, they would have just provided a great applet builder, not this monstrosity.
Silverlight is Microsoft's attempt to beat Adobe in the browser plug-in wars. So far, it doesn't really seem to be getting very far. Maybe around version 3.0 we can consider it a major force, but I'm sure that you'll have to update your Silverlight apps every single time the Redmond team decides to replace essential parts.

Some people may think that Revolution is focusing entirely on the multimedia market with this strategy, but they couldn't be further from the truth: this is the single largest opportunity in the history of Revolution to make it big in the world of Enterprise applications!

Of course, there will be plenty of multimedia Flash-like stuff built using this browser plug-in, and it should attract a whole new crowd of Revolution developers. But looking at the biz app developers now, Revolution is by far the most secure technology of the bunch: short of obfuscating your Javascript, your AJAX apps are wide-open for anyone to take apart and try to take advantage of.

The Revolution community can now deploy applications for those customers who want to see a browser user interface, and we won't even have to learn a new language. Likewise, the server module will serve as an application server gateway like we haven't had before.

And I can assure you that existing and future Quartam tools will help you get to the bottom of things: use the server module and Quartam PDF Library to dynamically generate documents for your web applications; and once Quartam Reports hits version 2.0, you'll be able to leverage this report generation tool on the browser platform as well.

Good times...

Website make-over

2008-05-04T05:03:00.000-07:00

After about 4 years of a design that was clean but not very modern, I decided to sit down and give my site a complete make-over. I had a pretty good idea of what I wanted it to look like, and in my hubris estimated I could do it in a day or two.

The original website design was done using Claris Home Page, a dinosaur even in the day that I picked it in 2004 as my tool for table-based layouting. But for the rather simple site I had in mind, it was the logical choice, given that I had last designed a website back in 1994, in the days when HoTMetaL Pro was considered a major step forwards.

My mindset is that of a developer, not a designer. Which means that I'm pretty good at straightforward HTML, and I can work with XML and the gory details of XSL transformations. But for some reason, my brain comes to a grinding halt when it is confronted with CSS. So I generally let the designer "do his thang" and integrate it with my XSLT file or AJAX routine. Which I write in a programmer's text editor, not some fancy tool like Dreamweaver.

However, for my own website I was going to get it right - and of course, it resulted in a lot of expletives and crying and pleading with every deity that could remotely help - not that I really expected the ancient Roman goddess of wisdom, Minerva, to be any good at CSS, but hey, it would have been cool if she had swooped by and fixed the problems - and I was getting desparate at that point.

Until I decided to put away my programmer's hat, and dug out my copy of Freeway Pro, which I had recently upgraded to version 5 anyway. Created by Softpress, it is aimed at visual designers who like working with Quark XPress, drawing graphic elements and filling them with content.

A long long time ago, in a galaxy far away, I was active in various student associations, where I invariably ended up layouting the association's magazine using PageMaker or RagTime. So after a lot of experimenting, unlearning and documentation-consulting, in these past four (*) days, I managed to completely revamp the quartam.com website.

The result is CSS-based, and my website no longer looks like something designed in the 20th century. There's one more section to redo as far as layout goes, and I still have to wrap up those elusive tutorials that I started back in 2006 - I'll let you know when those eggs hatch. Right now, I have to get back to preparing for runrevlive.08 - where I will be presenting the session on Advanced Databases.

(*) Four days, whereas I had planned two days. Great - just great. If my boss reads this, I'm sure he'll have a field day - according to him, you need to multiply a developer's time estimate by 2 and then you may get a more realistic timeframe. Don't you just hate it when the manager is right? Then again, he worked his way up from the coding trenches - which means he has a much better idea about software development than, say, a former bank director pretending to be a CEO in IT...

Thinking of an opening line

2008-04-04T12:04:00.000-07:00

Starting a blog is like trying to convince a girl that there's more to you than a pair of glasses, some ruffled brown hair and a strange grin. What exactly are you supposed to say?

Let's start with explaining what I hope to do here. There are lots of corporate blogs that are either filled by the managers, or their secretary copywriters. The good new for you, is that I am neither a manager, nor a secretary.

During the day I am a software engineer at MIPS Belgium - a leading provider of laboratory information management systems. At the job, I use a mixture of Progress OpenEdge, Java and -to a lesser extent- C/C++.

After hours, I use Revolution - one of the best-kept secrets in software development, it allows anyone with the gift of reason to quickly create an application by dragging buttons and fields onto a card and adding scripts to them. In an easy to understand English-like syntax, not some mystifying combination of dot-notation and enforced object-orientation.

My plan for this blog is to talk about the technology that I work with - the tools that I build and sell to fellow developers, little bits of code that I write to test a feature or just to satisfy my curiosity, but also the books that I read and try to glean information out of that will help me in my daily occupations.

Don't expect multiple posts per day - given my hectic schedule, it is bound to be more or less a once-a-week affair. But then again, I may enjoy writing entries that I will do it more often. You'll just have to wait and see...