CPIA Script User Guide

CPIA Script is using Python. CPIA Script provides three things:

1. a UI that makes it easy to create and run scripts
2. a set of conveniences that hide the complications inside our application
3. a class that simulates a User to create low level events

Lets start by looking at the user interface.

Script User Interface

To start scripting, you currently must select an item from the Test menu -- "Show Scripts in the Sidebar"

You use the "Scripts" collection to view all the Scripts in the repository. We've created some useful ones for you. Specifically, there's a script connected to the F1 key that creates a new Script for you. You can immediately start typing into the body of this new script, and then execute it using the command-s shortcut to the Test menu item 'Run "Untitled"'. Scripts have a couple of attributes displayed in the Detail View. These include a Function Key used to activate the script, and a "Test" boolean. One of the unit tests launches Chandler and runs all the scripts marked as test scripts, for a simple form of automated testing. Function key script triggering lets you write scripts that interrogate the current focus and other useful things because you can run the scripts without needing to have your script selected.

Scripts themselves are ContentItems that keep their script text in the body attribute (where notes go), and keep track of the last time they were run, etc.

There are a couple of different ways to invoke a script:

• When running Chandler from the command line using the --testScript parameter:

         release/RunChandler --testScript 

This runs all the scripts with the "Test" attribute set, to test Chandler.

• From the command line using the --scriptFile parameter:

         release/RunChandler --scriptFile="/Users/OSAF/script.txt"

• By pressing a function key (in the range F1 through F24)
  • To make the function key work, put your script in the body of any Chandler Note item, and set the Function Key attribute to the number of the function key you want to connect the script to.
• By selecting the script, and choosing the Test/Run "script name" menu item, which is connected to Command-S.

Scripts are Python code. As such, it's convenient to use file-based Python tools to edit scripts. You can do this by saving the script to a file, and then editing that file with your regular Python editor instead of editing it in the Detail View of the script. Whenever scripts are loaded or executed, the scripting system synchronizes the script in the repository with the script in the file, with the most recently changed version winning out. This makes it easier to debug scripts, set breakpoints, and do the other things normally done in the course of Python development.

Script Conveniences

A Script is really just some python code that gets executed in an environment that has some convenient definitions for you to use.

These conveniences fall into two categories:

1. Access to Chandler's features that are complicated by internal implementation details
2. Simulating User actions, like typing some text into a field

An example of the first category is getting access to the Summary View. The way CPIA is implemented, there may actually be several Summary Views, but only one of them will be rendered at any given time. So finding the current view is non-trivial. With the conveniences, you can essentially just say

convenience.summary

to get the summary view.

You get at the Chandler conveniences using the app_ns(view) function. This creates and returns an AppProxy object, which is a proxy to the osaf.app namespace inside the specified view. You can leave off the view parameter and it will default to the UI Repository View - the view used by Chandler's UI. The AppProxy object has attributes that automatically lookup all the major blocks in Chandler:

• sidebar - proxy to the Sidebar
• summary - proxy to the Summary View
• calendar - proxy to the Calendar View
• appbar - proxy to the Application Toolbar
• markupbar - proxy to the Markup Toolbar
• detail - proxy to the Detail View
• root - proxy to the Main View Root

The root and detail attributes are special. The detail attribute gives you a proxy that has a bunch of blocks from the detail view as its attributes:

• start_time -- the calendar event start time edit field
• start_date -- the start date
• location -- the location block
• title -- also known as the Headline area etc

The RootProxy has some extra behavior. It is the block that posts commands that you send to Chandler. All defined BlockEvent objects that are available through the eventsForNamedLookup attribute are methods of this object. So you can say app_ns().root.New() to create a new Note, for example. See the command reference below for a list of commands available as methods of the RootProxy object.

The AppProxy actually maps all named blocks onto its attributes, so you can say app_ns().MiniCalendar to get the MiniCalendar block for example.

Command Reference

CPIA BlockEvents that are available as "named" events are available as commands in CPIA Script. But you need to be somewhat careful using them:

• Some require parameters, which is a bit tricky. You can either use the syntax used internally by CPIA (pass a single dictionary for the parameters), or pass named parameters, or both.
• Some work, but not in all contexts. Take "Remove" for example. You can use it to remove your "All" collection - something the UI won't normally let you do.

Below is a list of all the CPIA Events available in the system.

• Bold commands are tested and work
• Italic commands don't work or should not be used
• Plain items have not yet been investigated

---

