Newton Developer Technical Information: Newton Programmer's Guide: 2.1 OS Addendum /

Chapter 2 - Newton Works Draw Application / Using the Drawing Application Interface

Adding Custom Drawing Tools

You can add tools to the Draw application. These tools allow the user to create new types of draw objects. Note that in many cases, it makes more sense to create new graphic objects as bitmaps via the stamp interface; see "Adding Stamps to the Stamp Tool".

Tools are added by calling the Draw application viewDef *RegTool method. Each new tool is added to the end of the toolbar. The toolbar grows off the right end of the screen, if enough tools are added.

Tools are based on the *protoDrawTool frame. You are required to supply the following:

• an icon to display in the toolbar
• a class symbol that identifies the tool and the object it creates
• a *MakeObject method that returns a graphic shape to add to the canvas
• a *SetAttribute method to respond to the user selecting, and perhaps modifying the object

The object created should be a shape array with the same class as the tool. This array should have a style frame at the front to make sure you get the drawing environment you want. The last two objects in the array should be an "invisible" style and a rectangle shape. The rectangle should be the size of the shape you are returning, and the style frame should be:

 {penSize: 0, fillPattern: vfNone, selection: nil}

This rectangle at the end of your shapes array is for the selection handles.

The default behavior of *protoDrawTool is to draw a bounding box as the user drags the pen across the screen. This creates a bounds box which is passed to the tool's *MakeObject method. You can override this behavior in a number of ways.

If it makes more sense to create the object with a tap, instead of by dragging a bounding box, set the tool's createByTapping slot to true, and its createByDragging slot to nil. The stamp tool, for example, creates its objects with pen taps.

You may also draw something other than a rectangle as the user drags the bounding box. The oval tool, for example, draws an oval as the bounding box is being created. To draw your own object, set your tool's dragARectangle slot to nil, and optionally provide a *MakeDragObject method. The *MakeDragObject method is called to return a shape as the bounding box is being dragged. The default version of this method simply sends your tool a *MakeObject message. If the objects your tools creates are very complicated, you may want to create a simpler object here. Your *MakeDragObject method could return the outline of your object, for example.

The example below creates a simple tool that makes a shape comprised of an equal size oval and rectangle.

Listing 2-1 Adding a tool to the Draw application's tool bar

 OpenResFile(Home & "resources");

DefineGlobalConstant ('kToolIcon , 
      MakePixFamily ( nil, nil, {rsrcSpec:"toolIcon", bitdepth:1}) );
CLoseResFile();

DefineGlobalConstant('kMyDrawToolTemplate,
{  _proto: UR('|Draw:NEWTON|, 'protoDrawTool), // get proto from unit
   class : '|OvalRect:MySig|,
   icon  : kToolIcon,
   MakeObject : func (left,top,right,bottom,style) 
   begin
      local l := Min(left,right), r := Max(left,right),
            t := Min(top,bottom), t := Max(top,bottom);
      local oval := MakeOval (l,t,r,b);
      local rect := MakeRect (l,t,r,b);
      local mainStyle := Clone(style);
      mainStyle.selection := nil;
      
      [|OvalRect:MySig|:
         mainStyle,
         rect,
         oval,
         { penSize:0, fillPattern:vfNone, selection:nil }, 
         rect,
      ];
   end,

   SetAttribute : func ( shape, attribute, newValue )
   begin
      //selection handles go on the invisible rect.
      if attribute = 'selection then
         shape[3] . selection := newValue;
      else shape[0].(attribute) := newValue;
   end
});

InstallScript := func(partFrame, removeFrame)
begin
   local viewDef := GetViewDefs('drawPaper).default;
   local sym := EnsureInternal(kAppSymbol);
   if viewDef  then
      viewDef:RegTool(sym, kMyDrawToolTemplate);
end;

RemoveScript := func (removeFrame) 
begin
   local viewDef := GetViewDefs('drawPaper).default;
   if viewDef then
      viewDef:UnRegPatterns(kAppSymbol);
 end;