TweetFollow Us on Twitter

March 96 - According to Script: Properties and Preferences

ACCORDING TO SCRIPT: Properties and Preferences

Cal Simone

On the way to implementing scripting support in your applications, you're bound to confront a variety of issues. In this column, I'll give you some pointers for devising and testing property names and discuss the techniques for handling preferences through scripting.

PROPERTIES

In an application's scripting vocabulary, a property is an attribute of an object. Properties can replace variables in if and repeat statements, as well as in expressions, and a script writer normally uses the AppleScript verbs set and get with them. Here I'll give some guidelines for coming up with human-language names for properties and testing the viability of those names within the overall natural style of the AppleScript language. It's important that properties have names that users can easily become familiar with. Ideally, users should be able to refer to properties in a script the way they think or speak about them.

Don't start property names with verbs. Starting property names with verbs leads to confusion when the property appears in the middle of a sentence. For example, naming a property disable call waiting leads to commands that don't read smoothly:

set disable call waiting to true 
if disable call waiting then ... 
This is somewhat clearer:
set call waiting enabled to false
if not call waiting enabled ... 
In fact, in the above case, it would be even better to name the property call waiting and use an enumeration as its value type (for a discussion of enumerations, see my article "Designing a Scripting Implementation" in develop Issue 21). The choices enabled and disabled allow grammatically correct sentences, as in the following:
set call waiting to enabled
if call waiting is disabled ... 
A little creative thinking goes a long way in making it easy for users to work with the language.

The "the" test. AppleScript allows you to add or remove the word the almost anywhere in a script without changing the meaning of the script. Many script writers precede object and property names with the word the to make their scripts easier to read. Writing your test scripts in this way helps you determine the degree to which your property names facilitate forming natural sentences.

set the service to "America Online"
if the priority is high then ...

Don't confuse attributes and actions. Sometimes setting a property can cause an immediate change on the screen. In deciding whether to use a property in this situation, a helpful rule is: When an action is initiated, use a verb; when an attribute changes (even if it produces immediate visible results), use a property. Another way of looking at this is if a visible change is immediate, it's OK to use a property, but if an action has a duration, use a verb.

As an example, the following command causes an immediate change on the screen:

set the font of the third paragraph to "Courier"
Even though setting the font property creates a visible change, the font is still an attribute of the text, not an action. On the other hand, naming a property or enumerator playing, as shown in the next two commands, is a poor choice, because playing actually initiates an action:
set playing to true   
set [the] status to playing   
The playing enumerator value in the second command is fine for obtaining state information, but a status property should be read-only. Instead of creating a property to control an action, use a verb. Verbs such as play or start playing are better suited for actions, as shown here:
play the movie "Wowie Zowie"
start playing the movie "Wowie Zowie"
Note that the commands are play and start playing, not play movie or start playing movie. In an application based on the object model, movie would be an object class.

The properties property. A properties property enables script writers to obtain all the properties for a given object in the form of a record by using a get properties construct. (I first suggested using records in this column in develop Issue 22.) The properties property can also be set with the set command. The sample properties property shown in Listing 1 can be included as a property of any object for which you allow the setting of more than one property at a time.

Listing 1. A sample properties property

{   /* array Properties: 5 elements */
   /* [5] */
   "properties",
   'Prop',
   'reco',
   "Property that allows setting of a list
      of properties.",
   reserved, singleItem, notEnumerated,
   readWrite, reserved,
   ...
},
Don't require the user to supply all the properties when setting the properties property -- allow the setting of just one or a few properties.

get the properties of the fourth paragraph 
   -- returns font, size, style, and so on
set the properties of the fourth paragraph to ~
   {font:"Helvetica", size:14} 

PREFERENCES

Developers use a variety of techniques to allow users to set preferences through scripts. I'll describe three common and easily implemented approaches for dealing with preference properties in your application class. (These same approaches can be used to implement document settings or group properties for individual objects within your application.)

Separate properties for each preference. Implementing preferences as individual properties works well when you have only a few preferences. For example:

set the connect sound to "Shriek"
set the receive folder to alias "HD:Drop Folder"
If you have many preferences, it's inefficient for the user to have to set each property individually. To solve this, you can implement your preferences as individual properties (usually in your vocabulary's application class definition) and also include a preferences property, described next.

