BeScriptPeek
Version 1.0a6
©2000 Dario Accornero
BeDev #10183
http://bexoft.com
mailto:bexoft@bexoft.com

A component of BeScript

Introduction

BeScriptPeek is an application that allows users examine all the scriptable objects (in the native BeOS sense) currently running on their systems. The program displays a list of scriptable objects: when users navigate the list, BeScriptPeek displays the scripting capabilities of the selected object. These are known as supported suites in BeOS parlance.

In the BeOS a scriptable object is any object that inherits from the BHandler class and supports the scripting system. BeScriptPeek can examine any such object that is advertised by an application, such as a Window or a View (remember that properties such as these are always in MixedCase). With BeScriptPeek users can learn about the scriptable objects available on their system easily and comfortably: all objects are accessible in a hierarchical manner. Single objects as well as entire sub-hierarchies can be expanded/collapsed at any time.

Usage

Run BeScriptPeek either from the Tracker or from the command line.

In the former case, or when launching from a shell with no parameters, the program will analyze all currently running applications and produce a list of their scriptable objects. Non-scriptable applications will not be reported in the list. Non-scriptable windows or views currently will not be reported either because of a bug in native BeOS scripting. Non-scriptable windows are unfortunately common in misbehaved applications (e.g. e-Picture from BeatWare, Inc.) Non-scriptable views are somewhat rare -- but please read the Known Bugs section for more information.
When BeScriptPeek is run from a shell, users can specify specific applications to examine via command-line parameters, which may be either application names or MIME signatures.

Examples are (assuming you have BeScriptPeek in/boot/home/Utilities):

$ cd /boot/home/Utilities
$ BeScriptPeek

Analyzes all running applications (equivalent to launching the program from the Tracker).

$ BeScriptPeek application/x-vnd.Be-STEE NetPositive BeIDE

Analyzes only StyledEdit (specified via its MIME signature), NetPositive, and the BeIDE.

Applications and other objects will appear in the BeScriptPeek scriptable list as soon as their analysis is complete. For complex applications with many windows this process may take a few seconds.
Any application specified on the command-line must be running when invoking BeScriptPeek -- it will not be launched for you. The most common usage is to run BeScriptPeek from the Tracker and have it analyze all currently running applications.

The scriptable list is displayed on the left of the BeScriptWindow and it is navigable with either the keyboard or the mouse. Selecting an item in the list will display its scripting capabilities in the related box to the right of the window. This box too is navigable with either the keyboard or the mouse, but currently it has only information purposes.
Expanding or collapsing an object in the scriptable list while holding down the B_OPTION_KEY (i.e. usually the Windows key on a standard PC keyboard) will expande or collapse the entire sub-hierarchy of scriptable objects rooted at the current object.

