TweetFollow Us on Twitter

December 94 - Exploring Advanced AOCE Templates Through Celestial Mechanics

Exploring Advanced AOCE Templates Through Celestial Mechanics

Harry R. Chesley

PowerTalk provides AOCE catalogs to store and edit collections of information. The Catalogs Extension to the Finder lets you use AOCE templates to extend the types of information stored and the means of editing it, which makes the catalogs open-ended rather than limited to the information types provided by Apple with the PowerTalk software. This article explores several advanced features of AOCE templates, showing how new types of entries can be added that store information about planets and calculate their current locations and orbits.

The AOCE Catalogs Extension (CE) -- an extension to the Finder and one of the PowerTalk components -- was originally conceived as an open-ended means of providing addresses for PowerTalk mail and messaging; however, it goes well beyond that original goal. The CE allows third-party developers to extend the Finder in a variety of ways, including providing new catalog entry types, new views on the contents of entries, new means of editing those contents, runtime calculation of information to be displayed, and new actions to perform in the case of drag and drop and double-click operations. AOCE templates, which serve as the extension mechanism, provide resources and code that define the format, appearance, and functionality of catalog entries.

Because this article explores advanced features of the AOCE template mechanism, we assume some familiarity with AOCE catalogs and a basic understanding of AOCE templates and the terms used to describe them. The article "Getting the Most out of AOCE Catalog Records" in this issue gives an overview of AOCE catalogs and templates. For in-depth information, the definitive reference is Inside Macintosh: AOCE Application Interfaces.

In this article, we demonstrate how the template mechanism can be extended to plot the orbits of the planets. For those of you who aren't interested in celestial mechanics and could care less about the mathematics involved in calculating the position of a celestial body, don't worry -- the article focuses on templates; you can skip the details on celestial mechanics without limiting your understanding. But if you are interested, see "Algorithms for Calculating Planetary Positions."

We begin by developing a set of templates that plot the positions and orbits of the planets at a specified time. A sublist on one of the record information pages lists the planets and their positions. We also develop templates to display information pages for each planet; these pages enable the user to enter the information needed to calculate a planet's orbit. The calculations and plotting are performed by code resources in the templates. Using the techniques described in the article, you could add other types of celestial bodies (such as comets, moons, and alien spacecraft) that would be defined by a different set of parameters and have a different algorithm for calculating position and orbit.

Although the templates are quite straightforward in general, the article focuses on the code resources that implement three advanced features of the template mechanism:

  • type conversion between text (RStrings) and custom, internal data types -- to display and edit floating-point numbers and date/time information

  • automatic calculation of property values when other selected property values change -- to update the planet's position when the time or orbital parameters change

  • drawing in a custom view -- to display the plotted object positions and orbits

DEFINING THE TEMPLATES

The templates we create define a record type of "hrc Orbits" to hold the list of planets we want to display. The record contains an attribute type "hrc Planet" with one attribute value per planet and an attribute value tag of 'plnt'. There's also a single-valued attribute of type "hrc Orbits info," which holds information pertinent to the orbits record.

Using an attribute value tag allows for future expansion to new types of objects -- spacecraft, for instance. In the example, the aspect template for the attribute type "hrc Planet" is used only for attribute values with the attribute value tag 'plnt'. To add a new type of object, which may require different orbital parameters and a different algorithm to calculate the orbits, you would use a different tag. For example, an attribute value that describes a spacecraft might have an attribute value tag of 'crft'.

We need to define the following templates:

  • information page templates for the orbits record (record type "hrc Orbits")

  • information page templates for the attribute type "hrc Planets," which is the attribute type of the sublist entries

  • an aspect template for the record type "hrc Orbits"

  • an aspect template for the attribute type "hrc Planets"
These templates are included on this issue's CD. There's nothing remarkable about most of them. This article discusses only those portions of the templates that are more interesting and unusual.

ORBITS RECORD INFORMATION PAGE TEMPLATES

We use two information pages to display the information stored in an orbits record (Figure 1). The List information page contains a sublist of planets (attribute type "hrc Planet"), allowing the user to create new planets and drag existing ones into and out of the list. Besides an icon, name, and kind, the sublist on the List page displays x and y coordinates for each planet. This is the location at the time given in the field at the top of the page. The user can edit the time to see past and future positions. The Continuous Update checkbox, when checked, causes the Time field to be constantly updated to the current time. The state of this checkbox is kept in the "hrc Orbits info" attribute of the orbits record.



List

Plot

Figure 1. Information pages for the orbits record

The Plot information page contains a plot of the position of each planet in the sublist on the List information page. When the Show Orbits checkbox is checked, the plot shows not only the position of each planet, but also the future track -- the orbit -- of the planet. Orbital calculations take a lot of time, especially on slower systems, so the user can choose whether or not to display this information.

Listing 1 shows resource definitions for the Plot information page template. Note that kOrbitsCustomViewProperty is used for the property number for both the Show Orbits checkbox and the custom view that plots the positions. Normally two views don't share the same property. Using the same one here causes an automatic redraw of the custom view when the checkbox changes. This is simpler than using the code resource to intercept the property-dirtied call resulting from the checkbox change and using a dirty-property callback to cause the custom view to be redrawn. (Whenever a property is changed, a kDETcmdPropertyDirtied call is made to the code resource.) The bulk of the work for the custom view occurs in the code resource, as described later in the section "Drawing in a Custom View."

