home *** CD-ROM | disk | FTP | other *** search
/ AmigActive 13 / AACD13.ISO / AACD / Graphics / PPT / Docs / support.doc < prev    next >
Text File  |  2000-02-06  |  46KB  |  1,639 lines
  1. TABLE OF CONTENTS
  2.  
  3. pptsupport/--background--
  4. pptsupport/AddExtension
  5. pptsupport/AskReqA
  6. pptsupport/ClearProgress
  7. pptsupport/CloseProgress
  8. pptsupport/CopyFrameData
  9. pptsupport/DupFrame
  10. pptsupport/FindExtension
  11. pptsupport/FindFrame
  12. pptsupport/FinishProgress
  13. pptsupport/GetBackgroundColor
  14. pptsupport/GetBitMapRow
  15. pptsupport/GetNPixelRows
  16. pptsupport/GetOptions
  17. pptsupport/GetPixel
  18. pptsupport/GetPixelRow
  19. pptsupport/InitFrame
  20. pptsupport/InitProgress
  21. pptsupport/MakeFrame
  22. pptsupport/ObtainPreviewFrameA
  23. pptsupport/PlanarToChunky
  24. pptsupport/Progress
  25. pptsupport/PutNPixelRows
  26. pptsupport/PutOptions
  27. pptsupport/PutPixel
  28. pptsupport/PutPixelRow
  29. pptsupport/ReleasePreviewFrame
  30. pptsupport/RemFrame
  31. pptsupport/RemoveExtension
  32. pptsupport/RenderFrame
  33. pptsupport/SPrintF
  34. pptsupport/SetErrorCode
  35. pptsupport/SetErrorMsg
  36. pptsupport/SetRexxVariable
  37. pptsupport/StartInput
  38. pptsupport/StopInput
  39. pptsupport/TagData
  40. pptsupport/--background--                              pptsupport/--background--
  41.  
  42.                   PPT support library documentation
  43.  
  44.                   $VER: pptsupport.doc 6.0 (02-Oct-99)
  45.  
  46.     Please note that all functions expect to have a valid PPTBase * in
  47.     A6 upon entering the function. Otherwise, these are just like
  48.     any other library functions, except that there are no stack-based
  49.     versions. If your compiler does not support registerized parameters,
  50.     tough luck.
  51.  
  52.  
  53. pptsupport/AddExtension                                  pptsupport/AddExtension
  54.  
  55.    NAME
  56.         AddExtension -- Add one extension to a frame (V3)
  57.  
  58.    SYNOPSIS
  59.         success = AddExtension( frame, name, data, len, flags );
  60.  
  61.         PERROR AddExtension( FRAME *, STRPTR, APTR, ULONG, ULONG )
  62.         D0                   A0       A1      A2    D0     D1
  63.  
  64.    FUNCTION
  65.         Adds a transparent extension to the image.  For example, you
  66.         could use this to save Author information for an image.
  67.  
  68.         Extensions are collectively deleted during exiting PPT.  If you
  69.         specify an existing extension, the old one is unceremoniously
  70.         deleted.
  71.  
  72.  
  73.    INPUTS
  74.         frame - the frame handle.
  75.         name - a NUL-terminated string that is an unique identifier
  76.             for your option chunk.  The name is case-sensitive. PPT
  77.             understands and uses the following pre-defined names:
  78.  
  79.             EXTNAME_AUTHOR - A string that contains author data.
  80.             EXTNAME_ANNO - An annotation string.
  81.             EXTNAME_DATE - A date string.
  82.  
  83.             Note that if you use any of these, you should also set
  84.             the EXTF_CSTRING flag...
  85.  
  86.         data - pointer to your data.
  87.         len  - length of your data chunk.
  88.         flags - flags that describe the format of this data chunk.
  89.             Possible values are:
  90.  
  91.             EXTF_PRIVATE - The format is private and PPT will not
  92.                 even try to guess it.
  93.             EXTF_CSTRING - this extension is a standard C format
  94.                 string with a NUL at the end.  PPT will allow editing
  95.                 this kind of extension in the edit window.
  96.  
  97.             As always, all unused bits should be set to zero.
  98.  
  99.    RESULT
  100.         success - PERR_OK if everything went OK and extension was
  101.             successfully saved in memory, PERR_OUTOFMEMORY, if
  102.             there was not enough memory to save the extension.
  103.  
  104.    EXAMPLE
  105.  
  106.    NOTES
  107.         This function allocates new space for each data item and
  108.         copies your data to a safe location.  Please note that it is
  109.         quite unhealthy to save pointers to your own data.
  110.  
  111.    BUGS
  112.         Extensions are not yet used too much.
  113.  
  114.    SEE ALSO
  115.         GetOptions(),PutOptions(),FindExtension()
  116.  
  117. pptsupport/AskReqA                                            pptsupport/AskReqA
  118.  
  119.    NAME
  120.         AskReqA -- Query the user for some values
  121.         AskReq -- Varargs version
  122.  
  123.    SYNOPSIS
  124.         error = AskReqA( frame, objectlist );
  125.         D0               A0     A1
  126.  
  127.         PERROR AskReqA( FRAME *, struct TagItem * );
  128.  
  129.         error = AskReq( PPTBase, frame, tag1, ... )
  130.  
  131.         PERROR AskReq( struct PPTBase *, FRAME *, Tag, ... )
  132.  
  133.    FUNCTION
  134.         Show a configurable requester to ask the user for some values.
  135.  
  136.    INPUTS
  137.         frame - as usual. May be NULL.
  138.         objs - a pointer to an array of TagItems, which contain
  139.             the object data. The following tags are allowed:
  140.  
  141.             AR_Text - A piece of text to be shown to the user. English
  142.                 default is "Change values:". You may use any BGUI control
  143.                 sequences here.
  144.  
  145.             AR_Positive - Text for the gadget for a positive answer.
  146.                 English default is "Ok".
  147.  
  148.             AR_Negative - Text for the gadget for a negative answer.
  149.                 English default is "Cancel".  If the negative tag
  150.                 is specified, but set to NULL or to an empty string,
  151.                 the window will have only the positive gadget.
  152.  
  153.             AR_Title - Title for the requester window. English default is
  154.                 "PPT Request".
  155.  
  156.             AR_HelpText (STRPTR) - A help text that is shown in a separate
  157.                 requester when the user presses HELP.  This requester is
  158.                 synchronous.  Default is NULL.
  159.  
  160.             AR_HelpNode (STRPTR) - The Amigaguide node that is to be shown
  161.                 in the help window when the user presses HELP.  This help
  162.                 is asynchronous.  Default is NULL.
  163.  
  164.                 Note that both AR_HelpText and AR_HelpNode are shown globally
  165.                 for the window, if there are no object-specific help
  166.                 texts defined.  See below for AROBJ_HelpText and
  167.                 AROBJ_HelpNode.
  168.  
  169.         You may also specify an object type for creation. These are handled
  170.         in the order they appear in. The ti_Data field should point to an
  171.         array of TagItems, which should contain more information on the
  172.         object. If you do not state any objects, you will get a simple
  173.         boolean Yes/No -type requester.
  174.  
  175.         You may choose from these objects:
  176.  
  177.         AR_SliderObject - Creates a slider object that has also an integer
  178.             gadget associated. Labels are placed on the left side. Available
  179.             attributes are:
  180.  
  181.             ARSLIDER_Min
  182.             ARSLIDER_Max - Minimum and maximum value for the slider. Defaults
  183.                 are 0 and 100, respectively.
  184.  
  185.             ARSLIDER_Default - Starting value. Default is 50.  If this tag
  186.                 does not exist, the default is taken from wherever
  187.                 AROBJ_Value happens to be pointing at.
  188.  
  189.             The AROBJ_Value field will contain the slider value on return.
  190.  
  191.         AR_StringObject - Create a string gadget. Available attributes
  192.             are:
  193.  
  194.             ARSTRING_MaxChars (ULONG) - Maximum length of the string
  195.             ARSTRING_InitialString (STRPTR) - A pointer to the initial string
  196.                 to be displayed in the gadget.
  197.  
  198.             The AROBJ_Value - field should point to a buffer containing
  199.             space for at least ARSTRING_MaxChars characters.
  200.  
  201.         AR_CheckBoxObject - Create a checkbox.  Available attributes
  202.             are:
  203.  
  204.             ARCHECKBOX_Selected (BOOL) - TRUE, if the original state is
  205.                 selected; FALSE otherwise.  If this tag does not exist,
  206.                 the default is taken from the AROBJ_Value field.
  207.  
  208.             The AROBJ_Value - field is set upon return to != 0, if the
  209.             gadget was set, 0 otherwise.
  210.  
  211.         AR_CycleObject - Create a cycle (popmenu) object.  Available
  212.             attributes are:
  213.  
  214.             ARCYCLE_Labels (STRPTR *) - pointer to a NULL-terminated array
  215.                 of strings, containing the labels of different choices.
  216.  
  217.             ARCYCLE_Active (LONG) - which one of the choices should be active
  218.                 upon startup.  Defaults to whatever AROBJ_Value field
  219.                 is currently pointing at.
  220.  
  221.             ARCYCLE_Popup (BOOL) - TRUE, if the cycle object should be
  222.                 a popup menu variant.  Default is FALSE.
  223.  
  224.             The AROBJ_Value is set upon return to the currently active
  225.             selection.
  226.  
  227.         AR_MxObject - Create a mx (radiobutton) object.  Available
  228.             attributes are:
  229.  
  230.             ARMX_Labels (STRPTR *) - pointer to a NULL-terminated array
  231.                 of strings, containing the labels of different choices.
  232.  
  233.             ARMX_Active (LONG) - which one of the choices should be active
  234.                 upon startup.  Defaults to whatever AROBJ_Value field
  235.                 is currently pointing at.
  236.  
  237.             The AROBJ_Value is set upon return to the currently active
  238.             selection.
  239.  
  240.         AR_FloatObject - Creates a string gadget which accepts only
  241.             floating point values.  It also attaches a slider next to it.
  242.             Available attributes are:
  243.  
  244.             ARFLOAT_Min (LONG) - The minimum allowed value for the gadget.
  245.                 Default is -100 (-1.0).
  246.  
  247.             ARFLOAT_Max (LONG) - The maximum allowed value for the gadget.
  248.                 Default is 100 (1.0).
  249.  
  250.             ARFLOAT_Default (LONG) - The startup value.  Default is 0.
  251.  
  252.             ARFLOAT_FormatString (STRPTR) - How the string gadget's contents
  253.                 should be formatted.  See printf(1) for more information.
  254.                 Default is ".3f".
  255.  
  256.             ARFLOAT_Divisor (LONG) - The divisor by which all values will
  257.                 be divided.  Default is 100.
  258.  
  259.             The float gadget uses long integers instead of floats because
  260.             the values are passed in a tag array.  To simplify casting
  261.             problems, I adopted this methodology.
  262.  
  263.             The result is a long, which should be divided by the divisor
  264.             before acting on it.  Note that the divisor also defines
  265.             the minimum value by which the knob of the slider can be moved
  266.             and also the minimum resolution of the gadget.
  267.  
  268.             NB: If you use too large values, you'll get into the roundoff
  269.             error hell.  Try to keep your numbers below 65535.
  270.  
  271.         You may also specify these common attributes for any objects:
  272.  
  273.             AROBJ_Label (STRPTR) - A label for this object.
  274.  
  275.             AROBJ_Value (ULONG *) - This points to a location in which
  276.                 the value from the gadget is written if the user
  277.                 selected the positive answer.
  278.  
  279.             AROBJ_HelpText (STRPTR) - Pointer to a nul-terminated string,
  280.                 which will be shown in a simple requester when the user
  281.                 presses the HELP key over the object.  Use this
  282.                 for short help-texts.
  283.  
  284.             AROBJ_HelpNode (STRPTR) - Pointer to a standard C string,
  285.                 which contains the file and node of an AmigaGuide help
  286.                 text.  For example, you could say something like:
  287.  
  288.                 AROBJ_HelpNode, "HELP:mymodule.guide/Twiddle",
  289.  
  290.                 and PPT would try to locate a guide called "mymodule.guide"
  291.                 in directory "HELP:" and display the node called "Twiddle"
  292.                 from it.
  293.  
  294.                 The node is displayed when the user presses the HELP key over
  295.                 this gadget.
  296.  
  297.    RESULT
  298.         error - Standard PPT error code. If the user chose Cancel,
  299.             this will be PERR_CANCELED. If everything went OK, then
  300.             this will be PERR_OK.
  301.  
  302.             Ctrl-C signals are recognised correctly and a PERR_BREAK
  303.             is returned. If this happens, exit as soon as you can
  304.             from your module.
  305.  
  306.    EXAMPLE
  307.         This opens up a simple window with two sliders.
  308.  
  309.         void TestAR() {
  310.             LONG foo2, foo3;
  311.             struct TagItem myslider[] = { /* Use defaults for this slider */
  312.                 AROBJ_Label, "%",
  313.                 AROBJ_Value, &foo2,
  314.                 TAG_END
  315.             };
  316.  
  317.             struct TagItem myslider2[] = {
  318.                 ARSLIDER_Min, -100,
  319.                 ARSLIDER_Max, 100,
  320.                 ARSLIDER_Default, 0,
  321.                 AROBJ_Value, &foo3,
  322.                 TAG_END
  323.             };
  324.  
  325.             struct TagItem mywindow[] = {
  326.                 AR_Title, "AR Test Window",
  327.                 AR_Text, ISEQ_C"\nPlease do tamper around with\n"
  328.                                "the sliders...\n",
  329.                 AR_Positive, "Cool",
  330.                 AR_Negative, "Not Cool",
  331.                 AR_SliderObject, myslider,
  332.                 AR_SliderObject, myslider2,
  333.                 TAG_END
  334.             };
  335.  
  336.             if(AskReqA( NULL, mywindow ) == PERR_OK) {
  337.                 /* User chose "Cool" */
  338.                 PDebug("Slider 1 = %ld\n", foo2);
  339.                 PDebug("Slider 2 = &ld\n", foo3);
  340.             }
  341.         }
  342.  
  343.    NOTES
  344.         The varargs version AskReq() can be found in pptsupp.lib. Please
  345.         note that it really does require the PPTBase in stack, since the
  346.         pointer cannot be declared global.  Unless you're running SAS/C
  347.         of course, in which case the compiler uses the #pragma tagcall
  348.         and you can stop worrying.
  349.  
  350.    BUGS
  351.  
  352.    SEE ALSO
  353.  
  354. pptsupport/ClearProgress                                pptsupport/ClearProgress
  355.  
  356.    NAME
  357.         ClearProgress -- Clear progress display.
  358.  
  359.    SYNOPSIS
  360.         ClearProgress( frame )
  361.                        A0
  362.  
  363.         VOID ClearProgress( FRAME * );
  364.  
  365.    FUNCTION
  366.         Clears the progress display, resets variables and renders the
  367.         'idle' - text on the status display.
  368.  
  369.    INPUTS
  370.         frame - as usual.
  371.  
  372.    RESULT
  373.  
  374.    EXAMPLE
  375.  
  376.    NOTES
  377.         There should not be any real reason for you to call this routine.
  378.         So, keep away from it.
  379.  
  380.    BUGS
  381.  
  382.    SEE ALSO
  383.         InitProgress(), Progress().
  384.  
  385. pptsupport/CloseProgress                                pptsupport/CloseProgress
  386.  
  387.    NAME
  388.         CloseProgress -- closes progress display (V5)
  389.  
  390.    SYNOPSIS
  391.         CloseProgress( frame )
  392.                         A0
  393.  
  394.         VOID CloseProgress( FRAME * );
  395.  
  396.    FUNCTION
  397.         Closes the progress display window.
  398.  
  399.    INPUTS
  400.         frame - As usual.
  401.  
  402.    RESULT
  403.         N/A.
  404.  
  405.    EXAMPLE
  406.  
  407.    NOTES
  408.         Please do not use, unless you really know what you're doing.
  409.  
  410.    BUGS
  411.  
  412.    SEE ALSO
  413.         InitProgress(), ClearProgress(), Progress().
  414.  
  415. pptsupport/CopyFrameData                                pptsupport/CopyFrameData
  416.  
  417.    NAME
  418.         CopyFrameData - copy the data from one frame to an another (V4)
  419.  
  420.    SYNOPSIS
  421.         error = CopyFrameData( source, dest, flags )
  422.         D0                     A0      A1    D0
  423.  
  424.         PERROR CopyFrameData( FRAME *, FRAME *, ULONG );
  425.  
  426.    FUNCTION
  427.         This function copies all the image data from the source
  428.         frame to the dest frame.  The frames must have the same
  429.         size and the same colorspace.
  430.  
  431.    INPUTS
  432.         source - the source frame
  433.         dest - the destination frame
  434.         flags - controls the copying procedure. Possible flags are:
  435.  
  436.             CFDF_SHOWPROGRESS - Specifying this flag causes a
  437.                 progress bar to be displayed during the copying
  438.                 operation.  You will want to enable this if you
  439.                 are copying a very large image.
  440.  
  441.    RESULT
  442.         PERR_OK if everything went ok, otherwise this can fail in
  443.             numerous ways...
  444.  
  445.    EXAMPLE
  446.  
  447.    NOTES
  448.  
  449.    BUGS
  450.         No error checking.
  451.  
  452.    SEE ALSO
  453.         MakeFrame(), InitFrame()
  454.  
  455. pptsupport/DupFrame                                          pptsupport/DupFrame
  456.  
  457.    NAME
  458.         DupFrame -- Duplicate a frame.
  459.  
  460.    SYNOPSIS
  461.         newframe = DupFrame( frame, flags )
  462.         D0                   A0,    D0
  463.  
  464.         FRAME *DupFrame( FRAME *, ULONG );
  465.  
  466.    FUNCTION
  467.         Makes a copy of the FRAME structure given - and if required -
  468.         also a copy of the image data.
  469.  
  470.         You may get rid of the new frame by calling RemFrame().
  471.  
  472.    INPUTS
  473.         frame - Frame you wish to duplicate.
  474.         flags - any of the following flags ORed together:
  475.             DFF_COPYDATA - Copies also the image data.
  476.             DFF_MAKENEWNAME - Generates a new name for the
  477.                 image.
  478.  
  479.    RESULT
  480.         newframe - A new frame that is an exact copy of the frame
  481.             you gave.
  482.  
  483.    EXAMPLE
  484.  
  485.    NOTES
  486.         If you don't want to copy the data, this routine just
  487.         calls MakeFrame() and InitFrame() to make a duplicate.
  488.  
  489.         Most probably you will never require this routine, since the
  490.         frame passed to your external already is a copy. And if you
  491.         specify PPTX_NoNewFrame, you will probably want to modify the
  492.         sizes anyways, in which case this routine is not for you.
  493.  
  494.    BUGS
  495.  
  496.    SEE ALSO
  497.         MakeFrame(), RemFrame(), InitFrame()
  498.  
  499. pptsupport/FindExtension                                pptsupport/FindExtension
  500.  
  501.    NAME
  502.         FindExtension -- Finds an extension from a frame (V3)
  503.  
  504.    SYNOPSIS
  505.         data = FindExtension( frame, name );
  506.  
  507.         struct Extension *AddExtension( FRAME *, STRPTR )
  508.         D0                            A0       A1
  509.  
  510.    FUNCTION
  511.         Finds a previously set extension from a frame.
  512.  
  513.    INPUTS
  514.         frame - the frame handle.
  515.         name - a NUL-terminated string that is an unique identifier
  516.             for your option chunk.  The name is case-sensitive. PPT
  517.             understands and uses the following pre-defined names:
  518.  
  519.             EXTNAME_AUTHOR - A string that contains author data.
  520.             EXTNAME_ANNO - An annotation string.
  521.             EXTNAME_DATE - A date string.
  522.  
  523.    RESULT
  524.         data - pointer to the extension node.  Consider everything
  525.             read only!
  526.             The information you want is at data->en_Data.
  527.  
  528.    EXAMPLE
  529.  
  530.    NOTES
  531.  
  532.    BUGS
  533.  
  534.    SEE ALSO
  535.         GetOptions(),PutOptions(),AddExtension()
  536.  
  537. pptsupport/FindFrame                                        pptsupport/FindFrame
  538.  
  539.    NAME
  540.         FindFrame -- Find a frame by its ID code
  541.  
  542.    SYNOPSIS
  543.         frame = FindFrame( id )
  544.         D0                 D0
  545.  
  546.         FRAME *MakeFrame( ID id );
  547.  
  548.    FUNCTION
  549.    TBA
  550.  
  551.    INPUTS
  552.         id - frame id code.
  553.  
  554.    RESULT
  555.         frame - a frame handle. NULL if the id could not be found.
  556.  
  557.    EXAMPLE
  558.  
  559.    NOTES
  560.  
  561.    BUGS
  562.  
  563.    SEE ALSO
  564.  
  565. pptsupport/FinishProgress                              pptsupport/FinishProgress
  566.  
  567.    NAME
  568.         FinishProgress -- finish progress display.
  569.  
  570.    SYNOPSIS
  571.         FinishProgress( frame )
  572.                         A0
  573.  
  574.         VOID FinishProgress( FRAME * );
  575.  
  576.    FUNCTION
  577.         Calling this function means that you are finished and you wish no
  578.         longer to use the progress display. If you still have something to do,
  579.         use InitProgress() again. Normally, you should call this function right
  580.         when you're finished. You may still do cleanups, etc., but nothing
  581.         slow, otherwise it might confuse the user.
  582.  
  583.         Note that this routines does not actually close the progress display,
  584.         but renders it at 100% done.  PPT will close the window when you
  585.         return from the plugin.
  586.  
  587.    INPUTS
  588.         frame - As usual.
  589.  
  590.    RESULT
  591.  
  592.    EXAMPLE
  593.         See autodoc for InitProgress().
  594.  
  595.    NOTES
  596.  
  597.    BUGS
  598.  
  599.    SEE ALSO
  600.         InitProgress(), ClearProgress(), Progress().
  601.  
  602. pptsupport/GetBackgroundColor                      pptsupport/GetBackgroundColor
  603.  
  604.    NAME
  605.         GetBackgroundColor
  606.  
  607.    SYNOPSIS
  608.         success = GetBackgroundColor( frame, pixel )
  609.         D0                            A0     A1
  610.  
  611.         PERROR GetBackgroundColor( FRAME *, ROWPTR );
  612.  
  613.    FUNCTION
  614.         Returns the background color of the given frame.  If no background
  615.         color has been designated, then will calculate a good guess
  616.         using an average of each of the corners.
  617.  
  618.    INPUTS
  619.         frame - the frame handle
  620.         pixel - pointer to a location where the pixel should be
  621.             written.  Make sure you have enough space for one pixel!
  622.  
  623.    RESULT
  624.         success - PPT error code.  PERR_OK, if everything went OK.
  625.  
  626.    EXAMPLE
  627.  
  628.    NOTES
  629.         The reason this is a function instead of a field in the PIXINFO
  630.         structure is that if needed, the background color can be
  631.         calculated on the fly.
  632.  
  633.    BUGS
  634.  
  635.    SEE ALSO
  636.  
  637. pptsupport/GetBitMapRow                                  pptsupport/GetBitMapRow
  638.  
  639.    NAME
  640.         GetBitMapRow -- get a pointer to a rendered image
  641.  
  642.    SYNOPSIS
  643.         ptr = GetBitMapRow( frame, row );
  644.         D0                  A0     D0
  645.  
  646.         UBYTE *GetBitMapRow( FRAME *, WORD );
  647.  
  648.    FUNCTION
  649.         Returns a single bitmapped row in chunky pixel format from
  650.         a rendered image.
  651.  
  652.    INPUTS
  653.         frame - easy.
  654.         row - The row you wish to have data from
  655.  
  656.    RESULT
  657.         ptr - A pointer to chunky data or NULL, if something failed.
  658.             Don't forget to check it!
  659.  
  660.    EXAMPLE
  661.  
  662.    NOTES
  663.  
  664.    BUGS
  665.  
  666.    SEE ALSO
  667.         GetPixelRow().
  668.  
  669. pptsupport/GetNPixelRows                                pptsupport/GetNPixelRows
  670.  
  671.    NAME
  672.         GetNPixelRows -- Get several rows at once.
  673.  
  674.    SYNOPSIS
  675.         rows = GetNPixelRows( frame, buffer, startrow, nrows )
  676.         D0                    A0     A1      D0        D1
  677.  
  678.         UWORD GetNPixelRows( FRAME *, ROWPTR *, WORD, UWORD );
  679.  
  680.    FUNCTION
  681.  
  682.    INPUTS
  683.         frame - as usual.
  684.         buffer - pointer to an array with nrows elements. PPT loads the
  685.             pointers to the image rows into this array, so that the pointer
  686.             to startrow goes into buffer[0], pointer to startrow+1 goes
  687.             to buffer[1], etc. If any of the rows are unfetchable for any
  688.             reason, the element will contain NULL. Remember to check for it!
  689.         startrow - the row you wish to start the lines for.
  690.         nrows - how many rows do you wish to fetch.
  691.  
  692.    RESULT
  693.         rows - number of rows successfully loaded into buffer.
  694.             If zero, an error occurred or you were way out of
  695.             any reasonable limits.
  696.  
  697.    EXAMPLE
  698.  
  699.    NOTES
  700.         You may attempt to get negative rows, but then both the array and
  701.         the return value will reflect this. For example:
  702.             foo = GetNPixelRows(frame,buffer,-5,10);
  703.  
  704.         In this case, foo will be 5 and buffer[0..4] will be NULL and
  705.         buffer[5..9] will be valid pointers.
  706.  
  707.    BUGS
  708.  
  709.    SEE ALSO
  710.         PutNPixelRows(), GetPixelRow(), GetPixel().
  711.  
  712. pptsupport/GetOptions                                      pptsupport/GetOptions
  713.  
  714.    NAME
  715.         GetOptions -- get an option chunk saved by PutOptions().
  716.  
  717.    SYNOPSIS
  718.         data = GetOptions( name );
  719.  
  720.         APTR GetOptions( STRPTR );
  721.         D0               A0
  722.  
  723.    FUNCTION
  724.         Returns a data chunk saved using PutOptions() or NULL,
  725.         if no such name was found.
  726.  
  727.    INPUTS
  728.         name - pointer to a NUL-terminated string containing the
  729.             (case-sensitive) name for the requested datachunk.
  730.  
  731.    RESULT
  732.         data - pointer to a saved chunk or NULL, if not found.
  733.  
  734.    EXAMPLE
  735.         struct IBox *ib;
  736.         struct NewWindow *newwin;
  737.  
  738.         ib = (struct IBox *)GetOptions("my_external");
  739.         if( ib ) {
  740.             newwin->LeftEdge = ib->Left;
  741.             newwin->TopEdge  = ib->Top;
  742.             newwin->Height   = ib->Height;
  743.             newwin->Width    = ib->Width;
  744.         }
  745.  
  746.    NOTES
  747.         This returns a pointer to the internal saved object.
  748.         Please do not tamper with it, consider it READ ONLY!
  749.  
  750.    BUGS
  751.  
  752.    SEE ALSO
  753.         PutOptions();
  754.  
  755. pptsupport/GetPixel                                          pptsupport/GetPixel
  756.  
  757.    NAME
  758.         GetPixel -- Get data for one pixel only.
  759.  
  760.    SYNOPSIS
  761.         ptr = GetPixel( frame, row, column );
  762.         D0              A0     D0   D1
  763.  
  764.         APTR GetPixel( FRAME *, WORD, WORD )
  765.  
  766.    FUNCTION
  767.         Returns the pixel value for a single pixel entry.
  768.  
  769.    INPUTS
  770.         frame - Frame pointer.
  771.         row   - row number (zero is top row)
  772.         column - Column number (zero is the leftmost)
  773.  
  774.    RESULT
  775.         A pointer to the pixel in question.  You must cast
  776.         the pointer according to frame->pix->colorspace.
  777.  
  778.    EXAMPLE
  779.  
  780.    NOTES
  781.         Please use GetPixelRow() for access - it's a lot
  782.         faster.
  783.  
  784.    BUGS
  785.  
  786.    SEE ALSO
  787.         PutPixel(), GetPixelRow().
  788.  
  789. pptsupport/GetPixelRow                                    pptsupport/GetPixelRow
  790.  
  791.    NAME
  792.         GetPixelRow -- get a pointer to chunky data
  793.  
  794.    SYNOPSIS
  795.         ptr = GetPixelRow( frame, row )
  796.         D0                 A0     D0
  797.  
  798.         ROWPTR GetPixelRow( FRAME *, WORD );
  799.  
  800.    FUNCTION
  801.         Return a pointer to a row of data in either 24 bit chunky format
  802.         or 8 bit chunky graylevel data. In the former case, the data is
  803.         in RGB - order. You may check the amount of components in
  804.         frame->pix->components at any time.
  805.  
  806.    INPUTS
  807.         frame - the frame handle
  808.         row - the pixel row you need info from
  809.  
  810.    RESULT
  811.         ptr - A pointer to bitmapped data or NULL, if something failed.
  812.  
  813.    EXAMPLE
  814.  
  815.    NOTES
  816.         DO NOT reference a row which you have not GetPixelRow()ed first.
  817.  
  818.    BUGS
  819.  
  820.    SEE ALSO
  821.         PutPixelRow(), GetBitMapRow()
  822.  
  823. pptsupport/InitFrame                                        pptsupport/InitFrame
  824.  
  825.    NAME
  826.         InitFrame -- Initialize a frame.
  827.  
  828.    SYNOPSIS
  829.         success = InitFrame( frame )
  830.         D0                   A0
  831.  
  832.         PERROR InitFrame( FRAME * );
  833.  
  834.    FUNCTION
  835.         This function will allocate all the necessary system resources
  836.         for PPT to operate, ie. Virtual Memory, screen data, etc. Use
  837.         AFTER MakeFrame().
  838.  
  839.    INPUTS
  840.         frame - Frame you wish to initialize.
  841.  
  842.    RESULT
  843.         PERR_OK, if everything went nicely, otherwise an error code
  844.         telling what went wrong. See ppt.h for error codes.
  845.  
  846.    EXAMPLE
  847.  
  848.    NOTES
  849.         Do not change any values inside the FRAME structure after calling
  850.         this function. You may still remove the handle with RemFrame().
  851.  
  852.    BUGS
  853.  
  854.    SEE ALSO
  855.         MakeFrame(), DupFrame(), RemFrame()
  856.  
  857. pptsupport/InitProgress                                  pptsupport/InitProgress
  858.  
  859.    NAME
  860.         InitProgress -- Initialize progress display
  861.  
  862.    SYNOPSIS
  863.         InitProgress( frame, txt, min, max )
  864.                       A0     A1   D0   D1
  865.  
  866.         VOID InitProgress( FRAME *, UBYTE *, ULONG, ULONG );
  867.  
  868.    FUNCTION
  869.         Initialize progress display to use with Progress().
  870.  
  871.    INPUTS
  872.         frame - as usual.
  873.         txt - a string to be displayed to the user while your algorithm
  874.             is running.
  875.         min - the minimum value of your counter
  876.         max - the maximum value of your counter
  877.  
  878.         The counter is the value you pass to the Progress() - function.
  879.  
  880.    RESULT
  881.  
  882.    EXAMPLE
  883.         A normal loop in which you can process the data might look as
  884.         follows (frame is the FRAME * sent to you by ppt and tags is
  885.         the TagItem array:
  886.  
  887.         ...
  888.  
  889.         InitProgress( frame, "Mongering...",
  890.                       frame->selbox.MinY, frame->selbox.MaxY );
  891.         for( row = frame->selbox.MinY; row < frame->selbox.MaxY; row ++ ) {
  892.             ROWPTR cp;
  893.             cp = GetPixelRow( frame, row );
  894.             MongerARow( cp );
  895.             if(Progress( frame, row )) {
  896.                 break;
  897.             }
  898.         }
  899.         FinishProgress( frame );
  900.         ...
  901.  
  902.    NOTES
  903.         Use always before Progress() and do not forget to call
  904.         FinishProgress()!
  905.  
  906.    BUGS
  907.  
  908.    SEE ALSO
  909.         Progress(), ClearProgress(), FinishProgress().
  910.  
  911. pptsupport/MakeFrame                                        pptsupport/MakeFrame
  912.  
  913.    NAME
  914.         MakeFrame -- Creates a new frame.
  915.  
  916.    SYNOPSIS
  917.         frame = MakeFrame( oldframe )
  918.         D0                 A0
  919.  
  920.         FRAME *MakeFrame( FRAME * );
  921.  
  922.    FUNCTION
  923.         This will allocate space for a new FRAME structure. The FRAME
  924.         is essential in any PPT image handling. After obtaining a handle
  925.         to the frame, you should edit any values you feel necessary
  926.         and then call InitFrame(). Do not pass the frame to any other PPT
  927.         routines before calling InitFrame()!
  928.  
  929.    INPUTS
  930.         oldframe - if you wish to duplicate a frame, you can either specify
  931.             the frame here or just call DupFrame(). If you specify the
  932.             oldframe, you should still call InitFrame(), though.
  933.  
  934.    RESULT
  935.         frame - new frame handle
  936.  
  937.    EXAMPLE
  938.  
  939.    NOTES
  940.         Remove handles using RemFrame().
  941.  
  942.    BUGS
  943.         This assumes the old frame will not coexist with a new one.
  944.  
  945.    SEE ALSO
  946.         InitFrame(), DupFrame(), RemFrame()
  947.  
  948. pptsupport/ObtainPreviewFrameA                    pptsupport/ObtainPreviewFrameA
  949.  
  950.    NAME
  951.         ObtainPreviewFrameA - Create a preview frame for an external.
  952.         ObtainPreviewFrame - varargs version.
  953.  
  954.    SYNOPSIS
  955.         preview = ObtainPreviewFrameA( frame, tags );
  956.         D0                             A0     A1
  957.  
  958.         FRAME *ObtainPreviewFrameA( FRAME *, struct TagItem * );
  959.  
  960.    FUNCTION
  961.         Obtains a preview frame (a small version of the original image,
  962.         also known as a thumbnail).
  963.  
  964.         The size of the thumbnail depends on the preferences set
  965.         by the user.
  966.  
  967.    INPUTS
  968.         Available tags are:
  969.  
  970.         PREV_PreviewHook (struct Hook *) - Specifying this tag means
  971.             that the external module is prepared to handle the entire
  972.             drawing of the preview by itself.  Don't do this unless
  973.             you really know what you're doing.
  974.  
  975.    RESULT
  976.         preview - the preview frame.
  977.  
  978.    EXAMPLE
  979.  
  980.    NOTES
  981.  
  982.    BUGS
  983.         This entry incomplete.
  984.  
  985.    SEE ALSO
  986.         ReleasePreviewFrame(), example code in externals/src/,
  987.         AskReqA()
  988.  
  989. pptsupport/PlanarToChunky                              pptsupport/PlanarToChunky
  990.  
  991.    NAME
  992.         PlanarToChunky -- Convert planar mode graphics to chunky
  993.  
  994.    SYNOPSIS
  995.         PlanarToChunky( source, dest, width, depth )
  996.                         A0      A1    D0     D1
  997.  
  998.         VOID PlanarToChunky( UBYTE **, ROWPTR, ULONG, UWORD );
  999.  
  1000.    FUNCTION
  1001.         This is an optimized function for converting planar mode
  1002.         graphics into chunky mode graphics. Useful if the data in
  1003.         a file is in bitmapped format because you need to feed the
  1004.         data into PPT in chunky pixel format.
  1005.  
  1006.    INPUTS
  1007.         source - A pointer to an array containing pointers to wherever
  1008.             your planar data is.
  1009.         dest - The chunky buffer where you wish the result to be put
  1010.         width - Width of the row.
  1011.         depth - Number of bitplanes and thus the number of entries in
  1012.             the source array.
  1013.  
  1014.    RESULT
  1015.  
  1016.    EXAMPLE
  1017.  
  1018.    NOTES
  1019.  
  1020.    BUGS
  1021.         Supports only 1-8, 16, 24 and 32 planes at the moment. Do not
  1022.         attempt to try to convert other types.
  1023.         Could really be faster
  1024.  
  1025.    SEE ALSO
  1026.         GetPixelRow()
  1027.  
  1028. pptsupport/Progress                                          pptsupport/Progress
  1029.  
  1030.    NAME
  1031.         Progress -- update Progress display.
  1032.  
  1033.    SYNOPSIS
  1034.         break = Progress( frame, done )
  1035.         D0                A0     D0
  1036.  
  1037.         BOOL Progress( FRAME *, ULONG );
  1038.  
  1039.    FUNCTION
  1040.         Updates progress display.
  1041.  
  1042.    INPUTS
  1043.         frame - As usual.
  1044.         done - your progress indicator. PPT will transform this into
  1045.             a display bar by heeding the values you stated in the
  1046.             InitProgress() call. The value must be between those
  1047.             values.
  1048.  
  1049.    RESULT
  1050.         break - TRUE, if the user wants you to quit. You should exit as
  1051.             soon as possible.
  1052.  
  1053.    EXAMPLE
  1054.         See autodoc for InitProgress().
  1055.  
  1056.    NOTES
  1057.  
  1058.    BUGS
  1059.  
  1060.    SEE ALSO
  1061.         InitProgress(), FinishProgress(), ClearProgress().
  1062.  
  1063. pptsupport/PutNPixelRows                                pptsupport/PutNPixelRows
  1064.  
  1065.    NAME
  1066.         PutNPixelRows -- Write several modified rows.
  1067.  
  1068.    SYNOPSIS
  1069.         PutNPixelRows( frame, buffer, startrow, nrows )
  1070.                        A0     A1      D0        D1
  1071.  
  1072.         VOID PutNPixelRows( FRAME *, ROWPTR *, WORD, UWORD );
  1073.  
  1074.    FUNCTION
  1075.         After doing a GetNPixelRows, you may use this routine to put
  1076.         the rows back into the frame. You MUST do this if you make
  1077.         any modifications.
  1078.  
  1079.    INPUTS
  1080.         frame - as usual.
  1081.         buffer - A pointer to an array which is filled with pointers
  1082.             to standard PPT pixel rows. See GetNPixels() autodoc for
  1083.             more info.
  1084.         startrow - where the rows where originally fetched from.
  1085.         nrows - how many rows in total.
  1086.  
  1087.    RESULT
  1088.  
  1089.    EXAMPLE
  1090.  
  1091.    NOTES
  1092.  
  1093.    BUGS
  1094.         This entry is still very incomplete.
  1095.  
  1096.    SEE ALSO
  1097.         GetNPixelRows(), PutPixel(), PutPixelRow().
  1098.  
  1099. pptsupport/PutOptions                                      pptsupport/PutOptions
  1100.  
  1101.    NAME
  1102.         PutOptions -- Saves options from an external (V3)
  1103.  
  1104.    SYNOPSIS
  1105.         success = PutOptions( name, data, len );
  1106.  
  1107.         PERROR PutOptions( STRPTR, APTR, ULONG )
  1108.         D0                 A0      A1    D0
  1109.  
  1110.    FUNCTION
  1111.         This function can be used to save a chunk of memory during
  1112.         different invocations of your external.  For example, if
  1113.         you wish to snapshot your window's location, you could
  1114.         make it a structure, and then pass it to this function.
  1115.         Then you can use GetOptions() to retrieve your data.
  1116.  
  1117.         The data given is copied, so it is safe to release the
  1118.         container after this call.
  1119.  
  1120.         If a previous option chunk with the same name is found,
  1121.         this chunk is replaced with the new one.  No warning
  1122.         is given.
  1123.  
  1124.         The data chunks are collectively removed during exiting
  1125.         PPT.
  1126.  
  1127.    INPUTS
  1128.         name - a NUL-terminated string that is an unique identifier
  1129.             for your option chunk.  The name is case-sensitive.
  1130.         data - pointer to your data.
  1131.         len  - length of your data chunk.
  1132.  
  1133.    RESULT
  1134.         success - PERR_OK if everything went OK and options were
  1135.             successfully saved in memory, PERR_OUTOFMEMORY, if
  1136.             there was not enough memory to save the options.
  1137.  
  1138.    EXAMPLE
  1139.         This describes how to save your window location.
  1140.  
  1141.         struct IBox windim;
  1142.  
  1143.         windim->Left = mywin->LeftEdge;
  1144.         windim->Top  = mywin->TopEdge;
  1145.         windim->Height = mywin->Height;
  1146.         windim->Width = mywin->Width;
  1147.  
  1148.         PutOptions("my_external", &windim, sizeof(struct IBox) );
  1149.  
  1150.    NOTES
  1151.         This function allocates new space for each data item and
  1152.         copies your data to a safe location.  Please note that it is
  1153.         quite unhealthy to save pointers to your own data.
  1154.  
  1155.    BUGS
  1156.         The options are not yet saved on disk.  In the future using
  1157.         this function guarantees that your options are saved on disk
  1158.         and you'll get the same data next time PPT is launched.
  1159.  
  1160.    SEE ALSO
  1161.         GetOptions()
  1162.  
  1163. pptsupport/PutPixel                                          pptsupport/PutPixel
  1164.  
  1165.    NAME
  1166.         PutPixel -- Put one modified pixel only.
  1167.  
  1168.    SYNOPSIS
  1169.         PutPixel( frame, row, column, pixel );
  1170.                   A0     D0   D1      A1
  1171.  
  1172.         VOID PutPixel( FRAME *, WORD, WORD, APTR );
  1173.  
  1174.    FUNCTION
  1175.         Writes a pixel into the frame.  The pixel must
  1176.         contain the data in the correct format (see
  1177.         frame->pix->colorspace).
  1178.  
  1179.    INPUTS
  1180.         frame - frame pointer.
  1181.         row   - Row.
  1182.         column - Column.
  1183.         pixel - The pixel pointer.
  1184.  
  1185.    RESULT
  1186.  
  1187.    EXAMPLE
  1188.  
  1189.    NOTES
  1190.         This is very slow - please see example code on how to modify
  1191.         the data directly.
  1192.  
  1193.    BUGS
  1194.  
  1195.    SEE ALSO
  1196.         GetPixel(), PutPixelRow().
  1197.  
  1198. pptsupport/PutPixelRow                                    pptsupport/PutPixelRow
  1199.  
  1200.    NAME
  1201.         PutPixelRow -- put the pixel data back into buffer.
  1202.  
  1203.    SYNOPSIS
  1204.         PutPixelRow( frame, row, data )
  1205.                      A0     D0   A1
  1206.  
  1207.         VOID PutPixelRow( FRAME *, WORD, ROWPTR );
  1208.  
  1209.    FUNCTION
  1210.         Put back the data obtained by GetPixelRow().
  1211.  
  1212.    INPUTS
  1213.         frame - the frame handle
  1214.         row - the pixel row you read the data from.
  1215.         data - pointer to the buffer returned by GetPixelRow().
  1216.  
  1217.    RESULT
  1218.  
  1219.    EXAMPLE
  1220.  
  1221.    NOTES
  1222.         You MUST call this routine if you wish your changes to be visible.
  1223.  
  1224.         Do not use this as a copy routine, in reality no data is copied
  1225.         to make this routine faster. If you have a need to copy stuff from
  1226.         one frame to another, use CopyMem(). In the future, the copying
  1227.         may be possible.
  1228.  
  1229.    BUGS
  1230.  
  1231.    SEE ALSO
  1232.         GetPixelRow(), GetBitMapRow()
  1233.  
  1234. pptsupport/ReleasePreviewFrame                    pptsupport/ReleasePreviewFrame
  1235.  
  1236.    NAME
  1237.         ReleasePreviewFrame - releases a preview frame.
  1238.  
  1239.    SYNOPSIS
  1240.         ReleasePreviewFrame( preview );
  1241.                              A0
  1242.  
  1243.         VOID ReleasePreviewFrame( FRAME * );
  1244.  
  1245.    FUNCTION
  1246.         Releases the small image acquired by ObtainPreviewFrame().
  1247.  
  1248.    INPUTS
  1249.         preview - The preview frame.
  1250.  
  1251.    RESULT
  1252.         N/A
  1253.  
  1254.    EXAMPLE
  1255.  
  1256.    NOTES
  1257.         The frame is freed completely after this call, so you'd better
  1258.         not access the memory in any way.
  1259.  
  1260.    BUGS
  1261.  
  1262.    SEE ALSO
  1263.         ObtainPreviewFrameA()
  1264.  
  1265. pptsupport/RemFrame                                          pptsupport/RemFrame
  1266.  
  1267.    NAME
  1268.         RemFrame -- Remove a frame.
  1269.  
  1270.    SYNOPSIS
  1271.         RemFrame( frame )
  1272.                   A0
  1273.  
  1274.         VOID RemFrame( FRAME * );
  1275.  
  1276.    FUNCTION
  1277.         Use this function to remove the handle given to you by
  1278.         MakeFrame() or DupFrame(). It does not matter if you call
  1279.         this after InitFrame(). Of course, you should no longer use
  1280.         the handle for anything after calling this function.
  1281.  
  1282.    INPUTS
  1283.         frame - Frame you wish to remove.
  1284.  
  1285.    RESULT
  1286.         A lot more free memory.
  1287.  
  1288.    EXAMPLE
  1289.  
  1290.    NOTES
  1291.         Safe to call with NULL args.
  1292.  
  1293.    BUGS
  1294.  
  1295.    SEE ALSO
  1296.         MakeFrame(), DupFrame(), InitFrame()
  1297.  
  1298. pptsupport/RemoveExtension                            pptsupport/RemoveExtension
  1299.  
  1300.    NAME
  1301.         RemoveExtension -- Removes an extension from a frame (V3)
  1302.  
  1303.    SYNOPSIS
  1304.         success = RemoveExtension( frame, name );
  1305.  
  1306.         PERROR RemoveExtension( FRAME *, STRPTR )
  1307.         D0                      A0       A1
  1308.  
  1309.    FUNCTION
  1310.         Finds and removes previously set extension from a frame.
  1311.  
  1312.    INPUTS
  1313.         frame - the frame handle.
  1314.         name - a NUL-terminated string that is an unique identifier
  1315.             for your option chunk.  The name is case-sensitive. PPT
  1316.             understands and uses the following pre-defined names:
  1317.  
  1318.             EXTNAME_AUTHOR - A string that contains author data.
  1319.             EXTNAME_ANNO - An annotation string.
  1320.             EXTNAME_DATE - A date string.
  1321.  
  1322.    RESULT
  1323.         success - PERR_OK, if the extension was found and successfully
  1324.             deleted; PERR_UNKNOWNTYPE, if the extension was not found.
  1325.  
  1326.    EXAMPLE
  1327.  
  1328.    NOTES
  1329.  
  1330.    BUGS
  1331.  
  1332.    SEE ALSO
  1333.         AddExtension(),FindExtension()
  1334.  
  1335. pptsupport/RenderFrame                                    pptsupport/RenderFrame
  1336.  
  1337.    NAME
  1338.         RenderFrame - renders a frame to the specified rastport. (V4)
  1339.  
  1340.    SYNOPSIS
  1341.         error = RenderFrame( frame, rport, location, flags );
  1342.         D0                   A0     A1     A2        D0
  1343.  
  1344.         PERROR RenderFrame( FRAME *, struct RastPort *, struct IBox *, ULONG );
  1345.  
  1346.    FUNCTION
  1347.         Use this function to render the frame into a RastPort.  PPT will
  1348.         automatically use the correct coloring routine.
  1349.  
  1350.         This is the internal previewing routine, so the results may not be
  1351.         very accurate.  Also, the current previewing preferences may
  1352.         change the result.
  1353.  
  1354.    INPUTS
  1355.         frame - the usual.
  1356.         rport - the RastPort of the window you want the frame to be rendered
  1357.             into.
  1358.         location - the location and size of the image.
  1359.         flags - reserved for future use.
  1360.  
  1361.    RESULT
  1362.         Standard error code.
  1363.  
  1364.    EXAMPLE
  1365.  
  1366.    NOTES
  1367.  
  1368.    BUGS
  1369.         Does not do very extensive error checking at the moment.
  1370.  
  1371.    SEE ALSO
  1372.  
  1373. pptsupport/SPrintF                                            pptsupport/SPrintF
  1374.  
  1375.    NAME
  1376.         SPrintF -- Print characters into a buffer. (V6)
  1377.  
  1378.    SYNOPSIS
  1379.         n = SPrintF( buffer, format, ... )
  1380.         D0           A0      A1
  1381.  
  1382.         n = SPrintFA( buffer, format, args )
  1383.         D0            A0      A1      A2
  1384.  
  1385.         ULONG SPrintF( STRPTR, STRPTR, ... );
  1386.  
  1387.         ULONG SPrintFA( STRPTR, STRPTR, APTR );
  1388.  
  1389.    FUNCTION
  1390.         Works like sprintf().  This uses ANSI functions, NOT
  1391.         exec.library/RawDoFmt().  Floating point is also supported.
  1392.  
  1393.    INPUTS
  1394.         buffer - buffer to which characters are written.  Make sure
  1395.             it is big enough.
  1396.  
  1397.         format - string of formatting characters.
  1398.  
  1399.         args - arguments for the format string.
  1400.  
  1401.    RESULT
  1402.         n - number of characters written.
  1403.  
  1404.    EXAMPLE
  1405.  
  1406.    NOTES
  1407.  
  1408.    BUGS
  1409.  
  1410.    SEE ALSO
  1411.         sprintf()
  1412.  
  1413. pptsupport/SetErrorCode                                  pptsupport/SetErrorCode
  1414.  
  1415.    NAME
  1416.         SetErrorCode -- Set the error code for the frame.
  1417.  
  1418.    SYNOPSIS
  1419.         SetErrorCode( frame, error )
  1420.                       A0     D0
  1421.  
  1422.         VOID SetErrorCode( FRAME *, PERROR );
  1423.  
  1424.    FUNCTION
  1425.         Set the error code for the frame. Upon returning from the
  1426.         external, PPT will display the proper error message.
  1427.  
  1428.    INPUTS
  1429.         frame - obvious
  1430.         error - a PPT specific error code. For the definition
  1431.             of the different PERR_* error codes, please see ppt.h.
  1432.  
  1433.    RESULT
  1434.  
  1435.    EXAMPLE
  1436.  
  1437.    NOTES
  1438.         You cannot set the error code more than once.
  1439.  
  1440.    BUGS
  1441.  
  1442.    SEE ALSO
  1443.         SetErrorMsg(), ppt.h
  1444.  
  1445. pptsupport/SetErrorMsg                                    pptsupport/SetErrorMsg
  1446.  
  1447.    NAME
  1448.         SetErrorMsg -- Set an error message string
  1449.  
  1450.    SYNOPSIS
  1451.         SetErrorMsg( frame, msg )
  1452.                      A0     A1
  1453.  
  1454.         VOID SetErrorMsg( FRAME *, UBYTE * );
  1455.  
  1456.    FUNCTION
  1457.         Set up a custom error message for the frame.
  1458.  
  1459.    INPUTS
  1460.         frame - your frame handle
  1461.         msg - pointer to a NUL-terminated string, which contains
  1462.             the error message. It is copied to an internal buffer,
  1463.             so you needn't guarantee it's validity after exiting
  1464.             your external module.
  1465.  
  1466.    RESULT
  1467.  
  1468.    EXAMPLE
  1469.  
  1470.    NOTES
  1471.         You cannot set the error code more than once.
  1472.  
  1473.    BUGS
  1474.  
  1475.    SEE ALSO
  1476.         SetErrorCode()
  1477.  
  1478. pptsupport/SetRexxVariable                            pptsupport/SetRexxVariable
  1479.  
  1480.    NAME
  1481.         SetRexxVariable -- sets a variable in the context of the frame. (V5)
  1482.  
  1483.    SYNOPSIS
  1484.         result = SetRexxVariable( frame, variable, value );
  1485.  
  1486.         LONG SetRexxVariable( FRAME *, STRPTR, STRPTR )
  1487.         D0                    A0       A1      A2
  1488.  
  1489.    FUNCTION
  1490.         This function sets an AREXX variable of the currently executing
  1491.         script.  Use with care!  Do not meddle with variables such
  1492.         as 'RC', 'RC2', or 'RESULT', since PPT uses them.
  1493.  
  1494.    INPUTS
  1495.         frame - the usual
  1496.         variable - the name of the variable you wish to set
  1497.         value - the string value
  1498.  
  1499.    RESULT
  1500.         Returns standard boolean values, that is, 0 for success,
  1501.         and != 0 for failure.
  1502.  
  1503.    EXAMPLE
  1504.  
  1505.    NOTES
  1506.         The SetRexxVar() parameter length is determined run-time
  1507.         with strlen().
  1508.  
  1509.    BUGS
  1510.  
  1511.    SEE ALSO
  1512.         amiga.lib/SetRexxVar
  1513.  
  1514. pptsupport/StartInput                                      pptsupport/StartInput
  1515.  
  1516.    NAME
  1517.         StartInput - Start up notification
  1518.  
  1519.    SYNOPSIS
  1520.         error = StartInput( frame, method, initialmsg )
  1521.         D0                  A0     D0      A1
  1522.  
  1523.         PERROR StartInput( FRAME *, ULONG, struct PPTMessage * );
  1524.  
  1525.    FUNCTION
  1526.         This function starts up input handling for a frame. Its main
  1527.         purpose is to provide interactivity for the external effect
  1528.         modules.
  1529.  
  1530.         When you call this function, PPT will temporarily unlock the
  1531.         frame and allow resizing the image window, zooming, etc.
  1532.  
  1533.         There are several methods at your disposal:
  1534.  
  1535.         GINP_PICK_POINT - initialmsg is ignored and may be NULL.
  1536.             Every time the user clicks the mouse within the image,
  1537.             you'll get a gPointMessage with the x and y fields
  1538.             containing image co-ordinates.
  1539.  
  1540.         GINP_FIXED_RECT - initialmsg should be a pointer to
  1541.             a struct gFixRextMessage, whose field dim should
  1542.             be initialized to a sensible value.  When the user moves
  1543.             the cursor in the frame, he'll see a rectangle moving around
  1544.             and when he places it somewhere, you'll be notified.
  1545.  
  1546.         You will be notified of input events until the StopInput()
  1547.         function is called.
  1548.  
  1549.    INPUTS
  1550.         frame - as usual
  1551.         method - Any of the following:
  1552.             GINP_PICK_POINT
  1553.             GINP_FIXED_RECT
  1554.         area - Depends on the method. See above.
  1555.  
  1556.    RESULT
  1557.         error - Standard PPT error code. PERR_OK if the input
  1558.             handler was started up OK.
  1559.  
  1560.    EXAMPLE
  1561.  
  1562.    NOTES
  1563.         You MUST call StopInput() when you are ready to start up your own
  1564.         processing on the frame.  Otherwise you'll keep getting messages
  1565.         even when you don't want them and the user might get confused.
  1566.  
  1567.    BUGS
  1568.  
  1569.    SEE ALSO
  1570.         StopInput()
  1571.  
  1572. pptsupport/StopInput                                        pptsupport/StopInput
  1573.  
  1574.    NAME
  1575.         StopInput - Stop sending input messages.
  1576.  
  1577.    SYNOPSIS
  1578.         StopInput( frame )
  1579.                    A0
  1580.  
  1581.         VOID StopInput( FRAME * );
  1582.  
  1583.    FUNCTION
  1584.         This function stops the input handler started by StartInput()
  1585.         and locks the frame, making it safe to process.
  1586.  
  1587.         It is important to call this function before starting up your
  1588.         own processing. If you call StartInput() and call GetPixelRow()
  1589.         some conflicts will occur, which will cause undefined behaviour.
  1590.         It might work. Or it might crash the system.
  1591.  
  1592.    INPUTS
  1593.         frame - the usual thing. Must be the same as in StartInput().
  1594.  
  1595.    RESULT
  1596.  
  1597.    EXAMPLE
  1598.  
  1599.    NOTES
  1600.  
  1601.    BUGS
  1602.         Should provide protection against forgotten StopInputs().
  1603.  
  1604.    SEE ALSO
  1605.         StartInput()
  1606.  
  1607. pptsupport/TagData                                            pptsupport/TagData
  1608.  
  1609.    NAME
  1610.         TagData -- Get Tag Data.
  1611.  
  1612.    SYNOPSIS
  1613.         data = TagData( value, list )
  1614.         D0              D0     A0
  1615.  
  1616.         ULONG TagData( Tag tag, struct TagList *list );
  1617.  
  1618.    FUNCTION
  1619.         This is a shortened version of utility.library's GetTagData().
  1620.         Use this to read tags from the taglists passed to your external.
  1621.  
  1622.    INPUTS
  1623.         value - Tag value you seek.
  1624.         list - A tag list terminated with TAG_DONE.
  1625.  
  1626.    RESULT
  1627.         data - Data associated with the tag. 0, if not found
  1628.             for some reason.
  1629.  
  1630.    EXAMPLE
  1631.  
  1632.    NOTES
  1633.  
  1634.    BUGS
  1635.  
  1636.    SEE ALSO
  1637.         utility.library/GetTagData().
  1638.  
  1639.