GrafEdit - Funnels

Funnels

Funnels are a passive iterator for processing enumerated graphics. TCanvasView::EnumerateGraphics calls the ProcessGraphic function of the funnel. This function is called for each graphic that is enumerated in the order the filter provides them.

Boolean TCanvasGraphicFunnel::ProcessGraphic( const MCanvasGraphic& );

You write funnel derived classes and override the ProcessGraphic function to add the behavior for processing each graphic that you want; for example, drawing each graphic, hit detection, or whatever, on each graphic.

ProcessGraphic returns False to terminate enumeration before all graphics have been processed. For example, when the processing involves hit detection, ProcessGraphic returns False as soon as a hit is detected to avoid processing all graphics.

Pointers to graphics and graphic IDs

ProcessGraphic takes a constant reference to the graphic because the canvas graphics passed to it do not persist beyond the scope of the function. If, for some reason, the graphics must persist beyond the scope of the function, you should override this function and define it to take the ID of the canvas graphic instead. Some funnels use the ProcessGraphic function to create another instance of something that persists beyond the scope of ProcessGraphic. One example is TCanvasInteractionFunnel that calls the graphic to create an interactor.

Funnels cannot change graphics, should not retain pointers to graphics, and might do such things as call constant functions and copy graphics.

Because funnels provide readonly graphic access, they should never retain pointers to canvas graphics that are passed to them. For example, a funnel to find the canvas graphic interactor given a point will hit detect each canvas graphic that is passed to it until one succeeds. The funnel requests this graphic to create an interactor and retain the interactor, not the graphic, for its client to extract later.

Retaining a canvas graphic pointer would be catastrophic if the graphic were a selection graphic because selection graphics are created as needed by the selection filter and destructed by the filter after the funnel has processed them.

Derived classes

TCanvasGraphicFunnel is abstract. GrafEdit provides the following drawing, hit detection, interaction, and selection concrete funnel classes.

Drawing

TCanvasDrawingFunnel( TGrafPort* referencePort );

This funnel is constructed from a drawing port (TGrafPort) and draws each graphic passed to it into this port.

Hit detection

  TCanvasHitDetectionFunnel( const TGPoint& hitLocation );
  TCanvasGraphicID GetHitGraphicID() const;

This funnel is constructed from a TGPoint hit location and calls the MCanvasGraphic::Hit function on each graphic passed to it until one succeeds. After EnumerateGraphics returns, clients can call GetHitGraphicID to get the ID of the hit graphic.

Interaction

  TCanvasInteractionFunnel(   MCanvasSelection* adoptSelection, MToolHandler* toolHandler,

const TGPoint& hitLocation );
  TCanvasInteractor* OrphanInteractor();

This funnel is constructed from a TGPoint hit location, canvas selection and a tool handler. It calls the MCanvasGraphic::Hit function on each graphic passed to it until one succeeds. Once a hit is detected, TCanvasInteractionFunnel calls the MCanvasGraphic::CreateInteractor and adopts the interactor returned. After EnumerateGraphics returns, clients can call OrphanInteractor to obtain the interactor that was created, if any.

The MCanvasSelection and MToolHandler parameters are for creating the interactor, which is described in Chapter 7, "Commands, interactors, and cursor tools."

Selection

TCanvasRectSelectionFunnel( const TGRect&, MCanvasSelection& );

This funnel is constructed from a rectangle and a canvas selection. It calls MCanvasSelection::SelectGraphic on the selection for each graphic it is passed that is also completely contained within the rectangle. The funnel references (does not own) the selection. The client creates and owns the selection and uses the modified selection after EnumerateGraphics returns.

[Contents] [Previous] [Next]

Click the icon to mail questions or corrections about this material to Taligent personnel.

Generated with WebMaker