Listing 1. Plot information page template

resource 'deti' (kOrbitsPlotPage, purgeable) {
   2000, kDETNoSublistRect, noSelectFirstText,
   { 
   kDETNoProperty, kDETNoProperty, kOrbitsPlotPage; 
   },
   {}
};

resource 'rstr' (kOrbitsPlotPage+kDETTemplateName, purgeable) {
   "hrc Orbits plot page"
};
resource 'rstr' (kOrbitsPlotPage+kDETRecordType, purgeable) {
   kOrbitsRecordType
};
resource 'rstr' (kOrbitsPlotPage+kDETInfoPageName, purgeable) {
   "Plot"
};

resource 'rstr' (kOrbitsPlotPage+kDETInfoPageMainViewAspect, 
   purgeable) {
   "hrc Orbits main aspect"
};

resource 'detv' (kOrbitsPlotPage, purgeable){
   {
   kDETSubpageIconRect, kDETNoFlags, kDETAspectMainBitmap,
   Bitmap {kDETLargeIcon};

   {12, kOrbitsPageWidth-120, 28, kOrbitsPageWidth-8},
      kDETNoFlags, kOrbitsCustomViewProperty,
      CheckBox {kPalatino, 12, kDETLeft, kDETBold,
                  "Show Orbits", kOrbitsCustomViewProperty};

   {44, 8, kOrbitsPageHeight-8, kOrbitsPageWidth-8}, kDETNoFlags,
      kDETNoProperty, Box {kDETUnused};

   {47, 11, kOrbitsPageHeight-11, kOrbitsPageWidth-11}, kDETNoFlags,
      kOrbitsCustomViewProperty, Custom {kDETUnused};
   }
};

PLANET INFORMATION PAGE TEMPLATES

When the user double-clicks a planet in the sublist, a window opens with two more information pages (Figure 2). The Orbit Calculation information page displays the position of the planet at a user-specified time. The Orbit Parameters information page displays, and lets the user enter, the values for the orbital parameters (shown earlier in Table 1). These two pages could have been combined, but most users aren't interested in seeing the orbital parameter values once they've been entered. They just clutter up the interesting information -- the planet's location at a given time.


Orbit Calculation

Orbit Parameters

Figure 2. Information pages for a planet

ORBITS RECORD ASPECT TEMPLATE

We define one aspect template for the orbits record (record type "hrc Orbits") -- a main aspect that also serves as the main view aspect for the orbits record information pages. The aspect for the orbits record contains the properties listed in Table 2.

The kOrbitsNowProperty property and the entries in the sublist are stored in the record, as specified by the 'dett' lookup table resource (shown below). You'll find the full source code for the orbits record aspect template on this issue's CD.

resource 'dett' (kOrbitsMainAspect+kDETAspectLookup, purgeable) {
   {
   {kOrbitsAttributeType}, typeBinary,
      useForInput, useForOutput, notInSublist, isNotAlias,
      isNotRecordRef,
      {
      'long', kOrbitsNowProperty, 0;
      };
   {kPlanetAttributeType}, 'plnt',
      notForInput, notForOutput, useInSublist, isNotAlias,
      isNotRecordRef,
      {};
   }
};

ASPECT TEMPLATE FOR ATTRIBUTE TYPE "HRC PLANET"

The aspect template for attribute type "hrc Planet" is also a main aspect template. The properties defined by this aspect are shown in Table 3. The orbital parameters, as well as the name of the attribute value (for example, "Mercury" or "Venus"), are stored in the attribute value, so they're included in the 'dett' resource:
#define kExtendedPropertyType 2
#define kExtendedPropertyTypeSize 10
...
resource 'dett' (kPlanetMainAspect+kDETAspectLookup, purgeable) {
   {
   {kPlanetAttributeType}, 'plnt',
      useForInput, useForOutput, notInSublist, isNotAlias,
      isNotRecordRef,
      {
      'rstr', kDETAspectName,    0;
      'btyp', kDETNoProperty,    kExtendedPropertyType;
      'blok', kTpProperty,       kExtendedPropertyTypeSize;
      'blok', kEpsilonProperty,  kExtendedPropertyTypeSize;
      'blok', kOmegaBarProperty, kExtendedPropertyTypeSize;
      'blok', keProperty,        kExtendedPropertyTypeSize;
      'blok', kaProperty,        kExtendedPropertyTypeSize;
      };
   }
};

Each of the properties in the 'dett' resource except kDETAspectName has a template-defined custom property type of 2 (kExtendedPropertyType) and is 10 (kExtendedPropertyTypeSize) bytes in size. The actual format is that of the standard SANE floating-point extended type. The 'btyp' element specifies that all subsequent 'blok' elements should produce properties of the type given (kExtendedPropertyType). The 'blok' elements that follow specify a fixed-size block, kExtendedPropertyTypeSize bytes in size. The next section describes how these property types get used.

As with the main aspect template for the orbits, the rest of this template is quite simple and is included on the CD.

CUSTOM PROPERTY TYPE CONVERSION