Each object can have two identifiers: an "internal name" and a "real name". For applications, the former is their MIME signature and the latter is their name. For windows, the former is either their title or the string "Window #" (where # is an integer index starting at zero), and the latter is their title or the empty string. For views, the former is either their internal description (mainly useful for programmers but "unfortunately" the reason why dynamic specifiers are needed) or the string "View #" (with the same rules as above), and the latter is either their screen name (i.e. Label), or equal to their internal name, or it is the empty string. Below is a general discussion of BeOS specifiers and how the BeScript system handles them. It is worth reading it if you plan to use BeScript in the future to control your applications: BeScriptPeek was created in order to facilitate the development of BeScript programs.

Internal names are reported in black and are known as regular specifiers. These are the only specifiers natively available on the BeOS: the scripting system works only with this kind of specifiers. This, however, is not very comfortable for end users: very often programmers (including myself) forget to assign meaningful internal names to their views. This is precisely the reason for using real or screen names.

A specifier based on a screen name is known as a dynamic specifier in BeScript parlance. The BeScript system, and hence BeScriptPeek too, can access any specifier: dynamic ones are based on screen names and appear in
red. Note that while an object is guaranteed to have an internal name (or e.g. the "Window #" / "View #" identifier), the object is not guaranteed to have a screen name at the same time. If it does, it is usually easier for users wishing to control their applications via BeOS scripting to handle their objects using dynamic specifiers. The reason is very simple: just by looking at an application Window, the screen names of GUI objects (such as "Use an external editor") are immediately visible, whereas internal names are, well, internal. However, the price to pay for using dynamic specifiers is a slight performance penalty because the BeOS scripting system was designed to handle pure (i.e. based on internal names) specifiers only. BeScript is capable of taking an X-rays picture of any scriptable GUI object and therefore makes it possible to use dynamic specifiers.

Known Bugs

Some applications, including Be-provided programs such as MediaPlayer and SoundRecorder, and also third-party applications such as BeShare,
crash while BeScriptPeek analyzes them using dynamic specifiers. The reason is likely that they inherit from broken Be classes that have problems in scripting support, as reported in bug #20001020-21887. This is not the fault of BeScriptPeek or of the BeScript system (i.e. you can crash those applications with the "hey" utility by Attila Mezei too, mail me privately if you want more information) and I cannot do anything about it.

Version History

Version 1.0a6
November 6, 2000

+ Added support for hierarchical suites display: any property within a suite that might have a suite of its own can be scanned. There is a new "Suites" menu that controls the display mode. See this screenshot for an example.

* Fixed bug with suites display (both system and expanded) where custom specifiers such as 'sprv' from Tracker Poses were being reported incorrectly.

Version 1.0a5
November 3, 2000

+ Added support for BeScript- and hey-friendly display of supported suites (called Expanded Suites Display). Examples are:
Frame      B_GET_PROPERTY B_SET_PROPERTY          DIRECT

becomes (two lines):

get Frame
set Frame


MenuItem   B_EXECUTE_PROPERTY B_DELETE_PROPERTY   NAME INDEX REV.INDEX

becomes (six lines):

execute MenuItem "name"
execute MenuItem index (0,1,...)
execute MenuItem -index (0,1,...)
delete MenuItem "name"
delete MenuItem index (0,1,...)
delete MenuItem -index (0,1,...)


Window     'TILE' 'STAK'                          DIRECT

becomes (two lines):

do 'TILE' Window
do 'STAK' Window
The next version will add support for copying a line to the clipboard.
The display mode is selectable from the "Peek" menu. Also, added keyboard shortcuts for the menu.

+ Added support for retrieving dynamic names of single objects: when you double-click on an item, applications are scanned as per the previous version whereas Windows and Views are asked for their dynamic name.

* Fixed bug where turning on and off the "Retrieve Dynamic Names" option in the "Peek" menu would work only for currently visible items (was calling ItemAt() instead of FullListItemAt()).

* Fixed bug where the scripting information box would not update its scrollbars correctly on a resize event. I was using BetterScrollView from Santa's Gift Bag but apparently the scrollbars were losing some pixels during a resize. The current implementation is rather painful but works properly.

Version 1.0a4
October 30, 2000

+ Added support for retrieving dynamic names on demand. By default, BeScriptPeek now starts up with the option turned off because of the bug reported in the Known Bugs section. However, at launch time the dynamic name of applications is retrieved in any case, because dealing with MIME signatures is not terribly comfortable. An option in the "Peek" menu enables users to retrieve or discard the dynamic names of all scriptable objects currently available at any given time.

+ Added support for refreshing applications, useful after having opened/closed windows. Double-click on an application in the scriptable list to rescan and immediately redisplay it on screen. Obviously new windows appear collapsed since there was no previous hierarchy rooted at those items.

Version 1.0a3
October 26, 2000

+ Added display of specifier for currently selected object.

* Fixed bug where non-scriptable objects would appear in the hierarchy anyway, causing confusion and potential crashes.

* Fixed bug where turning off the "Watch Application Launch" option would not actually prevent new applications from being analyzed -- only from being added to the hierarchy. Now new applications are not analyzed at all.

Version 1.0a2
October 25, 2000

* Fixed bug where scriptable objects that advertise empty suites (e.g. Opera 3.62 URL windows) would crash the BeScript system while inquirying them of their supported suites.

Version 1.0a1
October 19, 2000

+ Added option to watch application launch and quit messages from the system. BeScriptPeek will smoothly analyze all well-behaved applications and add them to the programs list. Note that crashing applications (see above) will disappear from the list if the watch quit option is selected. This makes it harder to debug them, but by default the option is on because we don't want to fiddle with a dead team. Also, note that currently windows that are not created at startup time will not be added to the programs list -- that is, BeScriptPeek senses only applications creation/destruction, not windows (yet).

+ Added icon display to all scriptable objects. Currently applications use the generic icon but in the future we'll add support to display their real icon. Windows and views have no option but displaying generic icons.

* Fixed bug where launching the program from the command-line with an invalid application identifier would result in no applications being analyzed -- BeScriptPeek would still think that a valid target was selected and cancel the analysis anyway.

* Fixed memory leak where launching the program from the Tracker would result in a local list of applications running at launch time being left dangling around. It is now disposed of since it is unused.

* Horizontal scrolling in the scriptable list causes some visual artifacts when moving slowly. Hard to fix bug, bloody round-by-something or pixel adjustment error.

Version 1.0d3
October 18, 2000

* First usable release. Released only to Scot Hacker, like the previous, really (honest ;-) first release.