1. About() - bring up the "about" box
2. AcceptShare()
3. ActiveateWebserver - activate the test feature making Chandler a Web server
4. AddAllAdditionalViews() - adds all the extra views to the sidebar (CPIA view, Block Demo view, and Repository view)
5. AddCPIAView() - adds the CPIA viewer to the sidebar
6. AddDemoView() - adds the Block Demo view to the sidebar
7. AddRepositoryView() - adds the Repository view to the sidebar
8. AddText()
9. AddToSidebarWithoutCopying()
10. AddToSidebarWithoutCopyingAndSelectFirst()
11. AddToSidebarWithoutCopyingOrCommiting()
12. ApplicationBarAll() - switches to the All view
13. ApplicationBarEvent() - switches to the Calendar view
14. ApplicationBarMail() - switches to the Email view
15. ApplicationBarTask() - switches to the Tasks view
16. BackupRepository() - invoke the test feature to create a repository backup
17. CertificateImportBlock() - imports a certificate PEM file
18. CertificateViewBlock() - add the Certificate view to the sidebar
19. ChangeLayout()
20. CheckRepository() - same as the menu item
21. ChooseAttributeEditorsTab()
22. ChooseButtonsTab()
23. ChooseChandlerMainView()
24. ChooseControlsTab()
25. ChooseCPIATestMainView()
26. ChooseHTMLTab()
27. ChooseIntroTab()
28. Close() - close the topmost window, which may quit Chandler
29. CommitRepository() - commit changes to the repository
30. Copy() - copy the selected item to the clipboard
31. CopyCollectionURL()
32. Cut() - cut the selected item
33. CycleTabs()
34. EditAccountPreferences() - bring up the account preferences dialog
35. EditCollectionRule() - bring up a dialog to let you edit the selected collection's rule
36. EnterPressed()
37. ExportIcalendar() - brings up a dialog box for exporting the calendar
38. GenerateContentItems() - generates many items of each kind for testing purposes
39. GetNewMail() - attempts to get new mail according to the account preferences
40. i18nMailTest()
41. ImportIcalendar() - brings up a dialog box for importing an ICS file
42. ImportImage() - import an image to create a Photo item
43. ManageSidebarCollection()
44. MimeTest() - same as the menu item
45. New() - create and select a new Content Item (defaults to Note)
46. NewAmazonCollection() - same as the menu item
47. NewAmazonWishList() - same as the menu item
48. NewCalendar() - create and select a new calendar Event
49. NewContact() - create a new Contact
50. NewFlickrCollectionByOwner() - same as the menu item
51. NewFlickrCollectionByTag() - same as the menu item
52. NewItemCollection() - create and select a new Item Collection
53. NewMailMessage() - create and select a new Mail Message
54. NewNote() - create and select a new Note
55. NewTask() - create and select a new Task
56. NewZaoBaoChannel() - same as the menu item
57. Open()
58. Paste() - paste the contents of the clipboard into the selection
59. Preferences()
60. Print() - same as the menu item
61. PrintPreview() - same as the menu item
62. Quit() - exit the application (Often crashes on a debug build)
63. Redo()
64. ReloadParcels() - same as the menu item
65. ReloadText()
66. ReminderTime()
67. Remove()
68. RequestSelectSidebarItem()
69. Resynchronize() - Resynchronize the Detail View
70. RunScript()
71. SelectedDateChanged()
72. SelectItemBroadcast()
73. SelectItemBroadcastInsideActiveView()
74. SelectWeek()
75. SendMail()
76. SendShareItem()
77. SetContents()
78. ShareCollection() - obsolete: use ShareSidebarCollection()
79. ShareItem()
80. ShareSidebarCollection()
81. ShareTool() - displays the share tool
82. SharingImportDemoCalendar()
83. SharingSubscribeToCollection()
84. ShowHideApplicationBar() - same as menu item
85. ShowHideSidebar() - same as menu item
86. ShowHideStatusBar() - same as menu item
87. ShowPyCrust() - brings up an interactive Python shell
88. StartProfiler()
89. StopProfiler()
90. SyncAll() - same as Sync All button
91. SyncCollection()
92. SyncWebDAV()
93. TogglePrivate()
94. ToggleSharingActive()
95. UnpublishSidebarCollection() - same as the Collection/Unpublish menu item
96. UnsubscribeSidebarCollection() - same as the Collection/Unsubscribe menu item
97. Undo()
98. WxTestHarness()

Item Selection

If you want to select an item in a Table, just call the select() method on the table object, passing in the item to be selected. The summary view supports named lookup, so you can use name= to select an item by name. Note that this feature is in Chandler itself, not CPIA Script, and it's likely to change as Chandler evolves. E.g. select should probably accept a list, so multiple items can be selected.

We'll need to add an implementation of select for the Calendar View.

Simulating User Actions

There's a User class in the conveniences that help you simulate user actions. All the methods in this class are class methods, so you never need to instantiate the User class, you can just call the methods directly. The methods are:

• emulate_typing(string, etc) -- emulate the user typing a string. There are additional parameters not described here.
• emulate_return(block) -- emulate the user pressing the return key in the given block
• emulate_click(block) -- emulate the user pressing and releasing the left mouse button in the given block.

So you can say User.emulate_click(app_ns().detail.location) to click on the location block of the detail view.

More Information

For more detailed information about specific features of CPIA Script, look at the code. The entire implementation is now in one file: scripting.py in the osaf.framework module.