The templates we're defining use two property types that aren't supported directly by the CE: SANE floating-point extended, for orbital parameters and positions, and date/time, for specifying the time for which the positions should be calculated. In addition to using these property types for internal calculations, we want to display them and let the user edit them. To do this, we display the items in text fields and supply a code resource that translates between the internal representation of the custom property types and text (RStrings). The code resource implements convertToRString and convertFromRString when called by the CE. The part of the Planet routine that figures out when to call the conversion functions is as follows:
#define kTimePropertyType 1
#define kTimePropertyTypeSize 8
pascal OSErr Planet(DETCallBlockPtr callBlockPtr)
{
   if (callBlockPtr->protoCall.target.selector == kDETSelf)
      switch (callBlockPtr->protoCall.reqFunction) {
         ...
         case kDETcmdConvertToRString:
            return convertToRString(callBlockPtr);
         case kDETcmdConvertFromRString:
            return convertFromRString(callBlockPtr);
         ...
         }
   return kDETDidNotHandle;
}
In each case, the conversion function in the code resource first gets the type of the property being converted -- either kTimePropertyType or kExtendedPropertyType -- and then performs the conversion appropriate to that property type. The code in Listing 2 is for the convertToRString case; code for convertFromRString performs the opposite conversion, taking an RString and turning it into a custom property type.

Listing 2. Converting custom property types to a text string

OSErr convertToRString(DETCallBlockPtr callBlockPtr)
{
   DETConvertToRStringBlock*    ctrs;
   DETGetPropertyTypeBlock      gpt;

   ctrs = &(callBlockPtr->convertToRString);

   // Get the type of the property being converted.
   gpt.reqFunction = kDETcmdGetPropertyType;
   gpt.target = ctrs->target;
   gpt.property = ctrs->property;
   if (CallBackDET(callBlockPtr,
         (DETCallBackBlock*) &gpt) == noErr) {
      char             s[256];
      RStringHandle    h;

      // Convert time property types.
      if (gpt.propertyType == kTimePropertyType) {
         LongDateTime   ldt;
         char          tStr[256];

         // Get the current value.
         ldt = GetTimeProperty(callBlockPtr, ctrs->property);

         // Convert it to a string.
         iuldatestring(&ldt, shortDate, s, nil);
         tStr[0] = ' '; tStr[1] = 0;
         strcat(s, tStr);
         iultimestring(&ldt, true, tStr, nil);
         strcat(s, tStr);
         }
      // Convert floating-point extended property types.
      else if (gpt.propertyType == kExtendedPropertyType) {
         extended     n;
         decform      df;
         decimal      d;

         // Get the current value.
         n = GetExtendedProperty(callBlockPtr, ctrs->property);

         // Convert it to a string.
         df.style = FLOATDECIMAL;
         df.digits = 9;
         num2dec(&df, n, &d);
         dec2str(&df, &d, &s);
         }

      // If we don't know the type, don't convert it.
      else return kDETDidNotHandle;

      // Return the string as an RString handle.
      h = (RStringHandle) NewHandle(strlen(s) +
          sizeof(ProtoRString));
      if (h) {
         HLock((Handle) h);
         OCECToRString(s, smRoman, *h, strlen(s));
         HUnlock((Handle) h);
         ctrs->theValue = h;
         return noErr;
         }
      else return MemError();
      }

   return kDETDidNotHandle;
}
Two utility functions retrieve properties of the new types -- getTimeProperty and getExtendedProperty. Listing 3 shows getExtendedProperty (getTimeProperty is virtually identical).

Listing 3. getExtendedProperty

extended getExtendedProperty(DETCallBlockPtr callBlockPtr, 
                               short property)
{
   DETGetPropertyBinaryBlock   gpb;
   extended                     n;

   gpb.reqFunction = kDETcmdGetPropertyBinary;
   gpb.target = callBlockPtr->protoCall.target;
   gpb.property = property;
   if (CallBackDET(callBlockPtr, (DETCallBackBlock*) &gpb) != noErr)
      return 0.0;
   BlockMove(*gpb.propertyValue, (char*) &n, sizeof(n));
   DisposeHandle(gpb.propertyValue);
   return n;
}
The code shown in this section belongs to the aspect template for attribute type "hrc Planet." Similar code is used for the orbits record aspect template, but that template never needs to convert extended types -- they're always converted by the "hrc Planet" attribute type template -- so only the code for converting times is included.

The CE makes all the decisions about when to perform the conversions. When it needs to display a property in a text field, it calls the code resource to convert the property to text. When the user finishes editing a property and closes the field (by tabbing to the next field, pressing Enter, switching pages, or closing the window), the CE calls the code resource to convert the property from text to the internal type.

The CE knows what type a property is because the template tells it. In the case of properties stored in an attribute value, the 'dett' resource includes the type information, as discussed earlier in the section on the aspect template for attribute type "hrc Planet."

In the case of temporary properties not stored in an attribute value, for which there is no 'dett' entry, the code resource sets the type, generally while setting the property. For example, in the aspect template for attribute type "hrc Planet" the code resource initializes the Time field to the current time as a part of the instanceInit routine, which is invoked when the code resource is called with the kDETcmdInstanceInit routine selector (Listing 4).

