$VER: Reference_ENG.doc V2.1 (26.5.94) © 1994 by Andreas R. Kleinert. All rights reserved. - Feel free to translate this Doc-File into other languages. - Andreas R. Kleinert Grube Hohe Grethe 23 D-57074 Siegen Germany * DO _NEVER_ ACCESS ANY SVOBJECTS DIRECTLY. * DO NEVER BYPASS superview.library ! THE FOLLOWING NOTES ARE ONLY FOR PROGRAMMERS OF SVOBJECTS : Here is a listing of the function set, which any of the version 1 and version 2 SVObjects does contain, in an Autodoc-like style of description : SVO_AllocHandle ; since Version 1 SVO_FreeHandle SVO_Show SVO_Write SVO_CloseDisplay SVO_FreeResources SVO_SetAccessMode SVL_SetScreenType SVO_SetWindowFlags SVO_SetWindowIDCMP SVO_GetScreenAddress SVO_GetWindowAddress SVO_SetScreenAddress SVO_SetWindowAddress SVO_SetWriteName SVO_SetReadName SVO_FileInfoRequest SVO_CheckFileType SVO_ReadToGfxBuffer ; since Version 2 SVO_GetGfxBuffer SVO_SetGfxBuffer (you will never find any notes belonging to "BUGS", because any SVObject may have its own ...) ----------------------------------------------------------------------------- Functions available since Version 1 : ----------------------------------------------------------------------------- NAME SVO_AllocHandle SYNOPSIS APTR SVO_AllocHandle(APTR future) D0 -$1e A1 FUNCTION Allocates a handle for accessing a Graphic via this SVObject. INPUT(S) future - always NULL yet RESULT A pointer to a new allocated Handle or NULL, if allocation failed. WARNING Test, if the result was NULL, or not ! SINCE ... Version 1 SVObjects. SEE ALSO SVO_FreeResources, SVO_FreeHandle ----------------------------------------------------------------------------- NAME SVO_FreeHandle SYNOPSIS VOID SVO_FreeHandle(APTR handle) D0 -$24 A1 FUNCTION Stops showing, frees all Resources and delocates a Handle, which has been allocated with SVO_AllocHandle before. For programmers of SVObjects : Note, that this function should call SVO_CloseDisplay(SVHandle); SVO_FreeResources(SVHandle); always. Otherwise memory might be lost. INPUT(S) handle - a valid handle RESULT - SINCE ... Version 1 SVObjects. SEE ALSO SVO_AllocHandle, SVO_CloseDisplay, SVO_FreeResources ----------------------------------------------------------------------------- NAME SVO_Show SYNOPSIS ULONG SVO_Show(APTR handle) D0 -$2a A1 FUNCTION Loads and shows the Graphic described by a previously set FileName or just shows the Graphic, if already been loaded. Showing can be stopped either via full delocation of the handle or via Closing the Display with SVO_CloseDisplay. INPUT(S) handle - a valid handle RESULT NULL or an adequate SVERR-Errorcode. SINCE ... Version 1 SVObjects. SEE ALSO SVO_AllocHandle, SVO_CloseDisplay, SVO_FreeHandle ----------------------------------------------------------------------------- NAME SVO_Write SYNOPSIS ULONG SVO_Write(APTR handle) D0 -$30 A1 FUNCTION Writes the currently loaded (GfxBuffer) or displayed (Screen) graphic into a file or onto any other medium, which has been specified via the appropriate function calls before. INPUT(S) handle - a valid handle RESULT NULL or an adequate SVERR-Errorcode. SINCE ... Version 1 SVObjects. SEE ALSO SVO_AllocHandle, SVO_FreeHandle ----------------------------------------------------------------------------- NAME SVO_CloseDisplay SYNOPSIS VOID SVO_CloseDisplay(APTR handle) D0 -$36 A1 FUNCTION Stops showing the Graphic, indentified by the handle. The Display-Screen is closed, but no Resources are given free. INPUT(S) handle - a valid handle RESULT - SINCE ... Version 1 SVObjects. SEE ALSO SVO_FreeResources, SVO_FreeHandle ----------------------------------------------------------------------------- NAME SVO_FreeResources SYNOPSIS VOID SVO_FreeResources(APTR handle) D0 -$3c A1 FUNCTION Frees all resources belonging to the specific Graphic, indentified by the handle, which are not needed to just show it. The Display will not be closed. Note, that SVO_FileInfoRequest() will no longer work, then ("No file loaded" or similar request appears). INPUT(S) handle - a valid handle RESULT - SINCE ... Version 1 SVObjects. SEE ALSO SVO_AllocHandle, SVO_CloseDisplay, SVO_FreeHandle ----------------------------------------------------------------------------- NAME SVO_SetAccessMode SYNOPSIS ULONG SVO_SetAccessMode(APTR handle, ULONG mode) D0 -$42 A1 D1 FUNCTION Initializes a Handle e.g. for AmigaDOS access, so that the separately specified AmigaDOS FileName will be used. Another possibility is sometimes to initialize Handles for ClipBoard Access (depending on the specific SVObject, e.g. IFF-ILBM). INPUT(S) handle - a valid handle mode - one of the supported "medium" Flags RESULT NULL or an adequate SVERR-Errorcode. SINCE ... Version 1 SVObjects. SEE ALSO SVO_SetWriteName ----------------------------------------------------------------------------- NAME SVL_SetScreenType SYNOPSIS ULONG SVL_SetScreenType(APTR handle, ULONG type, APTR future) D0 -$48 A1 D1 A2 FUNCTION Specifies, which ScreenType the Screen should have, on which the graphic is to be displayed later. This statement may have no effect, if the SVObject uses external drivers for displaying (e.g. EGS.svdriver will ignore this setting more or less). INPUT(S) handle - a valid handle type - a ScreenType descriptor, like e.g. CUSTOMSCREEN future - always NULL yet RESULT NULL or an adequate SVERR-Errorcode. SINCE ... Version 1 SVObjects. SEE ALSO SVO_GetScreenAddress ----------------------------------------------------------------------------- NAME SVO_SetWindowFlags SYNOPSIS ULONG SVO_SetWindowFlags(APTR handle, ULONG flags, APTR future) D0 -$4e A1 D1 A2 FUNCTION Specifies, which Flags the Window should have, on which the graphic is to be displayed later. This statement may have no effect, if the SVObject uses external drivers for displaying (e.g. EGS.svdriver will ignore this setting more or less). INPUT(S) handle - a valid handle flags - valid WindowFlags, like e.g. WFLG_BACKDROP future - always NULL yet RESULT NULL or an adequate SVERR-Errorcode. SINCE ... Version 1 SVObjects. SEE ALSO SVO_Write ----------------------------------------------------------------------------- NAME SVO_SetWindowIDCMP SYNOPSIS ULONG SVO_SetWindowIDCMP(APTR handle, ULONG idcmp, APTR future) D0 -$54 A1 D1 A2 FUNCTION Specifies, which IDCMP the Window should have, on which the graphic is to be displayed later. This statement may have no effect, if the SVObject uses external drivers for displaying (e.g. EGS.svdriver will ignore this setting more or less). INPUT(S) handle - a valid handle idcmp - a valid set of IDCMP-Flags future - always NULL yet RESULT NULL or an adequate SVERR-Errorcode. SINCE ... Version 1 SVObjects. SEE ALSO SVO_Show ----------------------------------------------------------------------------- NAME SVO_GetScreenAddress SYNOPSIS struct Screen *SVO_GetScreenAddress(APTR handle, future) D0 -$5a A1 A2 FUNCTION While displaying, the Address of the DisplayScreen can be get via this function. See description there and example SourceCodes for more and detailed information. INPUT(S) handle - a valid handle future - always NULL yet RESULT A valid ScreenPointer or NULL. SINCE ... Version 1 SVObjects. SEE ALSO SVO_GetWindowAddress ----------------------------------------------------------------------------- NAME SVO_GetWindowAddress SYNOPSIS struct Window *SVO_GetWindowAddress(APTR handle, future) D0 -$60 A1 A2 FUNCTION While displaying, the Address of the DisplayWindow can be get via this function. See description there and example SourceCodes for more and detailed information. INPUT(S) handle - a valid handle future - always NULL yet RESULT A valid WindowPointer or NULL. SINCE ... Version 1 SVObjects. SEE ALSO SVO_GetScreenAddress ----------------------------------------------------------------------------- NAME SVO_SetScreenAddress SYNOPSIS ULONG SVO_SetScreenAddress(APTR handle, struct Screen *sc, APTR future) D0 -$66 A1 A2 A3 FUNCTION Sets the address of a Screen, which should be used as the Source for the next write action. See description there and example SourceCodes for more and detailed information. INPUT(S) handle - a valid handle sc - a valid ScreenPointer future - always NULL yet RESULT NULL or an adequate SVERR-Errorcode. SINCE ... Version 1 SVObjects. SEE ALSO SVO_SetWindowAddress ----------------------------------------------------------------------------- NAME SVO_SetWindowAddress SYNOPSIS ULONG SVO_SetWindowAddress(APTR handle, struct Window *wi, APTR future) D0 -$6c A1 A2 A3 FUNCTION Sets the address of a Window, which should be used as the Source for the next write action. See description there and example SourceCodes for more and detailed information. INPUT(S) handle - a valid handle wi - a valid WindowPointer future - always NULL yet RESULT NULL or an adequate SVERR-Errorcode. SINCE ... Version 1 SVObjects. SEE ALSO SVO_SetScreenAddress ----------------------------------------------------------------------------- NAME SVO_SetWriteName SYNOPSIS ULONG SVO_SetWriteName(APTR handle, UBYTE *name, APTR future) D0 -$72 A1 A2 A3 FUNCTION Sets a filename for the next write action. INPUT(S) handle - a valid handle name - a valid AmigaDOS FileName future - always NULL yet RESULT NULL or an adequate SVERR-Errorcode. SINCE ... Version 1 SVObjects. SEE ALSO SVO_SetReadName ----------------------------------------------------------------------------- NAME SVO_SetReadName SYNOPSIS ULONG SVO_SetReadName(APTR handle, UBYTE *name, APTR future) D0 -$78 A1 A2 A3 FUNCTION Sets a filename for the next read action. INPUT(S) handle - a valid handle name - a valid AmigaDOS FileName future - always NULL yet RESULT NULL or an adequate SVERR-Errorcode. SINCE ... Version 1 SVObjects. SEE ALSO SVO_SetWriteName ----------------------------------------------------------------------------- NAME SVO_FileInfoRequest SYNOPSIS ULONG SVO_FileInfoRequest(APTR handle, struct Window *window, D0 -$7e A1 A2 APTR future) A3 FUNCTION Pops up an Info-Requester with more or less detailed information on the currently loaded Graphic. A window pointer may be given to select the place to pop it up. Note, that this function will fail, if you already called SVO_FreeResources() (might result in a "No file loaded" message) ! INPUT(S) handle - a valid handle window - a valid Window Pointer or NULL future - always NULL yet RESULT NULL or an adequate SVERR-Errorcode. SINCE ... Version 1 SVObjects. SEE ALSO - ----------------------------------------------------------------------------- NAME SVO_CheckFileType SYNOPSIS ULONG SVO_CheckFileType(BPTR filehandle, UBYTE *filename, D0 -$84 A1 A2 struct SVOCheckFile *svo_check) A3 FUNCTION Checks, if the given file (or ClipBoard entry, or whatever) fits to this SVObject and can be handled therein. Since Version 4 of superview.library ClipBoard-Support with external SVObjects would not have worked at all. Since V4 the specification of external Version 2 SVObjects has been modified to allow ClipBoard and other media usage : To preserve compatibility, this has been done by using the "future" parameter as a pointer to a structure (defined in "include:svobjects/svobjects.h"), which contains media information. This pointer may be NULL, so that you have to assume default settings, if there's not such a structure. For disk-access, this pointer will not be set at all, anyway. Also be prepared, to handle NULL pointers to filename : if ClipBoard usage is forced, there will no filename be needed. If you don't support any filename-less medias, just do a silent exit. Currently - for compatibility reasons - superview.library will supply a dummy filename and a dummy file for those SVObjects, which may not handle a NULL pointer correctly. So handle SVOCheckFile structures with a HIGHER priority, because currently there's always a dummy-file (mostly empty) available. INPUT(S) handle - a valid handle name - a valid AmigaDOS FileName svo_check - a pointer to a SVOCheckFile structure or NULL for disk-access (default) RESULT NULL or an adequate SVERR-Errorcode. SINCE ... Version 1 SVObjects. SEE ALSO - ----------------------------------------------------------------------------- Functions added with Version 2 : ----------------------------------------------------------------------------- NAME SVO_ReadToGfxBuffer SYNOPSIS ULONG SVO_ReadToGfxBuffer(APTR handle) D0 -$8a A1 FUNCTION Does a read action to a GfxBuffer, using the current settings for FileName and medium. This Buffer may be displayed via SVO_Show and/or exported via SVO_GetGfxBuffer. INPUT(S) handle - a valid handle RESULT NULL or an adequate SVERR-Errorcode. SINCE ... Version 2 SVObjects. SEE ALSO SVO_Show, SVO_GetGfxBuffer ----------------------------------------------------------------------------- NAME SVO_GetGfxBuffer SYNOPSIS ULONG SVO_GetGfxBuffer(APTR handle, struct SV_GfxBuffer **buffer, D0 -$90 A1 A2 ULONG future) A3 FUNCTION Initializes a given pointer with the address to the GfxBuffer for the currently loaded Graphic. This Buffer MUST NOT be given free by handle (use SVO_FreeHandle or SVO_FreeResources on the main handle) and may still be displayed via SVO_Show or saved anywhere else. INPUT(S) handle - a valid handle buffer - a pointer to a SV_GfxBuffer pointer, which should be initialized with a valid pointer future - always NULL yet RESULT NULL or an adequate SVERR-Errorcode. SINCE ... Version 2 SVObjects. SEE ALSO SVO_ReadToGfxBuffer, SVO_Show, SVO_SetGfxBuffer, SVO_Write ----------------------------------------------------------------------------- NAME SVO_SetGfxBuffer SYNOPSIS ULONG SVO_SetGfxBuffer(APTR handle, struct SV_GfxBuffer *buffer, D0 -$90 A1 A2 ULONG future) A3 FUNCTION Initializes the given handle with a pointer to a SV_GfxBuffer, which should be used for the next write action. This Buffer STILL HAS TO BE GIVEN FREE the way it has been allocated (usually via a SVO_FreeHandle or SVO_FreeResources call with the origin handle) and may still be displayed via SVO_Show or saved anywhere else. INPUT(S) handle - a valid handle buffer - a pointer to a SV_GfxBuffer pointer, which should be used to initialize the handle for a write action future - always NULL yet RESULT NULL or an adequate SVERR-Errorcode. SINCE ... Version 2 SVObjects. SEE ALSO SVO_ReadToGfxBuffer, SVO_Show, SVO_GetGfxBuffer, SVO_Write -----------------------------------------------------------------------------