home *** CD-ROM | disk | FTP | other *** search
/ Fresh Fish 5 / FreshFish_July-August1994.bin / useful / dist / gfx / show / superview-lib / programmers / docs / superview_ref_eng.doc next >
Text File  |  1994-07-04  |  31KB  |  1,321 lines
  1.  
  2.    $VER: Reference_ENG.doc V6.5 (13.6.94)
  3.  
  4.    © 1994 by Andreas R. Kleinert. All rights reserved.
  5.  
  6.    - Feel free to translate this Doc-File into other languages. -
  7.  
  8.    Andreas R. Kleinert
  9.    Grube Hohe Grethe 23
  10.    D-57074 Siegen
  11.    Germany
  12.  
  13.  
  14.    Please note the version-dependencies :
  15.  
  16.     superview.library      SVObjects      SVDrivers      SVOperators
  17.  
  18.     Version 1              -              -              -
  19.     Version 2              Version 1      -              -
  20.     Version 3-6            Version 1,2    Version 1      -
  21.  
  22.  
  23.    Request at least :  V2+    for SVObjects
  24.                        V3+    for SVDrivers
  25.                        V4+    for bug-fixed ClipBoard-Support
  26.                               with the supplied SVObjects
  27.                        V5+    for bug-fixed GfxBuffer-Functions
  28.                        V6+    for working GfxBuffer-Writing
  29.                               with the supplied SVObjects
  30.  
  31.  
  32.    Here is a listing of all currently available functions of the
  33.    superview.library in an Autodoc-like style of description :
  34.  
  35.         SVL_AllocHandle            ; since Version 1
  36.         SVL_FreeHandle
  37.         SVL_CloseDisplay
  38.         SVL_FreeResources
  39.         SVL_SuperView
  40.         SVL_SuperWrite
  41.         SVL_InitHandleAsDOS
  42.         SVL_InitHandleAsClip
  43.         SVL_SetWriteType
  44.         SVL_SetWindowIDCMP
  45.         SVL_SetWindowFlags
  46.         SVL_SetScreenType
  47.         SVL_GetWindowAddress
  48.         SVL_GetScreenAddress
  49.         SVL_GetErrorString
  50.         SVL_SetWriteScreen
  51.         SVL_SetWriteName
  52.         SVL_FileInfoRequest
  53.                    ; no functions added in Version 2
  54.         SVL_GetGlobalDriver        ; since Version 3
  55.         SVL_SetGlobalDriver
  56.         SVL_ReadToGfxBuffer
  57.         SVL_GetGfxBuffer
  58.         SVL_SetGfxBuffer
  59.         SVL_DisplayGfxBuffer
  60.                    ; no functions added in Version 4
  61.                    ; no functions added in Version 5
  62.         SVL_GetSVObjectList        ; since Version 6
  63.         SVL_GetSVDriverList
  64.         SVL_FreeSVObjectList
  65.         SVL_FreeSVDriverList
  66.  
  67. -----------------------------------------------------------------------------
  68.    Functions available since Version 1 - 2 :
  69. -----------------------------------------------------------------------------
  70.  
  71.    NAME
  72.         SVL_AllocHandle
  73.  
  74.    SYNOPSIS
  75.  
  76.         APTR SVL_AllocHandle(APTR future)
  77.         D0   -$1e            A1
  78.  
  79.    FUNCTION
  80.  
  81.         Allocates a handle for accessing a Graphic via SVObjects.
  82.  
  83.    INPUT(S)
  84.  
  85.         future - always NULL yet
  86.  
  87.    RESULT
  88.  
  89.         A pointer to a new allocated Handle or NULL, if allocation failed.
  90.  
  91.    WARNING
  92.  
  93.         Test, if the result was NULL, or not !
  94.  
  95.    BUGS
  96.  
  97.         -
  98.  
  99.    SINCE
  100.  
  101.         ... version 1 of the superview.library.
  102.  
  103.    SEE ALSO
  104.  
  105.         SVL_FreeResources, SVL_FreeHandle
  106.  
  107. -----------------------------------------------------------------------------
  108.  
  109.    NAME
  110.         SVL_FreeHandle
  111.  
  112.    SYNOPSIS
  113.  
  114.         VOID SVL_FreeHandle(APTR handle)
  115.         D0   -$24           A1
  116.  
  117.    FUNCTION
  118.  
  119.        Stops showing, frees all Resources and delocates a Handle, which has
  120.        been allocated with SVL_AllocHandle before.
  121.  
  122.  
  123.        For programmers of SVObjects :
  124.  
  125.        Note, that this functions calls
  126.  
  127.           SVL_CloseDisplay(SVHandle);
  128.           SVL_FreeResources(SVHandle);
  129.  
  130.        for internal SVObjects and
  131.  
  132.           SVO_FreeHandle(SVHandle->ah_SVHandle);
  133.  
  134.           CloseLibrary((APTR) SVObjectBase);
  135.  
  136.        for external SVObjects.
  137.        So do not forget to do the SVO_CloseDisplay() and SVO_FreeResources()
  138.        calls inside SVO_FreeHandle().
  139.        Otherwise memory might be lost.
  140.  
  141.    INPUT(S)
  142.  
  143.         handle - a valid handle
  144.  
  145.    RESULT
  146.  
  147.         -
  148.  
  149.    BUGS
  150.  
  151.         This function was buggy for external SVObjects (never closed, memory
  152.         loss) upto V2.4.
  153.  
  154.    SINCE
  155.  
  156.         ... version 1 of the superview.library.
  157.  
  158.    SEE ALSO
  159.  
  160.         SVL_AllocHandle, SVL_CloseDisplay, SVL_FreeResources
  161.  
  162. -----------------------------------------------------------------------------
  163.  
  164.    NAME
  165.         SVL_CloseDisplay
  166.  
  167.    SYNOPSIS
  168.  
  169.         VOID SVL_CloseDisplay(APTR handle)
  170.         D0   -$2a             A1
  171.  
  172.    FUNCTION
  173.  
  174.         Stops showing the Graphic, indentified by the handle.
  175.         The Display-Screen is closed, but no Resources are given free.
  176.  
  177.    INPUT(S)
  178.  
  179.         handle - a valid handle
  180.  
  181.    RESULT
  182.  
  183.         -
  184.  
  185.    BUGS
  186.  
  187.         -
  188.  
  189.    SINCE
  190.  
  191.         ... version 1 of the superview.library.
  192.  
  193.    SEE ALSO
  194.  
  195.         SVL_FreeResources, SVL_FreeHandle
  196.  
  197. -----------------------------------------------------------------------------
  198.  
  199.    NAME
  200.         SVL_FreeResources
  201.  
  202.    SYNOPSIS
  203.  
  204.         VOID SVL_FreeResources(APTR handle)
  205.         D0   -$30              A1
  206.  
  207.    FUNCTION
  208.  
  209.         Frees all resources belonging to the specific Graphic,
  210.         indentified by the handle, which are not needed to just show it.
  211.         The Display will not be closed.
  212.  
  213.         Note, that SVL_FileInfoRequest() will no longer work, then
  214.         ("No file loaded" or similar request appears).
  215.  
  216.    INPUT(S)
  217.  
  218.         handle - a valid handle
  219.  
  220.    RESULT
  221.  
  222.         -
  223.  
  224.    BUGS
  225.  
  226.         -
  227.  
  228.    SINCE
  229.  
  230.         ... version 1 of the superview.library.
  231.  
  232.    SEE ALSO
  233.  
  234.         SVL_AllocHandle, SVL_CloseDisplay, SVL_FreeHandle
  235.  
  236. -----------------------------------------------------------------------------
  237.  
  238.    NAME
  239.         SVL_SuperView
  240.  
  241.    SYNOPSIS
  242.  
  243.         ULONG SVL_SuperView(APTR handle, char *filename)
  244.         D0    -$36          A1           A2
  245.  
  246.    FUNCTION
  247.  
  248.         Loads and shows the Graphic described by FileName.
  249.         The handle is initialized and the fitting SVObject is opened
  250.         and accessed for showing the Graphic.
  251.  
  252.         Showing can be stopped either via full delocation of the handle
  253.         or via Closing the Display with SVL_CloseDisplay.
  254.  
  255.    INPUT(S)
  256.  
  257.         handle   - a valid handle
  258.         filename - a valid AmigaDOS FilePath and -Name
  259.  
  260.    RESULT
  261.  
  262.         NULL or an adequate SVERR-Errorcode.
  263.  
  264.    BUGS
  265.  
  266.         -
  267.  
  268.    SINCE
  269.  
  270.         ... version 1 of the superview.library.
  271.  
  272.    SEE ALSO
  273.  
  274.         SVL_AllocHandle, SVL_CloseDisplay, SVL_FreeHandle
  275.  
  276. -----------------------------------------------------------------------------
  277.  
  278.    NAME
  279.         SVL_SuperWrite
  280.  
  281.    SYNOPSIS
  282.  
  283.         ULONG SVL_SuperWrite(APTR handle, APTR source_handle)
  284.         D0    -$3c           A1           A2
  285.  
  286.    FUNCTION
  287.  
  288.         Before Version 3 a Graphic had to be loaded AND showed via
  289.         SVL_SuperView : No separate reading and showing calls were done.
  290.         For writing - that means : converting - a Graphic, you at first
  291.         have to display, then to save it. Use the following order :
  292.  
  293.         (But check the "result" value AFTER EACH function call, like this
  294.          has been done in the example SourceCodes ...)
  295.  
  296.         source_handle = SVL_AllocHandle(N);
  297.         /* result     = SVL_InitHandleAsDOS(source_handle, N); */ /* default */
  298.         result        = SVL_SetWindowIDCMP(source_handle,
  299.                                     IDCMP_MOUSEBUTTONS | IDCMP_VANILLAKEY, N)))
  300.         result        = SVL_SetScreenType(source_handle, CUSTOMSCREEN, N)))
  301.         result        = SVL_SuperView(source_handle, source_filename)))
  302.         result        = SVL_GetScreenAddress(source_handle, &sv_screen, N)))
  303.         result        = SVL_GetWindowAddress(source_handle, &sv_window, N)))
  304.  
  305.         dest_handle   = SVL_AllocHandle(N);
  306.         /* result     = SVL_InitHandleAsDOS(dest_handle, N); */ /* default */
  307.         result        = SVL_SetWriteType(dest_handle, dest_type, N)))
  308.         result        = SVL_SetWriteName(dest_handle, dest_filename, N)))
  309.         result        = SVL_SetWriteScreen(dest_handle, sv_screen, N)))
  310.         result        = SVL_SuperWrite(dest_handle, source_handle);
  311.         SVL_FreeHandle(dest_handle);
  312.  
  313.         SVL_FreeHandle(source_handle);
  314.  
  315.  
  316.         Since Version 3 it is also possible to save the contents of
  317.         SV_GfxBuffers, so that not necessarily a Screen has to be the
  318.         source for writing to Disk/ClipBoard (or to whatever).
  319.         Not all SVObjects may necessarily support this (return-code
  320.         becomes SVERR_ACTION_NOT_SUPPORTED).
  321.         But since Version 6 all of the supplied SVObjects (those which come
  322.         with superview.library and contain Writ