Listing 4. Initializing the Time field in instanceInit

OSErr instanceInit(DETCallBlockPtr callBlockPtr)
   {
   DETSetPropertyTypeBlock      spt;
   DETSetPropertyBinaryBlock   spb;
   unsigned long               l;
   LongDateCvt                  ldt;

   // Set the time property type.
   spt.reqFunction = kDETcmdSetPropertyType;
   spt.target = callBlockPtr->protoCall.target;
   spt.property = kTimeProperty;
   spt.newType = kTimePropertyType;
   CallBackDET(callBlockPtr, (DETCallBackBlock*) &spt);

   // Set the time property to the current time.
   GetDateTime(&l);
   ldt.hl.lHigh = 0; ldt.hl.lLow = l;
   spb.reqFunction = kDETcmdSetPropertyBinary;
   spb.target = callBlockPtr->protoCall.target;
   spb.property = kTimeProperty;
   spb.newValue = (Ptr) &ldt;
   spb.newValueSize = sizeof(ldt);
   if (CallBackDET(callBlockPtr, (DETCallBackBlock*) &spb) ==
          noErr) {
      // Dirty the time property.
      DETDirtyPropertyBlock   dp;

      dp.reqFunction = kDETcmdDirtyProperty;
      dp.target = callBlockPtr->protoCall.target;
      dp.property = kTimeProperty;
      CallBackDET(callBlockPtr, (DETCallBackBlock*) &dp);
      }
}

CALCULATING POSITIONS AUTOMATICALLY

The aspect template for attribute type "hrc Planet" calculates the position of the planet at a specified time. It takes the time from kTimeProperty and puts the resulting position in kXProperty and kYProperty. This calculation, which is performed whenever kTimeProperty changes, is used in three places: in the Orbit Calculation information page of each "hrc Planet" attribute value; in the sublist on the List information page of the orbits record; and in calculating where to draw the planets on the Plot information page of the orbits record. If you want to create another template that implements a different type of celestial body -- using a different attribute value tag -- the same procedure would work, even though you may use an entirely different algorithm to calculate kXProperty and kYProperty from kTimeProperty. We're using the template as an object-oriented database: Each object (aspect) is of a specific class (aspect template), which specifies how it should react to certain messages (setting the kTimeProperty property). Portions of the object (properties) are persistent (stored in AOCE catalogs).

To calculate kXProperty and kYProperty from kTimeProperty, we supply code that responds to a kDETcmdPropertyDirtied call, as shown in Listing 5. Note that the code resource also recalculates kXProperty and kYProperty when any of the orbital parameters changes. The functions degsin and degcos are versions of sin and cos that take their parameters in degrees rather than radians. The constant kAU is the size of one astronomical unit (149,600,000.0 meters).

Listing 5. Calculating kXProperty and kYProperty from kTimeProperty

// Returns days (including fractions) since 1990.
extended daysSince1990(LongDateTime t)
{
    LongDateRec     ldr;
    LongDateTime        t1990;
    extended            et, et1990;

    et = t;
    ldr.ld.era = 0; ldr.ld.year = 1989; ldr.ld.month = 12; 
    ldr.ld.day = 31; ldr.ld.hour = 0; ldr.ld.minute = 0; 
    ldr.ld.pm = 0;
    LongDate2Secs(&ldr, &t1990);
    et1990 = t1990;
    return et/(24.0*60.0*60.0) - et1990/(24.0*60.0*60.0);
}
OSErr propertyDirtied(DETCallBlockPtr callBlockPtr)
{
   DETPropertyDirtiedBlock*   pd;

   pd = (DETPropertyDirtiedBlock*) &callBlockPtr->propertyDirtied;
   switch (pd->property) {
      // Recalculate only on selected properties.
      case kTimeProperty:
      case kTpProperty:
      case kEpsilonProperty:
      case kOmegaBarProperty:
      case keProperty:
      case kaProperty:
         {
         DETSetPropertyTypeBlock     spt;
         DETSetPropertyBinaryBlock   spb;
         extended                    d, tp, epsilon, omegaBar, e, a;
         extended                    n, m, l, v, r, x, y;

         // Get the orbital parameters.
         d = daysSince1990(GetTimeProperty(callBlockPtr,
                           kTimeProperty));
         tp = GetExtendedProperty(callBlockPtr, kTpProperty);
         epsilon = GetExtendedProperty(callBlockPtr,
                       kEpsilonProperty);
         omegaBar = GetExtendedProperty(callBlockPtr,
                       kOmegaBarProperty);
         e = GetExtendedProperty(callBlockPtr, keProperty);
         a = GetExtendedProperty(callBlockPtr, kaProperty);

         // If the parameters are zero, return zero.
         if (tp == 0.0) {
            x = 0.0; y = 0.0;
            }
         // Otherwise, calculate the current position.
         else {
            n = fmod((360.0/365.242191)*(d/tp), 360.0);
            m = n+epsilon-omegaBar;
            l = fmod(n+(360.0/pi())*e*degsin(m)+epsilon, 360.0);
            v = l-omegaBar;
            r = kAU*(a*(1.0-e*e))/(1.0+e*degcos(v));
            x = degcos(l)*r;
            y = degsin(l)*r;
            }

         // Prepare to set the type and value of the x and y
         // properties.
         spt.reqFunction = kDETcmdSetPropertyType;
         spt.target = pd->target;
         spb.reqFunction = kDETcmdSetPropertyBinary;
         spb.target = pd->target;
         // Set x's type.
         spt.property = kXProperty;
         spt.newType = kExtendedPropertyType;
         if (CallBackDET(callBlockPtr, (DETCallBackBlock*) &spt)
               == noErr) {
            // Set x's value.
            spb.property = kXProperty;
            spb.newValue = (Ptr) &x;
            spb.newValueSize = sizeof(x);
            CallBackDET(callBlockPtr, (DETCallBackBlock*) &spb);
            }

         // Set y's type.
         spt.property = kYProperty;
         spt.newType = kExtendedPropertyType;
         if (CallBackDET(callBlockPtr, (DETCallBackBlock*) &spt)
               == noErr) {
            // Set y's value.
            spb.property = kYProperty;
            spb.newValue = (Ptr) &y;
            spb.newValueSize = sizeof(y);
            CallBackDET(callBlockPtr, (DETCallBackBlock*) &spb);
            }
         
         return noErr:
         }
      }
   return kDETDidNotHandle;
}
The calculation in Listing 5 happens automatically when the user changes the Time field on the Orbit Calculation information page, or any of the orbital parameters on the Orbit Parameters page. But on the orbits record List information page, we need to do a little work to make each entry in the sublist change when the user changes the Time field on that page. The updateOrbitEntries routine sets the time for each item in the sublist by calling setSublistTimeProperty (Listing 6). The updateOrbitEntries routine iterates through the sublist until it gets an error return, which happens when it tries to reference an entry that doesn't exist -- the one just past the end of the list.

