Apple Script
The applescript classes that come with the WTextView wrapper are a complete rewrite of the CWASTEEdit apple script classes. The design of the classes is different, the code is more robust, but the overall interaction with the WASTE PPlant view (in this case WTextView) is very similar.
Changes
In CWASTEEdit, apple script support was a subclass of CWASTEEdit that also inherited from LModelObject. In the new wrapper, WTextView keeps a pointer to a text model object, mTextModel. There is no subclass of WTextView that implements Apple Script. If this pointer is filled by the controller for WTextView, then WTextView will pass along appropriate calls to the Apple Script implementation. If the pointer is nil (no Apple Script is desired), the WASTE engine is called directly.
Why is this better?
This approach has several advantages. Using a pointer inside WTextView allows the text model implementation WTextModel to be a hierarchy of classes instead of a series of very similar classes that implement the same behavior. Compare the inheritance tree for WTextModel (the new class) to that of CAEText (the implementation that came with CWASTEEdit).
Figure 1. WTextModel inheritance
Figure 2. CAEText inheritance
All the text model classes from CWASTEEdit inherit from LModelObject and are unrelated, while the WTextModel tree is self contained and makes better use of inheritance. This advantage really shows itself in increased code reuse and decreased complexity of the subclasses of WTextModel. This code should be much easier to use and maintain.
It is possible to make the text model support dynamic by changing the pointer if the programmer really wants to. Also, WTextView is more flexible and can be used in more places since the extra apple script code doesn't have to be carried along.
Starting with version 1.0.0a2 the WTextModel subclasses are simplified and take advantage of inheritance more. Much of the work is handled by WTextModel and the subclasses only make modification where necessary.
If you really want to learn the guts of how this implementation works, read the code in WTextModel. It is heavily commented and hopefully easy to understand.
The Implementation
In this section I, Timothy Paustian, list a few things specific to WTextModel's AppleScript implementation. If you want to learn about the standard objects, verbs, and properties supported by WTextModel, open up it's AppleScript dictionary in ScriptEditor or another script writing application, such as UserLand's Frontier. My main goal was to implement basic things that any text processing application would want to do. I will warn you that the implementation is somewhat incomplete. The major omission is whose clause support. I may throw that in to a future release.
If you want to check out the example application using Frontier, download the Frontier application from the Frontier site. There is a free demo version and a commercial version. Frontier is great software and I recommend it to anyone doing web sites. Double click on newWaste.Frontier located in the output folder for the WText Demo Application. This will install install the verb table and shared menu for the WText Demo and allow you to write scripts on Frontier that control the Demo. Have fun!
Core (Standard) Suite
WTextModel supports the close, data size, get, make, open, print, save and set events in the standard suite. The application, document and window objects are included in the suite and it is possible to retrieve and set many of the properties of these objects.
Miscellaneous Suite
Revert, cut, copy and paste are supported here. In the case of WTextModel, the revert event is understood by a document object, while the other events refer to the selection object of the document in question. Cut and copy will return an error if there is no selection.
WTextModel's Text Suite
The text suite in WTextModel is the standard text suite used in many word processors. This suite does not define any more events, but adds to the types of objects that can be manipulated by the other suites. It is possible to refer to the text as characters, words, lines, and paragraphs. You can also refer to ranges of text objects such as, words 1 thru 57. There are some specific things about WTextModel's text model that are worth mentioning
Paragraphs
A paragraph is defined as a a return character. Each of these may be preceded by any number of characters. A single return with no characters in front of it is still thought of as a paragraph.Lines
A line is the text contained on one line of a window. If word wrap is on for you view, the text wraps to fit the window, and the contents, location, and size of each line will change if the window size is changed. In these situations, the script author should carefully consider the use of line objects in scripts. Paragraphs, words and characters are often more robust objects when scripting WTextModel.
Words
The definition of a word is world script compatible and depends upon the script being used. The definition of a word is ultimately dependent upon the toolbox call FindWordBreaks. See WWordLooper and WEFindWord to look at the gory details.
Characters
A character is a single letter, space, or return in the text. Two byte characters are supported.
WTextModel is now world script aware and hopefully will work with non-Roman languages.
AppleScript Demonstration
The best way to learn about the power of AppleScript is to try out a few scripts. I have included a demo script that will clean up a document and change some of its formatting characteristics.
- Start up WText Demo and close the untitled window that comes up.
- Navigate to the demo script folder and open the file Demo Script. The Script Editor application should open. In the Demo Script window click the run button.
- A dialog box will appear, asking you to open a file to be processed. Find the file The Bill of Rights, it should be located in the same folder as the Demo Script.
- Sit back and watch the show.
- After it's finished take a look at the script. Some things to note
- Paragraphs, lines, words and characters can be referred to by numeric index and by relative index
Numeric: set style of paragraph 1 to bold Relative: set thisLine to last character of line i
- The text has many properties. Ones used in the script include, color, font, and size.
- The count of lines changes as you go through the script and the script must take note of this. A frequent gotcha. Watch out for this one.
- Paragraphs, lines, words and characters can be referred to by numeric index and by relative index
WTextModel is also recordable.
Open up a new window in Script Editor and hit the record button
Switch to WTextModel and start changing properties of the text and window.
When finished, switch back to Script Editor and examine what was recorded.
As always if you have questions or comments, send them to Timothy Paustian or David Phillip Oster. Add AppleScript to your WASTE application. It's easy and useful in many cases. I hope this example application will make it even easier and don't forget to support Frontier.
Frontier Support in the WASTE example
I was blow away by a Great application called Frontier. To help further the cause for Frontier, menu sharing support has been added to the example application. If you make your application scriptable, Add menu sharing! You are already well on your way with the example application, so you have no excuse!
To learn more about menu sharing, go to the Frontier web site and look at the SDKs for Frontier. I will be happy to give help and advice to anyone who wants to add menu sharing to their Power Plant app. To get people started, below I give a step by step on how to add menu sharing.
First, make your application scriptable. Remember to have a rich verb set. You are welcome to start with the set that I have defined for the example application. This can do many things.
Good, your app is scriptable. Now comes the easy part. Include the files in the FrontierSupport folder in your project. Frontier is implemented as an attachment to the main event loop, as suggested by UserLand.
Add the following code to your project. This should go in the constructor of your application object.
CFrontierMenuHandler *frontierAttach = nil; frontierAttach = new CFrontierMenuHandler(resFrontierMenuID); ValidateObject_(frontierAttach); AddAttachment(frontierAttach);
This code initializes the Frontier menu handling routines. The constructor passes a number that corresponds to the first menu item number Frontier can use without conflicting with menus you have defined. UserLand suggests this number be kept under 255, so that hierarchical menus are possible. (The menu manager requires that hierarchical menus be below 255.) All the details are handled by CFrontierMenuHandler. In the constructor, InitSharedMenus passes two parameters. The first is the name of a function (ErrorDialog) that Frontier uses to communicate script errors with a user of your app. The second is a routine that will dispatch events sent to your application from Frontier. These are useful for updating windows, activating the application and other things, during the execution of a script. Both of these routines are defined in CFrontierMenuHandler.
I have made some changes to CFrontierMenuHandler with this release. It is now more responsive to the presence of Frontier and also handles more of the Frontier chores for you. Check out the code.
That's all the necessary modifications to your application. (The proverbial 4 lines of code!). I recently made some modifications to CFrontierMenuHandler so that it is more responsive and handles the cmd-. instance also.
To get shared menus to work well, you need to created a verb table, glue scripts, and a shared menu for your application in Frontier. Due to the power of Frontier, this is easy.
Start up frontier after you have downloaded it from the Frontier site.
Choose, Suites->Commercial Developers. A new Glue menu will be installed in the menu bar.
Choose, Glue->Enter Your Apps Name.... You will be asked your applications name. Type it in and hit return. You will then be asked if you want to create a glue script table, say yes.
Say yes to creating an appInfo table. When asked whether you application supports menu sharing, say yes. You will then be asked to locate your application.
Finally, when asked whether to import the 'aete' resource into the verb table, say yes. Frontier will then compile a verb table based upon your 'aete' resource.
That is it. Your application should now support menu sharing. Start up your application and Frontier. If you have trouble, try quitting both apps and launching them again. If things are still whacky, check out the docs on the Frontier site.
Note, with the recent releases of Frontier 4.2 and greater, creating a install object for your application using the commercial developers suite really doesn't work. My advice is to roll your own custom install files.