A property that includes all the preferences. You can make a single preferences or settings property, which is a record that's defined elsewhere in your vocabulary. To define the elements of the record, create a fake "class" in your vocabulary, preferably in your Type Definitions Suite, to serve as the definition of the element labels in a record definition. In the comment field for your "class," be sure to document clearly that this is a record definition, not an object class. Listing 2 illustrates this technique; for more information, see the section "Define Record Labels in a Record Definition" in "Designing a Scripting Implementation" in develop Issue 21.

Listing 2. A sample preferences property

/* First, define this application property. */
{   /* array Properties: 5 elements */
   /* [5] */
   "preferences",
   'Pref',   
   'cprf,      /* for "preferences class" */
   "Property that allows setting some or all
      of your preferences.",
   reserved, singleItem, notEnumerated,
   readWrite, reserved,
   ...      /* more reserved items */
},
... /* more property definitions */

/* Later, in your Type Definitions Suite, */
/* create a fake class. */
{   /* array Classes: 1 element */
/* [1] */
"preferences record",
'cprf',
"A record containing individual preferences",
{   /* array Properties: 10 elements */
   /* [1] */
   "connect sound", 'CSND', 'itxt',
   "the name of the sound to use when
      connected",
   reserved, singleItem, notEnumerated,
   ...
   /* [2] */
   "receive folder", 'RFLD', 'alis',
   "the folder to place files when received",
   reserved, singleItem, notEnumerated,
   ...
},
{   /* array Elements: 0 elements */
}
Lists and records are the two principal constructs in AppleScript that don't lend themselves to human sentence structure. They are, however, an integral part of the language and can occasionally help to make the script writer's life easier. When you use a record to create a preferences property, it's OK to stray a little from strict natural-language style. Of course, when referring to elements of a list or record, you should use natural-language style.

As with the properties property described earlier, don't require the user to set all the individual preferences at once. Allow the setting of just one or a few preferences at a time:

set the preferences to ~
   {connect sound:"Shriek", ~
    receive folder:alias "HD:Drop folder"}
A user can address individual preferences as if they were defined as separate application properties. To allow for varying user experience with AppleScript, your application should always accept property specifications for individual preferences using the technique described above, regardless of whether the user includes the qualifying phrase of the preferences. For example, both of the following statements should be allowed:
set the receive folder of the preferences to ~
   alias "HD:Drop Folder"
set the receive folder to alias "HD:Drop Folder"

Multiple "group" properties for grouping preferences. If you have many preferences or want to group the preferences according to similar functionality, such as those often found in multipaneled dialog boxes, you can create separate properties for groups of preferences or settings (using the record definition technique just described). The properties can reflect the groupings you've set up in your graphical interface:

set the compiler preferences to ~
   {warnings included:true, ~
   default integer size:short integer}

set the drawing settings to ~
   {pen size:{1,2}, shape:circle}
A user addresses an individual preference by including in the object property specification the record that the preference is an element of, as follows:
the pen size of the drawing settings
set the shape of the drawing settings to ~
   rectangle
set the default integer size of the compiler ~
   preferences to short integer

PARTING WORDS

Following these guidelines in implementing scriptability in your applications makes it easier for users to write scripts. Although they may seem like small points, it's the details that mean the difference between frustration and smooth sailing for the script writer. Remember to think about the way a user would write or speak about accomplishing what they want to do. Until next time, I remain your obedient servant on the AppleScript front. I'll see you on applescript-implementors@abs.apple.com, the mailing list for scriptability.

CAL SIMONE (AppleLink MAIN.EVENT, Internet mainevent@his.com) wants your dictionary for the Webster database, which will be used to help resolve human-name conflicts between different applications and scripting additions. He'll be analyzing the terms in your vocabulary against others in search of similarities and differences. Send your 'aete' resources to Cal via AppleLink or the Internet.*

Thanks to Eric Gundrum, Jon Pugh, and Derrick Schneider for reviewing this column.*

 

Community Search:
MacTech Search:

Software Updates via MacUpdate

Things 2.5.4 - Elegant personal task man...
Things is a task management solution that helps to organize your tasks in an elegant and intuitive way. Things combines powerful features with simplicity through the use of tags and its intelligent... Read more
NeoOffice 2014.10 - Mac-tailored, OpenOf...
NeoOffice is a complete office suite for OS X. With NeoOffice, users can view, edit, and save OpenOffice documents, PDF files, and most Microsoft Word, Excel, and PowerPoint documents. NeoOffice 3.x... Read more
iPhoto Library Manager 4.2 - Manage mult...
iPhoto Library Manager allows you to organize your photos among multiple iPhoto libraries, rather than having to store all of your photos in one giant library. You can browse the photos in all your... Read more
Web Snapper 3.3.8 - Capture entire Web p...
Web Snapper lets you capture Web pages exactly as they appear in your browser. You can send them to a file as images or vector-based, multi-page PDFs. It captures the whole Web page - eliminating the... Read more
TeamViewer 10.0.41404 - Establish remote...
TeamViewer gives you remote control of any computer or Mac over the Internet within seconds, or can be used for online meetings. Find out why more than 200 million users trust TeamViewer! Free for... Read more
Ableton Live 9.1.8 - Record music using...
Ableton Live lets you create and record music on your Mac. Use digital instruments, pre-recorded sounds, and sampled loops to arrange, produce, and perform your music like never before. Ableton Live... Read more
VOX 2.5 - Music player that supports man...
VOX is a beautiful music player that supports many filetypes. The beauty is in its simplicity, yet behind the minimal exterior lies a powerful music player with a ton of features & support for... Read more
OmniFocus 2.1.2 - GTD task manager with...
OmniFocus helps you manage your tasks the way that you want, freeing you to focus your attention on the things that matter to you most. Capturing tasks and ideas is always a keyboard shortcut away in... Read more
Adobe Flash Player 17.0.0.169 - Plug-in...
Adobe Flash Player is a cross-platform, browser-based application runtime that provides uncompromised viewing of expressive applications, content, and videos across browsers and operating systems.... Read more
iMazing 1.1.3 - Complete iOS device mana...
iMazing (was DiskAid) is the ultimate iOS device manager with capabilities far beyond what iTunes offers. With iMazing and your iOS device (iPhone, iPad, or iPod), you can: Copy music to and from... Read more

Chainsaw Warrior: Lords of the Night has...
It's time to put the Darkness back in its place now that Chainsaw Warrior: Lords of the Night has officially made it to iOS. | Read more »
A World of Ice and Fire Lets You Stalk 2...
George R. R. Martin’s A World of Ice and Fire, by Random House, is a mobile guide to the epic series. The new update gives you the Journeys map feture that will let you track the movements of 25 different characters. But don't worry, you can protect... | Read more »
Gameloft Announces Battle Odyssey, a New...
Battle Odyssey, Gameloft's newest puzzle RPG, is coming to the App Store next week. Set in the world of Pondera, you will need to control the power of the elements to defend the world from evil. You'll be able to entlist over 500 allies to aid you... | Read more »
Fusion - HDR Camera (Photography)
Fusion - HDR Camera 1.0.0 Device: iOS Universal Category: Photography Price: $1.99, Version: 1.0.0 (iTunes) Description: Fusion creates HDR (high dynamic range) photos by capturing different exposures and then combining them into one... | Read more »
Sago Mini Toolbox (Education)
Sago Mini Toolbox 1.1 Device: iOS Universal Category: Education Price: $2.99, Version: 1.1 (iTunes) Description: Come build with the Sago Mini friends! Use a wrench, try a saw, or hammer some nails. From sewing hand puppets to... | Read more »
You Should Probably Grab Hitman GO While...
Hitman GO is a surprisingly cool (yet also incredibly drastic) departure from the Hitman series. It's well worth playing for any puzzle game fans out there, and at the moment you can get your hands - or garrotte if you will - on it for a mere $0.99... | Read more »
IFTTT is Bringing Do Button and Do Note...
IFTTT has announced Do Button and Do Note for the Apple Watch. Do Button lets you make your own personalized button that can connect to things like your Google Drive, control the temperature in your home with Nest Thermostat, or turn the lights on... | Read more »
How Many Days, Hours, and Minutes Are Le...
Countdown, by Yves Tscherry, is now available on the App Store. The app keeps track of countdowns to your favorite things such as someones birthday or days till the New Year. You can display the time in seconds, minutes, hours, days, weeks, months,... | Read more »
The All-New Misfit 2.0 App is Available...
Misfit has just given their app a complete overhaul. Misfit 2.0 now has a brand new interface with a sleek design and is easier to navigate. You'll be able to sync your Misfit device and look up health and fitness information faster than ever before... | Read more »
Halo: Spartan Strike (Games)
Halo: Spartan Strike 1.0 Device: iOS Universal Category: Games Price: $5.99, Version: 1.0 (iTunes) Description: Delve into 30 challenging missions through cities and jungles using a devastating arsenal of weapons, abilities and... | Read more »

Price Scanner via MacPrices.net

Clearance 13-inch 2.6GHz Retina MacBook Pro a...
B&H Photo has clearance 2014 13″ 2.6GHz/128GB Retina MacBook Pros now available for $1099, or $200 off original MSRP. Shipping is free, and B&H charges NY sales tax only. Read more
Apple refurbished 2014 13-inch Retina MacBook...
The Apple Store has Apple Certified Refurbished 2014 13″ Retina MacBook Pros available for up to $400 off original MSRP, starting at $979. An Apple one-year warranty is included with each model, and... Read more
iMacs on sale for up to $205 off MSRP, NY tax...
B&H Photo has 21″ and 27″ iMacs on sale for up to $205 off MSRP including free shipping plus NY sales tax only: - 21″ 1.4GHz iMac: $1019 $80 off - 21″ 2.7GHz iMac: $1189 $110 off - 21″ 2.9GHz... Read more
Sale! 16GB iPhone 5S for $1 with service
Best Buy is offering 16GB iPhone 5Ss for $1.00 with 2-year activation at a participating cellular provider. Choose free home shipping and activation, or buy online and activate during in-store pickup... Read more
Apple refurbished 2014 MacBook Airs available...
The Apple Store has Apple Certified Refurbished 2014 MacBook Airs available starting at $679. An Apple one-year warranty is included with each MacBook, and shipping is free. These are currently the... Read more
27-inch 3.5GHz 5K iMac on sale for $2349, sav...
 Adorama has the 27″ 3.5GHz 5K iMac in stock today and on sale for $2349 including free shipping plus NY & NJ sales tax only. Their price is $150 off MSRP. For a limited time, Adorama will... Read more
Save up to $380 on an iMac with Apple refurbi...
The Apple Store has Apple Certified Refurbished iMacs available for up to $380 off the cost of new models. Apple’s one-year warranty is standard, and shipping is free: - 27″ 3.5GHz 5K iMac – $2119 $... Read more
iFixIt Teardown Awards 12-IInch Retina MacBoo...
iFixIt has posted its illustrated teardown of the new 12-inch MacBook Retina. They note that this new MacBook is less than half the thickness of the last Apple notebook called just “MacBook” back in... Read more
13-inch 2.5GHz MacBook Pro (refurbished) avai...
The Apple Store has Apple Certified Refurbished 13″ 2.5GHz MacBook Pros available for $829, or $270 off the cost of new models. Apple’s one-year warranty is standard, and shipping is free: - 13″ 2.... Read more
Faithful iPad 2 Gets A Second Career In Retir...
Finally, after four months’ transition, I handed my faithful old 2011 iPad 2 off to my wife at the end of March and switched whole-hog to using the iPad Air 2 I bought back in November. I’d found... Read more

Jobs Board

*Apple* Solutions Consultant - Retail Sales...
**Job Summary** As an Apple Solutions Consultant (ASC) you are the link between our customers and our products. Your role is to drive the Apple business in a retail Read more
*Apple* Retail - Multiple Positions (US) - A...
Sales Specialist - Retail Customer Service and Sales Transform Apple Store visitors into loyal Apple customers. When customers enter the store, you're also the Read more
*Apple* Retail - Multiple Positions - Apple,...
Job Description: Sales Specialist - Retail Customer Service and Sales Transform Apple Store visitors into loyal Apple customers. When customers enter the store, Read more
*Apple* Solutions Consultant - Retail Sales...
**Job Summary** As an Apple Solutions Consultant (ASC) you are the link between our customers and our products. Your role is to drive the Apple business in a retail Read more
*Apple* TV Live Streaming Frameworks Test En...
**Job Summary** Work and contribute towards the engineering of Apple 's state-of-the-art products involving video, audio, and graphics in Interactive Media Group (IMG) at Read more
All contents are Copyright 1984-2011 by Xplain Corporation. All rights reserved. Theme designed by Icreon.