Listing 6. updateOrbitEntries and setSublistTimeProperty

OSErr updateOrbitEntries(DETCallBlockPtr callBlockPtr)
{
   LongDateTime   ldt;
   long            i;

   // Get the time from the Time field.
   ldt = getTimeProperty(callBlockPtr, kOrbitsTimeProperty);

   // Set the time in each sublist entry.
   for (i = 1;; i++)
      if (setSublistTimeProperty(callBlockPtr, kTimeProperty, i, ldt)
            != noErr)
         break;
   return noErr;
}

OSErr setSublistTimeProperty(DETCallBlockPtr callBlockPtr, 
          short property, long itemNumber, LongDateTime ldt)
{
   DETSetPropertyBinaryBlock    spb;
   OSErr                        retVal;

   spb.reqFunction = kDETcmdSetPropertyBinary;
   spb.target.selector = kDETSublistItem;
   spb.target.aspectName = nil;
   spb.target.itemNumber = itemNumber;
   spb.property = property;
   spb.newValue = (Ptr) &ldt; spb.newValueSize = sizeof(ldt);
   retVal = CallBackDET(callBlockPtr, (DETCallBackBlock*) &spb);
   if (retVal == noErr) {
      DETDirtyPropertyBlock   dp;
   
      dp.reqFunction = kDETcmdDirtyProperty;
      dp.target.selector = kDETSublistItem;
      dp.target.aspectName = nil;
      dp.target.itemNumber = itemNumber;
      dp.property = kOrbitsTimeProperty;
      retVal = CallBackDET(callBlockPtr, (DETCallBackBlock*) &dp);
      }
   return retVal;
}

DRAWING IN A CUSTOM VIEW

The CE calls the orbits record aspect template's code resource with the routine selector kDETcmdCustomViewDraw whenever the part of the Plot information page that contains the custom view needs redrawing. This can happen because the user has just flipped to that page, or because all or part of the page was uncovered -- perhaps because another window was moved out from in front of the orbits record window.
pascal OSErr Orbits(DETCallBlockPtr callBlockPtr)
{
   if (callBlockPtr->protoCall.target.selector == kDETSelf)
      switch (callBlockPtr->protoCall.reqFunction) {
         ...
         case kDETcmdCustomViewDraw:
            return customViewDraw(callBlockPtr);
         }
   return kDETDidNotHandle;
}
Listing 7 shows the calculations we need to perform before we can draw the custom view. First, we determine the view bounds. Given the bounds of the view, the template can then calculate the center of the display, which is where it draws the sun. Finally, the template determines a scaling factor such that the largest orbit will just fill the display. (Actually, with the algorithm we use, it may overflow the display a bit if the orbit is very elliptical.) After these preparations, the template can go through each of the items in the sublist and plot their current positions, names, and (if the Show Orbits checkbox is checked) orbits (Listing 8). Being able to call on the aspect template for attribute type "hrc Planet" to do most of the work greatly simplifies this process.

Listing 7. Preparing to draw the custom view

DETGetCustomViewBoundsBlock  gcvb;
OSErr                        retVal:
short                        halfWidth, halfHeight, centerX, centerY;
LongDateTime                 ldt;
long                         i;
extended                     x, y, largestDistance, scaleFactor;

// 1. Determine the view bounds.
// If this isn't for our view, ignore it.
if (callBlockPtr->protoCall.property != kOrbitsCustomViewProperty)
   return kDETDidNotHandle;

