Issue 79 * October 1 2009

The State of the Window
Some handy things you didn't know you could set for Mac Window States

by Shao Sean

Revolution is a great cross-platform development environment that makes writing software very easy with its English-like syntax, but like most cross-platform environments it has to omit some of the platform specific options to remain consistent on all platforms. We are going to look at a couple of Mac OS X features and see how to add them to your Revolution applications using the "ssMacWindows" external.

First Things First - Getting the External

The external can be downloaded here and can be used free of charge in the IDE and for personal use software (see the Read Me file for more information about licensing).

Unless you have changed the location of the User Extensions in Revolution's preferences you can place the external into the folder:

~/Documents/My Revolution Enterprise/Externals/
~/Documents/My Revolution Studio/Externals/

If you had Revolution running, you will need to restart it to get the external loaded into Revolution. Now we can move on to the fun stuff.

The State of the Document

One nice thing about Mac OS X document windows is they give you information about the current state of the document - is it saved, has it been modified and what kind of document. Where do you find all that information really quickly and easily? The document's title bar.

The State of the Document - Has it Been Modified?

Go open TextEdit and take a look at the title bar. Pretty plain, just the three buttons and the title of the document. Create a new stack in Revolution and you get pretty much the same thing.

Type something in TextEdit and notice that the close button now has a black dot in the center of it letting us know that the document has been modified. Add a field to your Revolution window, notice the lack of a dot - lets fix this!

Go into Revolution and edit the script of that field and put in the following code:

on keyUp
   setWindowModified the windowID of this stack, 1
end keyUp 

Now go type something into the field and watch as we get the black dot in the close button.

Back to TextEdit to save the document and notice that the dot is now gone from the close button, we will need to do the same thing in our Revolution document.

Edit the card script and add the following code:

on saveStackRequest
   setWindowModified the windowID of this stack, 0
   pass saveStackRequest
end saveStackRequest 

Save the stack and watch as the black dot disappears too.

So we have now managed to let the user know if there has been any changes made to the documents of your Revolution application.

As a developer you may need a way to tell if the document has been changed from code so you can just quickly check with the following code:

isWindowModified(the windowID of this stack) 

Example:

on closeStackRequest
   if (isWindowModified(the windowID of this stack)) then
      -- document modified so perhaps saving it
   else
      -- document unmodified so we can just close it
   end if
   pass closeStackRequest
end closeStackRequest

The State of the Document - Has it Been Saved?

Now that we know if the document has been modified or not lets handle seeing if the document has ever been saved.

Back to TextEdit and you will notice that the document we saved earlier has an icon (this is known as a proxy icon) next to the document title. Open a new document and you will see that it does not have a proxy icon. Until a document is saved to disk we do not know what kind of document it is (TextEdit has multiple file types - html, rtf, text).

Back to Revolution and our sample stack. Save it and we have no proxy icon so lets add one. We will modify our existing card script to the following:

on saveStackRequest
   setWindowModified the windowID of this stack, 0
   send "addProxyIcon" to me in 1 millisecond
   pass saveStackRequest
end saveStackRequest

command addProxyIcon
   setWindowProxyIcon the windowID of this stack, \
          the filename of this stack
end addProxyIcon 

Now when we save the stack it will get a proxy icon. The proxy icon will also dim when the document has been modified (type in your field again to see it in action).

We use the send command to allow Revolution time to save the stack and to actually have a file name to use with the external command "setWindowProxyIcon".

The State of the Document - What Kind of Document?

The proxy icon shows a generic icon for the type of file so you can easily have your own document icons and set the fileType of your stack to get the proper proxy icon. If you have written a picture viewer program you can just pass the absolute path to the picture you are viewing to get the proper proxy icon as well.

Well that seems like a few useful features, so we decided to add in a few more useful features that had nothing to with the title bar just for good measure.

If your application requires that all your windows are brought to the front whenever your application is brought forward just use the external command:

bringAllApplicationWindowsForward 

and watch as all your application windows are brought forward.

Palettes are a nice way to have a window of quickly accessible items at hand without having to clutter up your docment window, but if you are using a wide and short palette having the title bar on the top can add a lot of wasted pixel space so lets move it to the left side of the window.

windowSetTitleBarOnSide the windowID of this stack, 1 

Hope you enjoyed this first newsletter article of mine and my first Mac OS X external as much as I enjoyed writing both of them. Here is a quick summary of the external commands and functions.

setWindowModified windowID, 1|0 -- 1 = modified, 0 = unmodified
isWindowModified(windowID) -- returns True or False
setWindowProxyIcon windowID, absoluteFilePath
windowSetTitleBarOnSide windowID, 1|0 -- 1 = left side, 0 = top
bringAllApplicationWindowsForward

windowSetTitleBarOnSide only works on palette windows.

About the Author

Shao Sean is the creator of the Revolution driven website RevDevelop.com and a long time Rev user.

Main Menu

What's New

Quartam Reports