heymodule - BeOS Application Scripting from Python

Version 1.1
January 1, 1999

(See the Changes section for a list of changes since Heymodule 1.0.)

BeOS R3 introduced a new BMessage based scripting system, that lets you remote control applications by sending them special scripting messages.

In theory, you can use anything you want to script your applications, as long as it can send and receive BMessage objects. In practice, you either have to write a C++ application, or use Attila Mezei's hey utility from the command-line.

Until now.

heymodule lets you do BeOS application scripting from Python. As far as I know, this is the very first third-party programming language to support BeOS's scripting!

Installing heymodule

Install Python

Before you install heymodule you must install Python 1.5.2. Currently, it's only distributed as source code:

1. Download the Python 1.5.2b1 source code from the official Python website.
2. Unpack the Python 1.5.2b1 archive, and follow the instructions in BeOS/README exactly. The BeOS port isn't 100% finished yet, and it's the build process that still needs work.
3. Before doing a the make ... install step, edit the top-level Makefile and change two lines in the libainstall: target. Originally, they look like this:

   		$(INSTALL_DATA) $(LIBRARY) $(LIBPL)/$(LIBRARY)
   		$(RANLIB) $(LIBPL)/$(LIBRARY)
   

   And you should change them to look like this:

   		#$(INSTALL_DATA) $(LIBRARY) $(LIBPL)/$(LIBRARY)
   		#$(RANLIB) $(LIBPL)/$(LIBRARY)
   

   Then do the make OPT=-DUSE_DL_EXPORT CCSHARED=-UUSE_DL_EXPORT MACHDEP=beos install step and Python should install properly.

Install heymodule

If you're on a PowerPC system:

1. Download the heymodule package for Software Valet or the heymodule ZIP archive.
2. Install heymodule:

   If you've got this...	Do this:
   SoftwareValet package	Double-click the package file and follow the on-screen instructions as you normally would with Software Valet.
   ZIP archive	Unzip the archive: $ cd /boot $ unzip -o /path/to/py-heymodule-1.1-ppc.zip

If you're on an x86 system:

1. Download the heymodule ZIP archive.
2. Install heymodule:

   $ cd /boot
   $ unzip -o /path/to/py-heymodule-1.1-x86.zip
   

Installing heymodule puts all the magic bits (the heymodule.so shared library) into the right places (/boot/home/config/lib/python1.5/BeOS). It also installs a heymodule-1.1 directory in /boot/apps; look inside for this documentation, and a few example scripts.

Now what?

Well, now you can do application scripting from Python.

This isn't saying much though; scripting isn't well documented yet, and there isn't really a whole lot you can do that's useful.

The BeOS Bible will have an excellent chapter on Scripting when it's published in the next month or two. Sorry for the plug, I wrote that chapter. :-)

If you've never used Python before, you can find tutorials at http://www.python.org/, and there are several great Python books for beginners:

• Programming Python, by Mark Lutz
• Internet Programming with Python, by Aaron Watters, Guido van Rossum and James C. Ahlstrom
• Das Python-Buch (German), by Martin von Löwis and Nils Fischbeck

Using heymodule

Importing heymodule

Before you can use heymodule, you've got to import it into Python:

import BeOS.hey

heymodule contains two Python objects, so it's probably going to be easier to use if you import those objects directly into your namespace:

from BeOS.hey import Hey, Specifier

This will let you refer to the Hey object directly, instead of with a qualified name, BeOS.hey.Hey. Much nicer if you're using heymodule from an interactive session; you can do whatever you want in a Python program.

You probably won't need to use the Specifier directly; the Hey object's Specifier() method knows how to create one for you.

Creating a Hey object

The Hey object is your communications portal into the BeOS scripting world; you need one of these to do anything useful with heymodule. This handles all of the communication between your Python script and a BeOS application.

You can have as many Hey objects communicating with as many applications as you want, or they can all be communicating with the same application.

Hey's constructor requires a string; this string can be:

• an application signature (such as application/x-vnd.Be-ShowImage); you can discover these by dropping the application on the FileTypes icon
• the name of a running application or application thread (such as StyledEdit); thread names will pick up the application's messanger, you can't currently target a specific thread
• a MIME type (such as text/html); this will get the preferred handler for that MIME type (NetPositive, in this case, unless you've changed the text/html handler)

Creating a Hey object from an application signature or MIME type will attempt to launch the appropriate application if it's not already running.

Hey object methods

The Hey object supports the following methods; each of these communicates with the application specified in the Hey constructor:

Unless stated otherwise, these methods will all return something reasonable for the given specifier. For example, if you're after the Frame of a Window, you're going to get back a rectangle (which will be a four-item tuple in Pythonese). If you ask for the Title, you'll get back a string.

If the Hey object doesn't know what the hell the other app was talking about in its reply, you'll get the entire message back; this is a Python dictionary, with keys matching the BMessage item names. Each key indexes a tuple, since BMessage can have multiple items under a single name.

Thus, if you got back a dictionary from one of the Hey methods, you could check the reply's error value like this:

import os
...

if reply.has_key( "error" ):
    # Get the first item out of the tuple... there isn't likely to be
    # more than one "error" entry anyway.
    value = reply["error"][0]
    
    if value != 0:
        print "It's the end of the world as we know it!"
        print os.strerror( value )

Specifier objects

The Specifier object is used by Hey's methods to target a specific part of an application, such as a view inside a window.

Creating a Specifier - the hey way

You can create a full, ready-to-use Specifier by using Hey's Specifier() method or the Specifier constructor with a string:

The string uses exactly the same syntax as the hey command-line tool. Specifically:

specifier_1 [of specifier_2 ... specifier_n]

Where a specifier is a property name (such as Title or Window; see your application's documentation for more information about the properties it supports) optionally followed by a qualifier:

Properties without extra qualifiers are direct specifiers.

Consult your application's docs to find out what kind of specifiers it supports, and look in The Be Book's scripting topic for more information about properties and specifiers.

Creating a Specifier - the Specifier Stack way

The other way to create a usable Specifier is to create what The Be Book's scripting topic calls a Specifier Stack. Doing it this way is handy if you've got some docs that talk about application scripting for a C++ using audience; you can use almost the same syntax.

Step one is to create an empty Specifier using Hey's Specifier() method or the Specifier constructor:

spec = hey_object.Specifier()
...
spec2 = Specifier()

Now you use the Specifier object's Add() method to populate the Specifier:

# We're after the title of the first window:
spec.Add( "Title" )
spec.Add( "Window", 0 )

title = hey_object.Get( spec )
print "The title is:", title

The specifier stack is created from the most specific item (in this case, the Title) to the least specific (the Window).

Specifier's Add() method

The Add() method lets you add any kind of specifier to the stack:

Examples

Hiding and showing windows

Say you start campus from your UserBootscript, and you'd like to hide it's status window:

from BeOS.hey import Hey
x = Hey( "campus" )

# Windows have a "Hidden" property; if it's "true",
# the window is hidden, otherwise the window is
# shown.

s = x.Specifier( "Hidden of Window 0" )
reply = x.SetBool( s, 1 )

To make it reappear:

from BeOS.hey import Hey
x = Hey( "campus" )
s = x.Specifier( "Hidden of Window 0" )
reply = x.SetBool( s, "false" )

Getting the Title and Frame of a window

Let's start the preferred handler for text/plain files, and find the Title and Frame rectangle of its first window:

from BeOS.hey import Hey

x = Hey( "text/plain" )

# Set up a specifier for the Frame, using the hey style.
# The Frame is the rectangle where the window dispalys
# stuff, just inside the window border.

frame_spec = x.Specifier( "Frame of Window 0" )

# Set up a specifier for the title, using the specifier stack.

title_spec = x.Specifier()
title_spec.Add( "Title" )
title_spec.Add( "Window", 0 )

# Get the frame and title.

frame_rect = x.Get( frame_spec )
title = x.Get( title_spec )

# Now say what we got.

print "The window %s has a frame rectangle of %s." % ( title, frame_rect )

# Now tell the text/plain handler to quit.

x.Quit()

On my system, StyledEdit is the text/plain handler, and this script prints:

The window Untitled 1 has a frame rectangle of (7.0, 26.0, 507.0, 426.0).

Moving windows around

Let's start the preferred handler for text/plain files again and move its window around.

from BeOS.hey import Hey
from time import sleep

# Start the text/plain handler if it's not already running.

x = Hey( "text/plain" )

# Set up a specifier for its Frame.

frame_spec = x.Specifier( "Frame of Window 0" )

# Get the left, top, right, and bottom values for its Frame rectangle.

(left, top, right, bottom) = x.Get( frame_spec )

for foo in range( 5, 105, 5 ):
    # Looks like you need to refresh the specifier every time you want
    # to use it... bug or feature?
    #
    # It turns out that this is a bug of mine; with heymodule 1.1,
    # you don't need this:

    #frame_spec = x.Specifier( "Frame of Window 0" )

    # Move the window 5 pixels at a time:

    reply = x.SetRect( frame_spec,
        ( ( left + foo ), ( top + foo ), 
          ( right + foo ), ( bottom + foo ) ) )

    # Just to show that this is the same as using the "hey" style...
    # If you need to re-use a specifier like this, it'd be more
    # efficient to set it up outside the loop!

    frame_rect = x.Specifier()
    frame_rect.Add( "Frame" )
    frame_rect.Add( "Window", 0 )

    # Get and print the current frame rectangle.

    now_rect = x.Get( frame_rect )
    print "rect is now '%s'" % ( now_rect, )

    # Snooze for a second so we can actually see the window moving.

    sleep( 1 )

# Tell us where the script left the window.

frame_rect = x.Specifier( "Frame of Window 0" )
new_rect = x.Get( frame_rect )
print "The window is now at %s." % ( new_rect, )

Listing an application's windows

Say you want to know the titles of every window in the currently running Pe session:

from BeOS.hey import Hey

# Create a Hey object to talk to Pe.
pe = Hey( "pe" )

# Count its windows.
wind = pe.Specifier( "Window" )
num = pe.Count( wind )

print "Pe has %d windows..." % ( num )

# For every window, find its title.  We need to set up
# a specifier every time because we're aiming this
# message at a different window every time.

for i in range( num ):
    s = pe.Specifier()
    s.Add( "Title" )
    s.Add( "Window", i )

    name = pe.Get( s )

    print "Pe's window %d is named '%s'" % ( i, name )

Right now on my system I get something like this:

Pe has 7 windows...
Pe's window 0 is named 'Open'
Pe's window 1 is named 'Find'
Pe's window 2 is named '/boot/home/config/settings/pe/Worksheet'
Pe's window 3 is named 'Preferences'
Pe's window 4 is named '/boot/src/Python/Python-1.5.1/Modules/heymodule.cpp'
Pe's window 5 is named '/boot/src/Python/Python-1.5.1/Modules/heymodule.html'
Pe's window 6 is named '/boot/src/Python/Python-1.5.1/Modules/testhey.py'

Since I can't see windows 0, 1, and 3 on my screen, Pe must keep them around as hidden windows. As an exercise for the reader, change this to make all of the windows visible (or if you're feeling saucy, show all the hidden windows and hide all the visible windows).

Changes

1.1 for x86 (January 1, 1999)

• This release is dedicated to Scot Hacker; without him, the x86 port wouldn't have appeared as quickly as part of the Python 1.5.2 public beta. Thanks for your support Scot!
• x86 version for Python 1.5.2b1 released.

1.1 (November 10, 1998)

• This release is dedicated to our excellent BeOS news sites:
  • BeForever
  • Be News
  • BeOS Central
• source code reorganisation
• documentation clean-up
• fixed specifier re-use bug (thanks to Peter "Scripto" Potrebic for pointing this out!)

1.0 (November 1, 1998)

• Initial version released for BeOS Masters Awards.

Last modified: $Date: 1999/01/01 15:09:20 $

Copyright © 1998-1999, Chris Herborth (chrish@qnx.com)