// Get the bounds of the view.
gcvb.reqFunction = kDETcmdGetCustomViewBounds;
gcvb.target = callBlockPtr->protoCall.target;
gcvb.property = callBlockPtr->protoCall.property;
retVal = CallBackDET(callBlockPtr, (DETCallBackBlock*) &gcvb);
if (retVal != noErr) return retVal;

// 2. Calculate the center of the display.
halfWidth = (gcvb.bounds.right - gcvb.bounds.left) / 2;
halfHeight = (gcvb.bounds.bottom - gcvb.bounds.top) / 2;
centerX = gcvb.bounds.left + halfWidth;
centerY = gcvb.bounds.top + halfHeight;

// Draw space.
PaintRect(&gcvb.bounds);

// Draw the sun.
ForeColor(whiteColor);
r.top = centerY - 4; r.bottom = centerY + 4;
r.left = centerX - 4; r.right = centerX + 4;
PaintOval(&r);

// 3. Determine the proper scaling factor.
// Get the time.
ldt = getTimeProperty(callBlockPtr, kOrbitsTimeProperty);

// Guess the maximum size.
largestDistance = 0.0;
for (i = 1;; i++) {
   extended  newDistance;

   if (getSublistPosition(callBlockPtr, i, ldt, &x, &y) != noErr)
      break;
   newDistance = sqrt(x*x + y*y);
   if (newDistance > largestDistance) 
      largestDistance = newDistance;
   }
scaleFactor = (halfHeight - 15) / largestDistance;
Listing 8. Drawing the custom view
DETGetPropertyRStringBlock        gpr;
long                              showOrbits;
Rect                              r;

// Plot each planet.
showOrbits = getNumberProperty(callBlockPtr,
    kOrbitsCustomViewProperty);
TextFont(kDETApplicationFont);
TextSize(9);
gpr.reqFunction = kDETcmdGetPropertyRString;
gpr.target.selector = kDETSublistItem;
gpr.target.aspectName = nil;
gpr.property = kDETPrName;

for (i = 1;; i++) {
   // Draw the body.
   if (getSublistPosition(callBlockPtr, i, ldt, &x, &y) !=
       noErr)
      break;
   r.top = centerY - ((short) rint(scaleFactor*y)) - 1;
   r.bottom = r.top + 3;
   r.left = centerX + ((short) rint(scaleFactor*x)) - 1;
   r.right = r.left + 3;
   PaintOval(&r);

   // Draw the name.
   gpr.target.itemNumber = i;
   if ((CallBackDET(callBlockPtr, (DETCallBackBlock*) &gpr) ==
         noErr) && ((*gpr.propertyValue)->dataLength < 256)) {
      HLock((Handle) gpr.propertyValue);
      MoveTo (r.right + 1,
           r.top < centerY ? r.top - 1 : r.bottom + 10);
      DrawString(((char*) &(*gpr.propertyValue)->dataLength)
           + 1);
      DisposeHandle((Handle) gpr.propertyValue);
      }

   // Show the orbit (if requested).
   if (showOrbits) {
      LongDateTime    ldtInc;
      extended       orbitInc;
      short          j;

      if (getSublistExtendedProperty(callBlockPtr, i, kTpProperty,
            &orbitInc) != noErr) 
         break;
      // orbitInc is calculated such that 36 of them produce a
      // complete one-year orbit.
      orbitInc *= (10.0*24.0*60.0*60.0);
      for (j = 36, ldtInc = ldt + orbitInc; j--;
           ldtInc += orbitInc) {
         if (getSublistPosition(callBlockPtr, i, ldtInc, &x, &y)
               != noErr)
            break;
         r.left = centerX + ((short) rint(scaleFactor*x));
         r.right = r.left + 1;
         r.top = centerY - ((short) rint(scaleFactor*y));
         r.bottom = r.top + 1;
         PaintRect(&r);
         }
      }
   }

// Return things to normal.
ForeColor(blackColor);
updateOrbitEntries(callBlockPtr);

BEYOND PLUTO

AOCE templates are extraordinarily elastic. You can use them to do all of the following:
  • show information such as users, addresses, file servers, and planets contained in local and remote catalogs

  • easily display text and integer information and, with a little work, display and let the user edit floating-point numbers, times, and virtually any other data type

  • display information as text, pictures, or any developer-defined custom view
In this article, we developed a set of templates to hold information about planets, to calculate the positions of the planets, and to plot the positions and orbits of those planets. This issue's CD contains records with entries for all nine known planets. More entries can be added as more planets are discovered in our solar system -- or in some other solar system. The planets supplied are divided into two records: inner planets and outer planets. If they're all placed in one record, the scaling of the orbit plots, forced by the size of the outer planet orbits, is such that the inner planets are squished too close together -- try it.

Some readers may wonder why we used AOCE templates for our planetary explorations rather than HyperCard, a desk accessory, or a full Macintosh application. Templates provide a lightweight solution, which doesn't require the support of a large application like HyperCard. Indeed, templates run within the Finder itself and leverage off its existing user interface code. Desk accessories are also lightweight, but we wanted permanent storage of the data, for which the AOCE catalog system is perfect.

