home *** CD-ROM | disk | FTP | other *** search
/ Fresh Fish 5 / FreshFish_July-August1994.bin / useful / dist / gfx / show / superview-lib / programmers / docs / svobject_ref_eng.doc < prev    next >
Text File  |  1994-07-04  |  16KB  |  829 lines
  1.  
  2.    $VER: Reference_ENG.doc V2.1 (26.5.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.    * DO _NEVER_ ACCESS ANY SVOBJECTS DIRECTLY.
  14.    * DO NEVER BYPASS superview.library !
  15.  
  16.    THE FOLLOWING NOTES ARE ONLY FOR PROGRAMMERS OF SVOBJECTS :
  17.  
  18.    Here is a listing of the function set, which any of the version 1
  19.    and version 2 SVObjects does contain, in an Autodoc-like style of
  20.    description :
  21.  
  22.     SVO_AllocHandle        ; since Version 1
  23.     SVO_FreeHandle
  24.     SVO_Show
  25.     SVO_Write
  26.     SVO_CloseDisplay
  27.     SVO_FreeResources
  28.     SVO_SetAccessMode
  29.     SVL_SetScreenType
  30.     SVO_SetWindowFlags
  31.     SVO_SetWindowIDCMP
  32.     SVO_GetScreenAddress
  33.     SVO_GetWindowAddress
  34.     SVO_SetScreenAddress
  35.     SVO_SetWindowAddress
  36.     SVO_SetWriteName
  37.     SVO_SetReadName
  38.     SVO_FileInfoRequest
  39.     SVO_CheckFileType
  40.     SVO_ReadToGfxBuffer       ; since Version 2
  41.     SVO_GetGfxBuffer
  42.     SVO_SetGfxBuffer
  43.  
  44.  (you will never find any notes belonging to "BUGS", because any SVObject
  45.   may have its own ...)
  46.  
  47. -----------------------------------------------------------------------------
  48.    Functions available since Version 1 :
  49. -----------------------------------------------------------------------------
  50.  
  51.    NAME
  52.     SVO_AllocHandle
  53.  
  54.    SYNOPSIS
  55.  
  56.     APTR SVO_AllocHandle(APTR future)
  57.     D0   -$1e         A1
  58.  
  59.    FUNCTION
  60.  
  61.     Allocates a handle for accessing a Graphic via this SVObject.
  62.  
  63.    INPUT(S)
  64.  
  65.     future - always NULL yet
  66.  
  67.    RESULT
  68.  
  69.     A pointer to a new allocated Handle or NULL, if allocation failed.
  70.  
  71.    WARNING
  72.  
  73.     Test, if the result was NULL, or not !
  74.  
  75.    SINCE
  76.  
  77.     ... Version 1 SVObjects.
  78.  
  79.    SEE ALSO
  80.  
  81.     SVO_FreeResources, SVO_FreeHandle
  82.  
  83. -----------------------------------------------------------------------------
  84.  
  85.    NAME
  86.     SVO_FreeHandle
  87.  
  88.    SYNOPSIS
  89.  
  90.     VOID SVO_FreeHandle(APTR handle)
  91.     D0   -$24        A1
  92.  
  93.    FUNCTION
  94.  
  95.        Stops showing, frees all Resources and delocates a Handle, which has
  96.        been allocated with SVO_AllocHandle before.
  97.  
  98.  
  99.        For programmers of SVObjects :
  100.  
  101.        Note, that this function should call
  102.  
  103.       SVO_CloseDisplay(SVHandle);
  104.       SVO_FreeResources(SVHandle);
  105.  
  106.        always. Otherwise memory might be lost.
  107.  
  108.    INPUT(S)
  109.  
  110.     handle - a valid handle
  111.  
  112.    RESULT
  113.  
  114.     -
  115.  
  116.    SINCE
  117.  
  118.     ... Version 1 SVObjects.
  119.  
  120.    SEE ALSO
  121.  
  122.     SVO_AllocHandle, SVO_CloseDisplay, SVO_FreeResources
  123.  
  124. -----------------------------------------------------------------------------
  125.  
  126.    NAME
  127.     SVO_Show
  128.  
  129.    SYNOPSIS
  130.  
  131.     ULONG SVO_Show(APTR handle)
  132.     D0    -$2a     A1
  133.  
  134.    FUNCTION
  135.  
  136.     Loads and shows the Graphic described by a previously set FileName
  137.     or just shows the Graphic, if already been loaded.
  138.  
  139.     Showing can be stopped either via full delocation of the handle
  140.     or via Closing the Display with SVO_CloseDisplay.
  141.  
  142.    INPUT(S)
  143.  
  144.     handle     - a valid handle
  145.  
  146.    RESULT
  147.  
  148.     NULL or an adequate SVERR-Errorcode.
  149.  
  150.    SINCE
  151.  
  152.     ... Version 1 SVObjects.
  153.  
  154.    SEE ALSO
  155.  
  156.     SVO_AllocHandle, SVO_CloseDisplay, SVO_FreeHandle
  157.  
  158. -----------------------------------------------------------------------------
  159.  
  160.    NAME
  161.     SVO_Write
  162.  
  163.    SYNOPSIS
  164.  
  165.     ULONG SVO_Write(APTR handle)
  166.     D0    -$30    A1
  167.  
  168.    FUNCTION
  169.  
  170.     Writes the currently loaded (GfxBuffer) or displayed (Screen)
  171.     graphic into a file or onto any other medium, which has been
  172.     specified via the appropriate function calls before.
  173.  
  174.    INPUT(S)
  175.  
  176.     handle          - a valid handle
  177.  
  178.    RESULT
  179.  
  180.     NULL or an adequate SVERR-Errorcode.
  181.  
  182.    SINCE
  183.  
  184.     ... Version 1 SVObjects.
  185.  
  186.    SEE ALSO
  187.  
  188.  
  189.     SVO_AllocHandle, SVO_FreeHandle
  190.  
  191. -----------------------------------------------------------------------------
  192.  
  193.    NAME
  194.     SVO_CloseDisplay
  195.  
  196.    SYNOPSIS
  197.  
  198.     VOID SVO_CloseDisplay(APTR handle)
  199.     D0   -$36          A1
  200.  
  201.    FUNCTION
  202.  
  203.     Stops showing the Graphic, indentified by the handle.
  204.     The Display-Screen is closed, but no Resources are given free.
  205.  
  206.    INPUT(S)
  207.  
  208.     handle - a valid handle
  209.  
  210.    RESULT
  211.  
  212.     -
  213.  
  214.    SINCE
  215.  
  216.     ... Version 1 SVObjects.
  217.  
  218.    SEE ALSO
  219.  
  220.     SVO_FreeResources, SVO_FreeHandle
  221.  
  222. -----------------------------------------------------------------------------
  223.  
  224.    NAME
  225.     SVO_FreeResources
  226.  
  227.    SYNOPSIS
  228.  
  229.     VOID SVO_FreeResources(APTR handle)
  230.     D0   -$3c           A1
  231.  
  232.    FUNCTION
  233.  
  234.     Frees all resources belonging to the specific Graphic,
  235.     indentified by the handle, which are not needed to just show it.
  236.     The Display will not be closed.
  237.  
  238.     Note, that SVO_FileInfoRequest() will no longer work, then
  239.     ("No file loaded" or similar request appears).
  240.  
  241.    INPUT(S)
  242.  
  243.     handle - a valid handle
  244.  
  245.    RESULT
  246.  
  247.     -
  248.  
  249.    SINCE
  250.  
  251.     ... Version 1 SVObjects.
  252.  
  253.    SEE ALSO
  254.  
  255.     SVO_AllocHandle, SVO_CloseDisplay, SVO_FreeHandle
  256.  
  257. -----------------------------------------------------------------------------
  258.  
  259.    NAME
  260.     SVO_SetAccessMode
  261.  
  262.    SYNOPSIS
  263.  
  264.     ULONG SVO_SetAccessMode(APTR handle, ULONG mode)
  265.     D0    -$42        A1         D1
  266.  
  267.    FUNCTION
  268.  
  269.     Initializes a Handle e.g. for AmigaDOS access, so that the
  270.     separately specified AmigaDOS FileName will be used.
  271.     Another possibility is sometimes to initialize Handles
  272.     for ClipBoard Access (depending on the specific SVObject,
  273.     e.g. IFF-ILBM).
  274.  
  275.    INPUT(S)
  276.  
  277.     handle - a valid handle
  278.     mode   - one of the supported "medium" Flags
  279.  
  280.    RESULT
  281.  
  282.     NULL or an adequate SVERR-Errorcode.
  283.  
  284.    SINCE
  285.  
  286.     ... Version 1 SVObjects.
  287.  
  288.    SEE ALSO
  289.  
  290.     SVO_SetWriteName
  291.  
  292. -----------------------------------------------------------------------------
  293.  
  294.    NAME
  295.     SVL_SetScreenType
  296.  
  297.    SYNOPSIS
  298.  
  299.     ULONG SVL_SetScreenType(APTR handle, ULONG type, APTR future)
  300.     D0    -$48        A1        D1        A2
  301.  
  302.    FUNCTION
  303.  
  304.     Specifies, which ScreenType the Screen should have, on which the
  305.     graphic is to be displayed later.
  306.  
  307.     This statement may have no effect, if the SVObject uses external
  308.     drivers for displaying (e.g. EGS.svdriver will ignore this
  309.     setting more or less).
  310.  
  311.    INPUT(S)
  312.  
  313.     handle - a valid handle
  314.     type   - a ScreenType descriptor, like e.g. CUSTOMSCREEN
  315.     future - always NULL yet
  316.  
  317.    RESULT
  318.  
  319.     NULL or an adequate SVERR-Errorcode.
  320.  
  321.    SINCE
  322.  
  323.     ... Version 1 SVObjects.
  324.  
  325.    SEE ALSO
  326.  
  327.     SVO_GetScreenAddress
  328.  
  329. -----------------------------------------------------------------------------
  330.  
  331.    NAME
  332.     SVO_SetWindowFlags
  333.  
  334.    SYNOPSIS
  335.  
  336.     ULONG SVO_SetWindowFlags(APTR handle, ULONG flags, APTR future)
  337.     D0    -$4e         A1          D1       A2
  338.  
  339.    FUNCTION
  340.  
  341.     Specifies, which Flags the Window should have, on which the
  342.     graphic is to be displayed later.
  343.  
  344.     This statement may have no effect, if the SVObject uses external
  345.     drivers for displaying (e.g. EGS.svdriver will ignore this
  346.     setting more or less).
  347.  
  348.    INPUT(S)
  349.  
  350.     handle       - a valid handle
  351.     flags       - valid WindowFlags, like e.g. WFLG_BACKDROP
  352.     future       - always NULL yet
  353.  
  354.    RESULT
  355.  
  356.     NULL or an adequate SVERR-Errorcode.
  357.  
  358.    SINCE
  359.  
  360.     ... Version 1 SVObjects.
  361.  
  362.    SEE ALSO
  363.  
  364.     SVO_Write
  365.  
  366. -----------------------------------------------------------------------------
  367.  
  368.    NAME
  369.     SVO_SetWindowIDCMP
  370.  
  371.    SYNOPSIS
  372.  
  373.     ULONG SVO_SetWindowIDCMP(APTR handle, ULONG idcmp, APTR future)
  374.     D0    -$54         A1          D1       A2
  375.  
  376.    FUNCTION
  377.  
  378.     Specifies, which IDCMP the Window should have, on which the
  379.     graphic is to be displayed later.
  380.  
  381.     This statement may have no effect, if the SVObject uses external
  382.     drivers for displaying (e.g. EGS.svdriver will ignore this
  383.     setting more or less).
  384.  
  385.    INPUT(S)
  386.  
  387.     handle - a valid handle
  388.     idcmp  - a valid set of IDCMP-Flags
  389.     future - always NULL yet
  390.  
  391.    RESULT
  392.  
  393.     NULL or an adequate SVERR-Errorcode.
  394.  
  395.    SINCE
  396.  
  397.     ... Version 1 SVObjects.
  398.  
  399.    SEE ALSO
  400.  
  401.     SVO_Show
  402.  
  403. -----------------------------------------------------------------------------
  404.  
  405.    NAME
  406.     SVO_GetScreenAddress
  407.  
  408.    SYNOPSIS
  409.  
  410.     struct Screen *SVO_GetScreenAddress(APTR handle, future)
  411.     D0           -$5a            A1         A2
  412.  
  413.    FUNCTION
  414.  
  415.     While displaying, the Address of the DisplayScreen can be get
  416.     via this function.
  417.     See description there and example SourceCodes for more and
  418.     detailed information.
  419.  
  420.    INPUT(S)
  421.  
  422.     handle - a valid handle
  423.     future - always NULL yet
  424.  
  425.    RESULT
  426.  
  427.     A valid ScreenPointer or NULL.
  428.  
  429.    SINCE
  430.  
  431.     ... Version 1 SVObjects.
  432.  
  433.    SEE ALSO
  434.  
  435.     SVO_GetWindowAddress
  436.  
  437. -----------------------------------------------------------------------------
  438.  
  439.    NAME
  440.     SVO_GetWindowAddress
  441.  
  442.    SYNOPSIS
  443.  
  444.     struct Window *SVO_GetWindowAddress(APTR handle, future)
  445.     D0           -$60            A1         A2
  446.  
  447.    FUNCTION
  448.  
  449.     While displaying, the Add