Printing

There's a short answer for this question, but it's preceeded by a long dissertation on how printing works in Magic Cap.

When the user taps the print button in the Magic Lamp, one of the things that is done is the list of things that can be printed is constructed. This is done by calling the MakeContentProxyChoices() operation of the current scene. If you want to add choices to this list, you need subclass Scene and override MakeContentProxyChoices(). The key thing you need to do in this method is to call NewContentProxy(), which creates an alias to the thing that is to be printed. You would pass the actual thing to print as the target parameter to NewContentProxy().

When the user taps the print button in the print window, PrintWindow_Print is called, which ultimately creates a print job from the content proxy and adds it to the print queue by calling PrinterQueue_AddToSendQueue. This operation starts up the render server actor and the print server actor.

The render server performs the job of creating the image that is to be printed. It ultimately calls Viewable_Render (which in turn calls Draw()) on the target of the content proxy on the to do the drawing. The print server takes the rendered image and sends it out to the printer, handling the communication with the printer. This is sort of analogous to a print driver on the Mac.

After that long winded explanation on the inner workings of Magic Cap printing, all you need to do to is simply create a viewable that is 8 1/2" by 11" and make it the target of a content proxy object.

Here's a code snippet that makes a text field that re-flows its contents for printing and faxing.

Method void
PrintingScene_MakeContentProxyChoices(ObjectID self, ulong usageType,
                                      ObjectID list)
{
   // Call InheritedMakeContentProxyChoices to allow the
   // Scene_MakeContentProxyChoices to add the screen as a printing option.
   InheritedMakeContentProxyChoices(self, usageType, list);
 
   // usageType specifies whether the user pressed print, fax, beam or mail.
   // Only allow printing and faxing the contents of this scene.
   switch (usageType) {
      case contentPrint:
      case contentFax: {
         ObjectID contentDescriptionText;
         ObjectID contentProxy;
   
   // Create the string that appears under the printing choice.
         contentDescriptionText = NewTransient(Text_, nil);
         ReplaceTextWithString(contentDescriptionText, "\pyour text");
   
   // Create the content proxy. The viewable returned by
   // NewTextFieldForPrinting() is the viewable (along with its subviews) that
   // will get printed or faxed.
         contentProxy = NewContentProxy(self, contentDescriptionText, 1, 
                                        NewTextFieldForPrinting(),
                                        iTextProxyImage, 0);

   // NewContentProxy made a copy of our description text, so we can destroy
   // ours now.
         Destroy(contentDescriptionText);
   
   // Remember the usageType
         SetUsageType(contentProxy, usageType);

   // Add the content proxy to the list of things to print or fax.
         AddLast(list, contentProxy);
         break;
      }
   }
}

Is there a quick way to find out how many PixelMaps to expect in a print job?

There will always be only one PixelMap per print job. The user can print more than one card at a time if the card is in a stack of cards. As an example, if you go to the library and open a book, then print the book, you will get the option to print the page of the book that is showing, or the entire book. However, all the pages are streamed into the one PixelMap that the print job refers to; for each viewable, RenderIntoViewable() will be called, which renders the viewable into the print stream.