home *** CD-ROM | disk | FTP | other *** search
/ vsiftp.vmssoftware.com / VSIPUBLIC@vsiftp.vmssoftware.com.tar / FREEWARE / FREEWARE40.ZIP / xpaint-247 / doc / operator.doc < prev    next >
Text File  |  1996-06-25  |  3KB  |  72 lines
  1. This is a "rough" document, but hopefully if you are interested in
  2. adding a new paint operator to xpaint, it should make a good 
  3. staring point.
  4.  
  5. The interface to add new functions is as follows, all operations have
  6. two functions named (where OP == Function name, ## == concatination):
  7.     void *    OP ## Add(Widget w)
  8.     void    OP ## Remove(Widget w, void *local)
  9.  
  10. Thus for the Pencil operation you have a PencilAdd() and PencilRemove()
  11. function.  Then what is needed is add a two lines to Operation.c, one
  12. of GENERATE_OP( OP ), and a entry in the iconList[] table for the icon
  13. that is displayed for the operation.
  14.  
  15. Your Add method is expected to return a pointer to whatever local 
  16. instance information that your operator might need to keep track of,
  17. which is the argument into the Remove method.  Also, usually I
  18. use this data pointer are the information to pass into the event
  19. methods as well.
  20.  
  21. Events handlers are added using the:
  22.     OpAddEventHandler(Widget, surface, mask, flag, function, data)
  23. and OpRemoveEventHandler() is used to remove them.  The Widget
  24. argument should be the same ass the Widget passed into the add
  25. function.  The surface argument is weather you want events on either
  26. the Window or the Pixmap, or both (you still are required to update
  27. the Window if you arn't zoomed).
  28.  
  29. The first thing your operator should do before it changes the drawable
  30. is call UndoStart{Point,Rectangle}, which will cause a new undo
  31. buffer to be allocated for your operator.  
  32.  
  33. Operators are passed an info structure, important parts are:
  34.     isFat        Boolean
  35.         -- the XtWindow() is zoomed, you should only
  36.            draw on the window if you know how, when 
  37.            this is set.
  38.     surface        OpSurface == enum { opPixmap, opWindow }
  39.         -- what surface you are being called with
  40.            either the backing store pixmap or the
  41.            actuall window
  42.     drawable    Drawable (either the window or pixmap)
  43.         -- what the drawable ID is, this in only valid
  44.            after the call to UndoStart()
  45.     filled_gc    GC
  46.         -- the graphic context you should use for
  47.            all your drawing operations.
  48.     x, y        int
  49.         -- The x and y position of the event,
  50.            these may be in the zoomed coordinate
  51.            on the Window, while they will always
  52.            be the real x, y for the Pixmap.
  53.     realX, realY    int
  54.         -- The real x and y position of the event, if 
  55.            gridding is on x,y is modified by the gridding 
  56.            factor.  This only should be used in rare cases 
  57.            where it is non-sensical to pay attention to the 
  58.            grid factor (ie flood fill).
  59.     zoom         int
  60.         -- the current zoom factor, if isFat is True.
  61.  
  62. The XtNcompress value for the paint widet controlles wheather
  63. or not motion events are compressed into a single event if
  64. possible. Thus:
  65.     XtVaSetValues(w, XtNcompress, False, NULL);
  66. says that your operator is interested in all motion events
  67. (ie. the pencil, or paint brush).
  68.  
  69. Generally, if you look at the operators that I have
  70. provided there is probably an example of every attrocity that
  71. I might be able to think of using the above information.
  72.