There's plenty of room for extending these templates. Here are a few ideas:

  • Add the z coordinate -- see Practical Astronomy With Your Calculator for the appropriate formulas.

  • Add new types of celestial objects -- moons and comets for starters.

  • Add spacecraft as a type. Allow the user to set the acceleration vector of the ship.

  • Add a page to the orbits record that plots the planet's positions in the sky from a given location on Earth.

  • Add options to the existing Plot information page to allow the user to choose one of the planets as the center of the plot, rather than the sun.

  • Add a pop-up menu to one of the two information pages for the planet attribute values that selects the color to use when plotting that planet.
We hope you're inspired by this article to write templates for many other uses besides celestial ones. As you can see, AOCE templates provide capabilities well beyond supplying electronic mail addresses or browsing network devices.


    RECOMMENDED READING

    Practical Astronomy With Your Calculator, by Peter Duffett-Smith (Cambridge University Press, 1988). All the algorithms for the celestial mechanics used in the templates come from this excellent book.

    Inside Macintosh: AOCE Application Interfaces (Addison-Wesley, 1994).


HARRY R. CHESLEY There are two mysteries that have always -- well -- mystified Harry: (1) Why do mirrors exchange left and right but not top and bottom? (2) What is consciousness? Harry recently worked out the answer to the first question. You reverse the scene yourself by turning around to look through the mirror rather than directly at it. If you'd turned head-over-heels instead of around, the scene would be top and bottom exchanged but not right and left exchanged. Given this resolution, Harry feels the answer to the second question can't be far behind. Meanwhile, Harry works in Apple Online Services, doing Newton programming.

Thanks to our technical reviewers Paul Black, Dave Evans, and Bruce Gaya.

 

Community Search:
MacTech Search:

Software Updates via MacUpdate

Ember 1.8.3 - Versatile digital scrapboo...
Ember (formerly LittleSnapper) is your digital scrapbook of things that inspire you: websites, photos, apps or other things. Just drag in images that you want to keep, organize them into relevant... Read more
Apple iTunes 12.1 - Manage your music, m...
Apple iTunes lets you organize and play digital music and video on your computer. It can automatically download new music, app, and book purchases across all your devices and computers. And it's a... Read more
LibreOffice 4.4.3 - Free, open-source of...
LibreOffice is an office suite (word processor, spreadsheet, presentations, drawing tool) compatible with other major office suites. The Document Foundation is coordinating development and... Read more
FoldersSynchronizer 4.2.1 - Synchronize...
FoldersSynchronizer is a popular and useful utility that synchronizes and backs-up files, folders, disks and boot disks. On each session you can apply special options like Timers, Multiple Folders,... Read more
Simon 4.0.2 - Monitor changes and crashe...
Simon monitors websites and alerts you of crashes and changes. Select pages to monitor, choose your alert options, and customize your settings. Simon does the rest. Keep a watchful eye on your... Read more
Cocktail 8.1.2 - General maintenance and...
Cocktail is a general purpose utility for OS X that lets you clean, repair and optimize your Mac. It is a powerful digital toolset that helps hundreds of thousands of Mac users around the world get... Read more
Cyberduck 4.6.4 - FTP and SFTP browser....
Cyberduck is a robust FTP/FTP-TLS/SFTP browser for the Mac whose lack of visual clutter and cleverly intuitive features make it easy to use. Support for external editors and system technologies such... Read more
Herald 5.0.2 - Notification plugin for M...
Note: Versions 2.1.3 (for OS X 10.7), 3.0.6 (for OS X 10.8), and 4.0.8 (for OS X 10.9) are no longer supported by the developer. Herald is a notification plugin for Mail.app, Apple's Mac OS X email... Read more
DEVONthink Pro 2.8.3 - Knowledge base, i...
Save 10% with our exclusive coupon code: MACUPDATE10 DEVONthink Pro is your essential assistant for today's world, where almost everything is digital. From shopping receipts to important research... Read more
Boom 2 1.0.1 - System-wide pro audio app...
Boom 2 is a system-wide volume booster and equalizer app that is designed especially for OS X 10.10 Yosemite. It comes with a smart interface, self-calibrates itself according to your Mac, offers... Read more

Playworld Superheroes Review
Playworld Superheroes Review By Tre Lawrence on January 30th, 2015 Our Rating: :: HERO CRAFTINGUniversal App - Designed for iPhone and iPad It’s all about the imagination, fighting bad creatures — and looking good while doing so.   | Read more »
Join the SpongeBob Bubble Party in this...
Join the SpongeBob Bubble Party in this New Match 3 Bubble Poppin’ Frenzy Posted by Jessica Fisher on January 30th, 2015 [ permalink ] | Read more »
Handpick Review
Handpick Review By Jennifer Allen on January 30th, 2015 Our Rating: :: TANTALIZING SUGGESTIONSiPhone App - Designed for the iPhone, compatible with the iPad Handpick will make you hungry, as well as inspire you to cook something... | Read more »
Storm the Halls of Echo Base in First St...
Storm the Halls of Echo Base in First Star Wars: Galactic Defense Event Posted by Jessica Fisher on January 30th, 2015 [ permalink ] Universal App - Designed for iPhone and iPad | Read more »
Contradiction Review
Contradiction Review By Tre Lawrence on January 30th, 2015 Our Rating: :: SPOT THE LIEiPad Only App - Designed for the iPad Contradiction is a live action point and click adventure that’s pretty engaging.   Developer: Tim Follin... | Read more »
Unlock Sunshine Girl in Ironkill with th...
Unlock Sunshine Girl in Ironkill with this special 148Apps code Posted by Rob Rich on January 29th, 2015 [ permalink ] Robo-fighter Ironkill has been out on iOS a | Read more »
Crossroad Zombies Review
Crossroad Zombies Review By Jordan Minor on January 29th, 2015 Our Rating: :: CROSSWALKING DEADiPad Only App - Designed for the iPad Crossroad Zombies is a rough draft of a cool genre mash-up.   | Read more »
Blood Brothers 2 – Tips, Cheats, and Str...
War is hell: Is it the kind of hell you want to check out? Read our Blood Brothers 2 review to find out! Blood Brothers 2, DeNA’s follow-up to the original Blood Brothers, is an intriguing card collecting / role-playing / strategy hybrid. There’s... | Read more »
Blood Brothers 2 Review
Blood Brothers 2 Review By Nadia Oxford on January 29th, 2015 Our Rating: :: AN AGGRAVATING RELATIVEUniversal App - Designed for iPhone and iPad Blood Brothers 2 is built on a simple, solid foundation, but its free-to-play system... | Read more »
I AM BREAD, the Toast of the Town, is Ro...
Have you ever dreamt of being deliciously gluten-y? Do you feel passionate about Rye and Wheat? The guys at Bossa Studios do and that is why they are bringing I AM BREAD to iOS soon. The loafy app will feature all the new content that is being... | Read more »

Price Scanner via MacPrices.net

Apple Becomes World’s Largest Smartphone Vend...
According to the latest research data from Strategy Analytics, as global smartphone shipments grew 31 percent annually to reach a record 380 million units in the fourth quarter of 2014. Apple became... Read more
Cut the Cord: OtterBox Resurgence Power Case...
Dead batteries and broken phones are two of the biggest issues for smartphone users today. Otterbox addresses both with the new Resurgence Power Case for Apple iPhone 6, promising to make those panic... Read more
13-inch Retina MacBook Pros on sale for up to...
B&H Photo has 13″ Retina MacBook Pros on sale for $200 off MSRP. Shipping is free, and B&H charges NY sales tax only: - 13″ 2.6GHz/128GB Retina MacBook Pro: $1199.99 save $100 - 13″ 2.6GHz/... Read more
15-inch 2.5GHz Retina MacBook Pro on sale for...
 B&H Photo has the 15″ 2.5GHz Retina MacBook Pro on sale for $2319.99 including free shipping plus NY sales tax only. Their price is $180 off MSRP, and it’s the lowest price available for this... Read more
Back in stock: Refurbished iPod nanos for $99...
The Apple Store has Apple Certified Refurbished 16GB iPod nanos available for $99 including free shipping and Apple’s standard one-year warranty. That’s $50 off the cost of new nanos. Most colors are... Read more
Apple lowers price on refurbished 256GB MacBo...
The Apple Store has lowered prices on Apple Certified Refurbished 2014 MacBook Airs with 256GB SSDs, now available for up to $200 off the cost of new models. An Apple one-year warranty is included... Read more
New Good Management Suite Simplifies Enterpri...
Good Technology has announced the availability of the Good Management Suite, a comprehensive cross-platform solution for organizations getting started with mobile business initiatives. Built on the... Read more
15-inch 2.0GHz Retina MacBook Pro (refurbishe...
The Apple Store has Apple Certified Refurbished previous-generation 15″ 2.0GHz Retina MacBook Pros available for $1489 including free shipping plus Apple’s standard one-year warranty. Their price is... Read more
15-inch 2.5GHz Retina MacBook Pro on sale for...
Amazon has the 15″ 2.5GHz Retina MacBook Pro on sale for $2319.99 including free shipping. Their price is $180 off MSRP, and it’s the lowest price available for this model from any reseller. Read more
iPad Turns Five – The ”Book Mystique
Five years ago this week, the late Steve Jobs took the stage at an Apple special press event to unveil the first Apple iPad — a slab-shaped, hand-holdable device that was to shake the personal... Read more

Jobs Board

At-Home Chat Specialist- *Apple* Online Stor...
**Job Summary** At Apple , we believe in hard work, a fun environment, and the kind of creativity and innovation that only comes about when talented people from diverse Read more
SW QA Engineer - *Apple* TV - Apple (United...
**Job Summary** The Apple TV team is looking for experienced Quality Assurance Engineers with a passion for delivering first in class home entertainment solutions. **Key Read more
*Apple* Retail - Multiple Positions(US) - Ap...
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* Systems Engineer - Pre Sales, Educat...
…is responsible for proactively providing technical expertise to drive sales of Apple solutions into assigned accounts. The SE architects, validates, and assists in Read more
*Apple* Solutions Consultant - Retail Sales...
As an ambassador of the Apple brand, the ASC is accountable for driving sales performance by: Connecting with customers. Discovering customers' needs and values. Showing Read more
All contents are Copyright 1984-2011 by Xplain Corporation. All rights reserved. Theme designed by Icreon.