The AGA Experience 2

home *** CD-ROM | disk | FTP | other *** search

/ The AGA Experience 2 / agavol2.iso / software / utilities / wb_tools / swazblanker / programmer / autodoc / matrix.doc next >

Wrap

Text File | 1995-05-18 | 71.7 KB | 2,886 lines

TABLE OF CONTENTS matrix.library/--Event_FontGadgetNew-- matrix.library/--MX_FormatMXSB-- matrix.library/--MX_ScreenButton_Remake-- matrix.library/--background-- matrix.library/MX_AddArexxPort matrix.library/MX_AddNodeSorted matrix.library/MX_AddVBlankNode matrix.library/MX_AllocMem matrix.library/MX_AllocVecStr matrix.library/MX_CDToAssigns matrix.library/MX_CPUName matrix.library/MX_CleanUpGList matrix.library/MX_CloneListByName matrix.library/MX_CloseForm matrix.library/MX_CloseWinSafe matrix.library/MX_CompressInfo matrix.library/MX_CompressTrue matrix.library/MX_CurrentTime matrix.library/MX_DeCompress matrix.library/MX_DeCompressTrue matrix.library/MX_DeleteDirectory matrix.library/MX_DisplayRequest matrix.library/MX_DisplayRequestWin matrix.library/MX_DosOpen matrix.library/MX_ExamineDir matrix.library/MX_Free8SVX matrix.library/MX_FreeArgs matrix.library/MX_FreeFIB matrix.library/MX_FreeFont matrix.library/MX_FreeList matrix.library/MX_FreeListNodes matrix.library/MX_FreeMem matrix.library/MX_FullWBArgName matrix.library/MX_GetCatalogStr matrix.library/MX_GetFont matrix.library/MX_HexStrLong matrix.library/MX_HookTag matrix.library/MX_HookTagOrdered matrix.library/MX_JustifyText matrix.library/MX_ListToArray matrix.library/MX_Load8SVX matrix.library/MX_LoadFIB matrix.library/MX_LoadFile matrix.library/MX_LoadIFF matrix.library/MX_LockMxBase matrix.library/MX_MakeMenu_Localize matrix.library/MX_MakePath matrix.library/MX_ModifyListview matrix.library/MX_NewLoadIFF matrix.library/MX_NewPrefsWH matrix.library/MX_NewReadArgs matrix.library/MX_NewSaveIFF matrix.library/MX_NewSortList matrix.library/MX_NextForm matrix.library/MX_OpenForm matrix.library/MX_OpenFormReq matrix.library/MX_OpenPathNew matrix.library/MX_PatternMatch matrix.library/MX_ProcessArexxPort matrix.library/MX_QuickSort matrix.library/MX_Random matrix.library/MX_RandomInRange matrix.library/MX_RandomSeed matrix.library/MX_RawFormat matrix.library/MX_ReadArgs matrix.library/MX_ReadForm matrix.library/MX_ReadFormTagList matrix.library/MX_RemArexxPort matrix.library/MX_RemVBlankNode matrix.library/MX_RemakeGadgets matrix.library/MX_ReplaceTags matrix.library/MX_ReplaceVecStr matrix.library/MX_SaveIFF matrix.library/MX_SeekForm matrix.library/MX_SelectGadget matrix.library/MX_SendArexxString matrix.library/MX_SetListView matrix.library/MX_SetWaitPointer matrix.library/MX_ShowWindow matrix.library/MX_SortList matrix.library/MX_SoundID matrix.library/MX_StrCpyLen matrix.library/MX_StrCpyWord matrix.library/MX_StrLen matrix.library/MX_TaskName matrix.library/MX_TextFileToList matrix.library/MX_TimeString matrix.library/MX_UnlockMxBase matrix.library/MX_UnlockWindow matrix.library/MX_UpdateVBLankInterrupt matrix.library/MX_WhereAmI matrix.library/MX_WindowHandler matrix.library/MX_WrapText matrix.library/MX_WriteForm matrix.library/MX_WriteFormTagList matrix.library/--Event_FontGadgetNew-- matrix.library/--Event_FontGadgetNew-- PURPOSE This function is private. SYNTAX Event_FontGadgetNew(gadget,IMsg,whStruct) a1 a4 a5 SEE ALSO MX_WindowHandler(), MX_CreateGadgets(). matrix.library/--MX_FormatMXSB-- matrix.library/--MX_FormatMXSB-- PURPOSE This function is private. Formats the text used by screen mode gadgets. SYNTAX MX_FormatMXSB(mxScreenButtonData,mxBase) a0 a6 struct MxScreenModeButton *mxScreenButtonData; INPUTS mxScreenButtonData = pointer to data field made by MX_CreateGadgets() to track information. This can be obtained from the gadgets userdata field. RESULT None. SEE ALSO MX_WindowHandler(), MX_CreateGadgets(). matrix.library/--MX_ScreenButton_Remake-- matrix.library/--MX_ScreenButton_Remake-- PURPOSE This function is private. Refreshes the screenmode gadget. SYNTAX MX_ScreenButton_Remake(gad,win,mxBase) a0 a1 a6 struct Gadget *gad; struct Window *win; INPUTS gad = pointer to a mxScreenMode gadget made by MX_CreateGadgets(). This will be refreshed to reflect any changes made in its data storage area. win = pointer to window containing gadget. RESULT None. SEE ALSO MX_WindowHandler(), MX_CreateGadgets(). matrix.library/--background-- matrix.library/--background-- PURPOSE Unknown. OVERVIEW All information contained in this document is confidentional and may not be distributed. matrix.library/MX_AddArexxPort matrix.library/MX_AddArexxPort NAME MX_AddArexxPort -- add a public arexx message port. (V23) SYNOPSIS port = MX_AddArexxPort(name,hook,[userdata]) d0 a0 a1 [d0] struct MsgPort *port; STRPTR name; APTR hook; LONG userdata; FUNCTION Add an arexx port to the system public port list safely. INPUTS name - pointer to name of the public port. This name is copied into public memory using MX_AllocVecStr(). It is therefore necessary to call MX_RemArexxPort() when removing the arexx port so that this memory may also be deallocated. hook - pointer to user function that is called when a port is found with the same name as the one we wish to create. The hook is invoked as follows: result = userhook(port,userdata) d0 a0 a0 RESULT port = pointer to created message port or NULL if a port with the same name has been found (the user hook would have been invoked) or we are unable to allocate sufficient memory. NOTES The userhook callback is called within a Forbid() permit so that the port is unable to go away, unless the task goes into a Wait(). Also the result return value should always return NULL. This may be used at a later stage for a retry/cancel mode. SEE ALSO MX_RemArexxPort(), MX_ProcessArexxPort(), MX_AllocVecStr(), exec.library/FindPort(), exec.library/CreateMsgPort(), exec.library/AddPort(), exec.library/Forbid(), exec.library/Permit(), exec.library/Wait(). matrix.library/MX_AddNodeSorted matrix.library/MX_AddNodeSorted NAME MX_AddNodeSorted -- add node to linked list (V22) SYNOPSIS pos = MX_AddNodeSorted(list,node) d0 a0 a1 ULONG pos; APTR list; APTR node; FUNCTION Add a node into a linked list into prioritized alphbetic order. INPUTS pos = position added into list list = pointer to initialized list head. node = node to add into the list in prioritized alphabetic order. Make sure the LN_PRI and LN_NAME fields are set. RESULT None NOTES Make sure the LN_PRI field of each node is set, if you do not want a prioritized sort then set this to zero for all nodes. SEE ALSO MX_SortList() matrix.library/MX_AddVBlankNode matrix.library/MX_AddVBlankNode NAME MX_AddVBlankNode -- add vblank server hook or signal (V23) SYNOPSIS vbn = MX_AddVBlankNode(tags) d0 a0 struct MXVBlankNode *vbn; struct TagItem *tags; FUNCTION Add hook or signal to the matrix vblank interrupt server. INPUTS tags = pointer to a tagitem array. RESULT vbn = pointer to allocated vblank node or NULL if failed. TAGS MXVB_HookAddress (APTR) - set a hook routine to call when a vertical blank occurs. The hook is called as follows: userhook(vbn,userdata)(a0,d0) This tag is mutually exclusive to MXVB_SigBit. MXVB_UserData (ULONG) - user definable field passed to hook function. MXVB_SigBit (UBYTE) - this will be the signal bit to signal the task that is adding the vblank node. This tag is mutually exclusive to MXVB_HookAddress. MXVB_Count (BYTE) - number of vertical blanks that are to occur before the hook address of signal is called. SEE ALSO MX_RemVBlankNode(), MX_UpdateVBLankInterrupt() matrix.library/MX_AllocMem matrix.library/MX_AllocMem NAME MX_AllocMem -- OBSOLETE FUNCTION SYNOPSIS mem = MX_AllocMem(size) d0 d0 matrix.library/MX_AllocVecStr matrix.library/MX_AllocVecStr NAME MX_AllocVecStr -- alloc a string and buffer (V23) SYNOPSIS mem = MX_AllocVecStr(string,attributes) d0 a0 d1 APTR mem; STRPTR string; ULONG attributes; FUNCTION Allocates a buffer for the string and copys the string into the buffer. INPUTS string = pointer to a string. attributes = exec.library/AllocVec() memory attributes. RESULT Pointer to buffer containing the string, or NULL if not enough memory for the buffer. NOTE Use exec.library/FreeVec() to deallocate the buffer. SEE ALSO MX_ReplaceVecStr(), exec.library/AllocVec(), exec.library/FreeVec() matrix.library/MX_CDToAssigns matrix.library/MX_CDToAssigns NAME MX_CDToAssigns -- change directory to all assigns SYNOPSIS success = MX_CDToAssigns(name,hook,[userdata]) d0 a0 a1 [d0] BOOLEAN success; STRPTR name; APTR hook; ULONG userdata; INPUTS name = hook = userdata = RESULT TRUE if successful SEE ALSO matrix.library/MX_CPUName matrix.library/MX_CPUName NAME MX_CPUName -- get the type of CPU SYNOPSIS name = MX_CPUName(attnflag,tags) a0 d0 d1 INPUTS attnflag = as per execbase tags = none defined. Leave this as NULL RESULT name = pointer to description of CPU NOTES Please not that a2 *IS* trashed a1 = *FPUName a2 = *MMUName matrix.library/MX_CleanUpGList matrix.library/MX_CleanUpGList NAME MX_CleanUpGList -- Dispose of the gadgets SYNOPSIS MX_CleanUpGList(firstGadget,Number) d0 d1 struct Gadget *firstGadget; ULONG Number; FUNCTION Deallocates structures allocated for the gadgets set up by MX_CreateGadgets() INPUTS firstGadget = pointer to first gadget. NULL does nothing. Number = number of gadgets to cleanup. RESULT None SEE ALSO MX_CreateGadgets(), MX_RemakeGadgets() matrix.library/MX_CloneListByName matrix.library/MX_CloneListByName NAME matrix.library/MX_CloneListByName -- Duplicate a list by name only. SYNOPSIS list = MX_CloneListByName(sourcelist,function,tags) d0 a0 a1 a2 STRUCT list *list; STRUCT list *sourcelist; APTR function; struct TagItem *tags; FUNCTION Creates a list based upon the source list. If no user function is provided the created list is a duplicate list of the node names of the source list only. If the user function is provided then the created list is a list of the names returned by the function. INPUTS list - pointer to source list. function - pointer to user function or NULL. The user function fills a buffer with the required node name based upon the source node. The user function is called as: result = Function(buffer,node) d0 a0 a1 If the result returned is FALSE then the buffer will not be added to the list. tags - none available. RESULT list - pointer to list, use MX_FreeList() to deallocate. TAGS None available. NOTES The buffer is currently only 200 bytes long. Tags may be provided later to change this. SEE ALSO MX_FreeList() matrix.library/MX_CloseForm matrix.library/MX_CloseForm NAME MX_CloseForm -- OBSOLETE FUNCTION SYNOPSIS MX_CloseForm(formhandle) d0 matrix.library/MX_CloseWinSafe matrix.library/MX_CloseWinSafe NAME MX_CloseWinSafe -- close a window with a shared IDCMP port. (V22) SYNOPSIS MX_CloseWinSafe(window) a0 struct Window *window; FUNCTION Detaches the IDCMP port from a window before closing and removes and replies any outstanding messages. INPUTS window = pointer to window to close. RESULT None. SEE ALSO intuition.library/CloseWindow() matrix.library/MX_CompressInfo matrix.library/MX_CompressInfo NAME MX_CompressInfo -- query buffer compression (V24) SYNOPSIS buffer, length = MX_CompressInfo(srcData) a0 d0 a0 APTR buffer ULONG length APTR srcData FUNCTION How long is the decompressed buffer. INPUTS srcData = Pointer to compressed data stream RESULT The length of the decompressed buffer. Returns ZERO if the buffer is not a matrix compression buffer. Also returns pointer to start of compressed data in a0. NOTES SEE ALSO MX_CompressTrue(), MX_CompressText(), MX_DeCompress(), MX_DeCompressTableSize(). matrix.library/MX_CompressTrue matrix.library/MX_CompressTrue NAME MX_CompressTrue -- compress a buffer (V24) SYNOPSIS buffer,length = MX_CompressTrue(srcData,srcLen) d0 d1 a0 d0 APTR buffer ULONG length APTR srcData ULONG srcLen FUNCTION Compress a buffer. INPUTS srcData = Pointer to sorce buffer srcLen = length of source data RESULT Pointer to compressed buffer. This should be freed using exec.library/FreeVec(). This buffer can be decompressed using MX_DeCompressTrue(). The length of the buffer is returned in d1. The length of the buffer when decompressed may be obtained from the buffer header which is as follows: STRUTURE MXCompressHeader,4 ; 4 byte identifier ULONG mxcp_Len LABEL mxcp_SIZE NOTES SEE ALSO MX_DeCompressTrue() matrix.library/MX_CurrentTime matrix.library/MX_CurrentTime NAME MX_CurrentTime() -- get the current time in seconds (V20) SYNOPSIS seconds = MX_CurrentTime() d0 FUNCTION Returns the current time in seconds. INPUTS None RESULT seconds - number of seconds elapsed since 01-Jan-1978. NOTE The number of microseconds is returned in d1. SEE ALSO intuition.library/CurrentTime(), timer.device/TR_GETSYSTIME matrix.library/MX_DeCompress matrix.library/MX_DeCompress NAME MX_DeCompress -- decompress a compressed buffer (V24) SYNOPSIS result = MX_DeCompress(srcData,destData,table) a0 a0 a1 a2 APTR srcData APTR destData APTR table APTR result FUNCTION Decompress data compressed with MX_Compress() INPUTS srcData = Pointer to compressed source stream destData = Pointer to destination data table = Pointer to an area for the hash tables, of size found with MX_DecompessTableSize(). RESULT Pointer to end of compressed data. NOTES SEE ALSO MX_Compress(), MX_DeCompress() matrix.library/MX_DeCompressTrue matrix.library/MX_DeCompressTrue NAME MX_DeCompressTrue -- decompress a buffer (V24) SYNOPSIS buffer, length = MX_DeCompressTrue(srcData) d0 d1 a0 APTR buffer ULONG length APTR srcData FUNCTION Decompress a buffer compressed with MX_CompressText() or MX_CompressTrue(). INPUTS srcData = Pointer to compressed data stream RESULT Pointer to decompressed buffer. This should be freed using exec.library/FreeVec(). NOTES SEE ALSO MX_CompressTrue(), MX_CompressText(), MX_DeCompress(), MX_DeCompressTableSize(). matrix.library/MX_DeleteDirectory matrix.library/MX_DeleteDirectory NAME MX_DeleteDirectory -- delete a diretory and its contents. (V22) SYNOPSIS success = MX_DeleteDirectory(name,tags) d0 a0 d0 BOOL success; STRPTR name; struct TagList *tags; FUNCTON Deletes a directory and all subdirectories and files. INPUTS name = pointer to directory path. tags = pointer to a taglist. None are supported. RESULT success = TRUE if successful, FALSE otherwise. SEE ALSO dos.library/DeleteFile(), MX_MakePath() matrix.library/MX_DisplayRequest matrix.library/MX_DisplayRequest NAME MX_DisplayRequest -- display a request to the user (V23) SYNOPSIS result = MX_DisplayRequest(body,buttons,data) d0 a0 a1 a2 ULONG result; STRPTR body; STRPTR buttons; APTR data; FUNCTON Displays a request to the user either by an intuition requestor or with output to cli, depending on where the task was run from. INPUTS body = pointer to format string for the body text. If NULL then this function performs no action. buttons = pointer to format string for the buttons data = data for the formatting strings RESULT 0, 1, ..., N = Successive GadgetID values, for the gadgets you specify for the requester. NOTE: The numbering from left to right is actually: 1, 2, ..., N, 0. NOTES Currently under V23 when run from the CLI this function only displays the body text and will return 0. SEE ALSO MX_DisplayRequestWin(), exec.library/RawDoFmt(), intuition.library/EasyRequestArgs() dos.library/VPrintf() matrix.library/MX_DisplayRequestWin matrix.library/MX_DisplayRequestWin NAME MX_DisplayRequestWin -- display a request to the user (V24) SYNOPSIS result = MX_DisplayRequestWin(body,buttons,data,window) d0 a0 a1 a2 d0 ULONG result; STRPTR body; STRPTR buttons; APTR data; struct Window *window; FUNCTON Displays a request to the user either by an intuition requestor. INPUTS body = pointer to format string for the body text. If NULL then this function performs no action. buttons = pointer to format string for the buttons data = data for the formatting strings window = pointer to window to disable. RESULT 0, 1, ..., N = Successive GadgetID values, for the gadgets you specify for the requester. NOTE: The numbering from left to right is actually: 1, 2, ..., N, 0. SEE ALSO MX_DisplayRequest(), exec.library/RawDoFmt(), intuition.library/EasyRequestArgs() dos.library/VPrintf() matrix.library/MX_DosOpen matrix.library/MX_DosOpen NAME MX_DosOpen -- open a file SYNOPSIS filehandle = MX_DosOpen(filename,path,mode) d0 a0 a1 d0 INPUTS filename = path = mode = RESULT filehandle is NULL if file could not be opened SEE ALSO dos.library/Open(), dos.library/Close() matrix.library/MX_ExamineDir matrix.library/MX_ExamineDir NAME MX_ExamineDir -- examine entries in a directory (V21) SYNOPSIS lock = MX_ExamineDir(hook,[data],lock) d0 a0 d0 d1 BPTR lock; APTR hook; BPTR lock; LONG data; FUNCTION Examine a directory INPUTS hook = pointer to hook function called as follows: continue = Hook(fib,data) d0 a0 d0 BOOLEAN continue; struct FileInfoBlock *fib; LONG data; The hook function should return 0 for abort, and 1 to continue with the directory read. lock = pointer to a directory that has been locked. data = user definable value passed to hook function. RESULT lock = the same value as the lock passed in. NOTES This function will change the CurrentDir to the directory being examined (V23) BUGS Prior to V23 the hook function did not return a continuation condition, this has been added to V23. Some programs will not function correctly and should be updated. SEE ALSO dos.library/Lock(), dos.library/Examine(), dos.library/ExNext(), dos.library/CurrentDir() matrix.library/MX_Free8SVX matrix.library/MX_Free8SVX NAME MX_Free8SVX -- OBSOLETE FUNCTION SYNOPSIS MX_Free8SVX(mx8SVX) d0 matrix.library/MX_FreeArgs matrix.library/MX_FreeArgs NAME MX_FreeArgs -- Free allocated memory after MX_ReadArgs() (V23) SYNOPSIS MX_FreeArgs(MXArgLock) a0 struct *MXArgLock; INPUTS MXArgLock - pointer returned by MX_ReadArgs or NULL for no action. RESULT None. SEE ALSO matrix.library/MX_FreeArgs(), dos.library/FreeArgs() dos.library/ReadArgs(), dos.library/ReadItem(), dos.library/FindArg() matrix.library/MX_FreeFIB matrix.library/MX_FreeFIB NAME MX_FreeFIB -- deallocate the FIB from MX_LoadFIB() SYNOPSIS MX_FreeFIB(fib) d0 SEE ALSO MX_LoadFIB, dos.library/AllocDosObject(), dos.library/Examine() matrix.library/MX_FreeFont matrix.library/MX_FreeFont NAME MX_FreeFont -- Frees the font allocated. (V23) SYNOPSIS MX_FreeFont(textattr,font,tags) a0 a1 a2 struct TextAttr *textattr; struct TextFont *font; struct TagItem *tags; FUNCTION Frees any resources taken by MX_GetFont(). The textattr structure will be initialized to zeros. INPUTS textattr = pointer to textattr structure that was filled by MX_GetFont(). font = as returned by MX_GetFont(). tags = pointer to a taglist (NULL). TAGS None. RESULT None. SEE ALSO MX_GetFont(), graphics.library/CloseFont() matrix.library/MX_FreeList matrix.library/MX_FreeList NAME MX_FreeList -- free the entire list (V22) SYNOPSIS MX_FreeList(list,hook,[userdata]) a0 a1 [d0] APTR head; APTR hook; LONG userdata; FUNCTION Frees an entire list. INPUTS head = pointer to list head or NULL. hook = pointer to hook function. See MX_FreeListNodes(). RESULT None. NOTES The list head is not freed by the user function, it is freed using exec.library/FreeVec(). The userdata parameter was added for V23 matrix.library. SEE ALSO exec.library/FreeVec(), MX_FreeListNodes() matrix.library/MX_FreeListNodes matrix.library/MX_FreeListNodes NAME MX_FreeListNodes -- free the nodes of a linked list (V22) SYNOPSIS MX_FreeListNodes(head,hook,[userdata]) a0 a1 [d0] APTR head; APTR hook; LONG userdata; FUNCTION Frees all nodes from a linked list, using specified userhook or internal routines. INPUTS head = pointer to list head. hook = pointer to hook function. If this is NULL then the node is freed using exec.library/FreeVec(), otherwise the userhook called as UserHook(node,userdata)(a1,d0). RESULT None. NOTES The userdata parameter was added for V23 matrix.library and is an optional parameter. SEE ALSO exec.library/FreeVec(), MX_FreeList(), MX_TextFileToList() matrix.library/MX_FreeMem matrix.library/MX_FreeMem NAME MX_FreeMem -- OBSOLETE FUNCTION SYNOPSIS MX_FreeMem(mem) a1 matrix.library/MX_FullWBArgName matrix.library/MX_FullWBArgName NAME MX_FullWBArgName -- full path name of wb argument (V21) SYNOPSIS success = MX_FullWBArgName(buffer,wbarg,len) d0 a0 a1 d0 ULONG success; STRPTR buffer; struct WbArg *wbarg; ULONG len; INPUTS buffer = pointer to the buffer to fill with the path name. wbarg = the wb argument (see workbench.library) len = length of the buffer. RESULT returns TRUE if successful. NOTES If the path is 'SPAM:' then this will be expanded to 'SPAM:disk'. SEE ALSO workbench.library matrix.library/MX_GetCatalogStr matrix.library/MX_GetCatalogStr NAME MX_GetCatalogStr -- get a localized string (V24) SYNOPSIS string = MX_GetCatalogStr(catalog,catCompArray,stringNum) d0 a0 a1 d0 FUNCTION Localizes a string id if required. INPUTS catalog = a message catalog. catCompArray = pointer to catCompArray stringNum = a message number within the catalog RESULT string = a pointer to a NULL-terminated string. The returned string is READ-ONLY, do NOT modify! This string pointer is valid only as long as the catalog remains open. NOTE If the CatCompArray is NULL then the STRPTR returned is actually the stringNum passed in. Make sure you have a pointer to a valid CatCompArray. The CatCompArray is of the following format: ULONG id ; id number STRPTR string ; . . . ULONG NULL If the first longword of the CatCompArray is -1 then the array is treated as a packed list of the following format ULONG id ; id number UWORD len ; length of string UBYTE string[len] ; always an even length, single or double null terminated . . . ULONG NULL SEE ALSO locale.library/GetCatalogStr() matrix.library/MX_GetFont matrix.library/MX_GetFont NAME MX_GetFont -- Fills out textattr structure. (V22) SYNOPSIS font = MX_GetFont(textattr,tags) d0 a0 a1 struct Font *font; struct TextAttr *textattr; struct TagItem *tags; FUNCTION Fills out a text attribute structure based on the default system font. The font pointer returned may be null. In wich case the textattr structure will be filled out to "topaz.font", size 8. It is not necessary to call MX_FreeFont() if the font returned is NULL. INPUTS textattr = pointer to textattr structure to be filled. tags = pointer to a taglist (NULL). TAGS MXGF_FontName (UBYTE *) - pointer to name of font to open. This tag is mutually inclusive to MXGF_FontSize. The default for this is the system font. An additional extension has been provided, you may specify the fontname and size in the same string using a space as a separator. Example: "topaz.font 8" or "topaz 8" MXGF_FontSize (WORD) - size of the font to open. This tag is mutually inclusive to MXGF_FontName. The defaut for this is the system font. MXGF_FontSizeStr (STRPTR) - this is functionally the same as MXGF_FontSize except that a string pointer is used. MXGF_UseScreenFont (struct Screen *) - pointer to the screen to obtain the font. This will overide the default for MXGF_FontName and MXGF_FontSize is no name and size are specified. (V23) RESULT font = pointer to font opened or NULL. SEE ALSO MX_FreeFont(), diskfont.library/OpenDiskFont() matrix.library/MX_HexStrLong matrix.library/MX_HexStrLong NAME MX_HexStrLong -- convert hex string to long (V19) SYNOPSIS value, success, next = MX_HexStrLong(string) d0 d1 a0 a0 STRPTR string; ULONG value; INPUTS string - pointer to valid hexadecimal string. This string may only contain a maximum of 8 characters selectable from "0,1,2,3,4,5,6,7,8,9,a,b,c,d,e,f". RESULT value = the value of the hexidecimal string. success = indication on wether the conversion was successful or not. next = pointer to the next byte to be processed in the string after the converted characters. NOTE SEE ALSO matrix.library/MX_HookTag matrix.library/MX_HookTag NAME MX_HookTag -- call hook function from tag array (V23) SYNOPSIS result = MX_HookTag(tagarray,defhook,tagvalue,data) d0 a0 a1 d0 d1 struct TagItem *tagarray; APTR defhook; LONG tagvalue; LONG data; INPUTS tagarray - pointer to array of tag items. The hook function is called as follows: Hook(data)(d0) defhook - hook to call if tag item not found. tagvalue - value of the tag item hook to call. data - data passed to hook function. RESULT return value from hook function or NULL if no hook function was invoked. NOTES When the hook function is called registers a4 and a5 are untouched. SEE ALSO MX_HookTagOrdered, utility.library/GetTagData() matrix.library/MX_HookTagOrdered matrix.library/MX_HookTagOrdered NAME MX_HookTagOrdered -- call hook function from tag array (V23) SYNOPSIS MX_HookTagOrdered(tagarray,defhook,tagvalue,data) a0 a1 d0 d1 struct TagItem *tagarray; APTR defhook; LONG tagvalue; LONG data; FUNCTION This routine is functions identically to MX_HookTag() except that the array must be in order. INPUTS tagarray - pointer to array of tag items. The hook function is called as follows: Hook(data)(d0) defhook - hook to call if tag item not found. tagvalue - value of the tag item hook to call. data - data passed to hook function. RESULT None. SEE ALSO MX_HookTag, utility.library/GetTagData() matrix.library/MX_JustifyText matrix.library/MX_JustifyText NAME MX_JustifyText -- justtify a buffer SYNOPSIS MX_JustifyText(source,dest,length) a0 a1 d0 APTR source; APTR dest; ULONG length; FUNCTION INPUTS source - pointer to source buffer to justify dest - pointer to buffer to store the justified source buffer length - length of the justify buffer RESULT None NOTE The source buffer must not exceed the length of the justfy. It is intended that the MX_WrapText() function be used before calling this routine to remove any partial word left on the end of the line. Any trailing spaces will be removed by this routine. BUGS SEE ALSO MX_WrapText() matrix.library/MX_ListToArray matrix.library/MX_ListToArray NAME MX_ListToArray -- convert a list into an array (V23) SYNOPSIS array,numelements = MX_ListToArray(list,tags,numElements) d0 d1 a0 a1 d0 FUNCTION Converts a list into array form, the array consists of pointers to the list nodes, terminated with a NULL pointer to indicate end of list. INPUTS list = pointer to list. tags = pointer to a tag item array. numelements = number of elements in the list, if 0 then the list will be traversed to calculate the number of entries. This value MUST NOT be less than the number of list entries. TAGS MXLTA_AddOffset (WORD) = offset relative to the node to use as the pointer. Default is 0. RESULT Pointer to array of pointers to list nodes, use exec.library/FreeVec() to deallocate. SEE ALSO MX_QuickSort() matrix.library/MX_Load8SVX matrix.library/MX_Load8SVX NAME MX_Load8SVX -- OBSOLETE FUNCTION SYNOPSIS MX_Load8SVX(filename,tags) a0 d0 matrix.library/MX_LoadFIB matrix.library/MX_LoadFIB SYNTAX fib,typedata = MX_LoadFIB(type,typedata) d0 d1 d0 d1 INPUTS type - specification of typedata, can be: LOADFIB_LOCK LOADFIB_FILEHANDLE LOADFIB_NAME typedata - lock, filehandle or pointer to filename. RESULTS fib - pointer to fileinfo block, NULL if failed. Use MX_FreeFib() to discard this fib when finished. SEE ALSO MX_FreeFIB, dos.library/AllocDosObject(), dos.library/Examine() matrix.library/MX_LoadFile matrix.library/MX_LoadFile SYNTAX buffer,length = MX_LoadFile(filename) d0 d1 a0 INPUTS filename = pointer to name fo file to load RESULTS buffer = pointer to buffer file read into, this is padded with a NULL byte. This is NULL if there is an error. To deallocate this buffer use exec.library/FreeVec(). length = the number of bytes successfully read (this is not the length of the buffer). SEE ALSO exec.library/FreeVec() matrix.library/MX_LoadIFF matrix.library/MX_LoadIFF NAME MX_LoadIFF() -- OBSOLETE SYNOPSIS iffhandle = MX_LoadIFF(iffhandle,filename,tags) d0 a0 a1 a2 matrix.library/MX_LockMxBase matrix.library/MX_LockMxBase NAME MX_LockMxBase -- Invoke semaphore arbitration of MxBase. SYNOPSIS MX_LockMxBase() FUNCTION This locks the MxBase so the data may be read/modified. INPUTS None. RESULT None. NOTE This call is guaranteed to preserve all registers. A call to this function MUST be paired with a subsequent call to MX_UnlockMxBase(), and soon, please. Do not call any Matrix functions while holding this lock, except for MX_UnlockMxBase(). SEE ALSO MX_UnlockMxBase() matrix.library/MX_MakeMenu_Localize matrix.library/MX_MakeMenu_Localize NAME MX_MakeMenu_Localize -- make menus localized SYNOPSIS newmenu= MX_MakeMenu_Localize(newmenu, catalog, catCompArr,tags) d0 a0 a1 a2 d0 struct NewMenu *newmenu struct NewMenu *newmenu struct Catalog *catalog APTR catCompArr struct TagItem *tags FUNCTION Make a menu using locale id's INPUTS newwmenu - pointer to GadTools NewMenu structure. catalog - pointer to locale catalog returned by locale.library/OpenCatalog(). catCompArr - array of locale strings tags - pointer to taglist. RESULT pointer to a localize newmenu array or NULL for failure. SEE ALSO gadtools.library/CreateMenusA(), locale.library/OpenCatalog() matrix.library/MX_MakePath matrix.library/MX_MakePath NAME MX_MakePath -- create an entire directory path (V22) SYNOPSIS success = MX_MakePath(path) d0 a0 BOOL success; STRPTR path; INPUTS path = pointer to path string. RESULT success = 0 if failure occurs. SEE ALSO dos.library/CreateDir(), MX_DeleteDirectory() matrix.library/MX_ModifyListview matrix.library/MX_ModifyListview NAME MX_ModifyListview -- change the list in a listview. SYNOPSIS MX_ModifyListview(gad,win,hook,data) a0 a1 a2 d0 struct Gadget *gad; struct Window *win; APTR hook; LONG data; FUNCTION Modifys a listview list, disables the list so that it may be modified and calls a hook function. The hook function returns a pointer to a list (generally the old list but modified.) The listview is then set to the new list. If no hook function is specified then the data parameter is used as the new list pointer. INPUTS gad - pointer to a listview gadget. win - pointer to a window. hook - pointer to user hook function or NULL. The hook function is called as follows: list = hook(data) d0 d0 data - if a hook function is provided then this is treated as a user data field, otherwise is the hook pointer is NULL this is used as a pointer to a list. RESULT None. NOTES If the gad and win pointers are both NULL then the hook function will still be called, just that no gadget will be updated. SEE ALSO gadtools.library/GT_SetGadgetAttrsA() matrix.library/MX_NewLoadIFF matrix.library/MX_NewLoadIFF NAME MX_NewLoadIFF -- load an IFF form file (V23) SYNOPSIS success = MX_NewLoadIFF(filename,tags) d0 a0 a1 ULONG success; STRPTR filename; struct TagItem *tags; FUNCTION Reads an iff FORM file given a hunk definition. INPUTS filename = pointer to name of file to open. tags = pointer to taglist. RESULT success = TRUE if file load was completed successfully. TAGS MXIF_Filename (UBYTE *) - pointer to name of file to open, this overides the parameter passed to this function. MXIF_Type (ULONG) - type of IFF file to process. Eg "PREF". MXIF_HunkArray (APTR) - pointer to NULL terminated array of hunk descriptors. The hunk descriptor is a structure as follows ULONG - Hunk name (Eg. "PRHD" ) ULONG - Hunk type ULONG - Data0 ULONG - Data1 MXIF_ValidateHook (APTR) - pointer to hook function called when the IFF file has been loaded. success = ValidateHook() SUPPORTED HUNK TYPES MXIF_Raw MXIF_HookMULTI MXIF_HookOWNCHUNK MXIF_STRING SEE ALSO MX_NewSaveIFF() matrix.library/MX_NewPrefsWH matrix.library/MX_NewPrefsWH NAME MX_NewPrefsWH -- process window as a preferences program (V23) SYNOPSIS result = MX_NewPrefsWH(tags) d0 a0 ULONG result; struct TagItem *tags; FUNCTION Handles all processing for a standard workbench style preferences program. All standard preferences operations are supported, such as the loading, saving and restoring of data, menu functions and load/save as file requestors. INPUTS tags = pointer to taglist. RESULT result = 0,1,2 (Cancel,Use,Save) TAGS MXPF_AboutMenuHook (void *) - pointer to hook function to handle selection of the about menu item. You do not get an about menu item if this tag is NULL. Default NULL. MXPF_ASLInfo (WORD *) - a pointer to 4 words containing the asl file requestor positional and dimensional information. MXPF_DefaultHook (APTR) - this hook is called when the default settings has been selected from the menu. MXPF_Font (STRPTR) - pointer to fontname to use for gadgets etc... If null then the default system font will be used. MXPF_IFFTags (APTR) - pointer to tag array for MX_NewLoadIFF() and MX_NewSaveIFF(). MXPF_InitialLoad (BOOLEAN) - set this to TRUE to load the initial preferences settings. Default = TRUE. MXPF_LoadSaveDir (UBYTE *) - pointer to default directory for the Open and Save filerequestors to go to. MXPF_LoadTitle (UBYTE *) - this string overides the MXPF_Title for the Open file requestor. MXPF_NewDataHook (APTR) - this hook is called when the preferences data is loaded or reset. MXPF_PreSaveHook (APTR) - pointer to user function called before any file saving operations. NOTE: It is called only once when the user selects SAVE and the ENVARC: and ENV: files are written. This hook is also called when the user selects "Save As..." from the menu. MXPF_PubScreenName (UBYTE *) - pointer to public screen name. If no screen name is provided then the default public screen is used. MXPF_QuitMenuHook (void *) - pointer to hook function invoked when quit is selected from the menu. Default = Cancel the prefs. MXPF_SaveFile (UBYTE *) - filename to save the preferences as. MXPF_SaveTitle (UBYTE *) - this string overides the MXPF_Title for the Save file requestor. MXPF_Screen (struct Screen *) - pointer to screen to open on. If no visual info tag is provided then the visual info will be obtained automatically. MXPF_Title (UBYTE *) - default name to be used in Open and Save file requestors. The title will be inserted as: "Load %s Preferences" and "Save %s Preferences" MXPF_UseFile (UBYTE *) - file name to use the preferences as, this is also the name used to load the initial preferences settings. MXPF_VisualInfo (APTR) - pointer to screen visual info returned by gadtools/GetVisualInfoA(). MXPF_WHTags (struct TagItem *) - pointer to standard matrix windowhandler tag item array. See MX_WindowHandler(). MXPF_Window (struct Window *) - pointer to parent window. You need to specify MXPF_VisualInfo if you are using this tag. Currently this tag has not been implemented. SEE ALSO MX_PrefsWH(), MX_NewLoadIFF(), MX_NewSaveIFF(), MX_WindowHandler(), MX_WindowHandler2(), intuition.library/OpenWindowTagList(), gadtools.library/GetVisualInfoA() matrix.library/MX_NewReadArgs matrix.library/MX_NewReadArgs NAME MX_NewReadArgs -- Parse the arguments (V23) SYNOPSIS MXArgLock = MX_NewReadArgs(template,array,tags) d0 a0 a1 a2 struct *MXArgLock; STRPTR *template; LONG *array; struct TagItem *tags; INPUTS template = see dos.library/ReadArgs() for details. Currently only a subset of the dos template types are supported for tool types, they are: /K, /N, /K/N, and /S array = array of longwords for results, 1 per template entry tags = pointer to a tag list or NULL. RESULT MXArgLock - NULL for failure. Call MX_FreeArgs with this pointer to deallocated any resources used. TAGS MXRA_DosFallback (BOOLEAN) - fallback to processing the dos cli arguments when we are run from cli. This is only valid when the tool types have been set by MXRA_TryLoadIcon and allow the tool types to act as set values and any cli arguments will overide these values. Defaults to TRUE. (V24) MXRA_ToolTypes (APTR) - pointer to tool type array to use instead of using the tooltypes from WBStartup message. (V23) MXRA_TryLoadIcon (BOOLEAN) - if TRUE then the icon for the program will be loaded and used for argument processing if no tool types were provided by any other means. (V23) MXRA_WBMessage (APTR) - pointer to WBStartup message. This is used to set the tool types array if it was not provided by MXRA_ToolTypes. (V23) SEE ALSO MX_ReadArgs(), MX_FreeArgs(), dos.library/ReadArgs() dos.library/FindArg(), dos.library/ReadItem(), dos.library/FreeArgs() matrix.library/MX_NewSaveIFF matrix.library/MX_NewSaveIFF NAME MX_NewSaveIFF -- save an IFF form file (V23) SYNOPSIS success = MX_NewSaveIFF(filename,tags) d0 a0 a1 ULONG success; STRPTR filename; struct TagItem *tags; FUNCTION Writes an iff FORM file given a hunk definition. INPUTS filename = pointer to name of a new file to open. tags = pointer to taglist. RESULT success = TRUE if file save was completed successfully. TAGS MXIF_CreateDir (BOOLEAN) - if the directory for the file does not exist then an attempt will be made to make the directory. If successful then the file open will be reattempted. see MX_NewLoadIFF() for additional tags SEE ALSO MX_NewLoadIFF() matrix.library/MX_NewSortList matrix.library/MX_NewSortList NAME MX_NewSortList() -- sort a list (v23) SYNOPSIS success = MX_NewSortList(list,hook,tags,elements,data) d0 a0 a1 a2 d0 d1 FUNCTION Sort a linked list using a callback hook for node comparisions. INPUTS list = pointer to a list to be sorted hook = comparison hook function called as follows: result/d0 = hook(node1,node2,data)(a0,a1,a6) -1 = node1 > node 2 0 = same 1 = node1 < node 2 If the hook is NULL then a default hook is used which compares the LN_NAME strings and is case sensitive. tags = pointer to taglist, NULL. elements = number of elements in the array, if NULL then the list will be traversed to compute the number of elements. If provided, this *MUST* be at least the number of elements in the list. data = passed to hook function in a6 RESULT FALSE if list was not sorted. TAGS None NOTES The sorting algorithm currently used is QuickSort. SEE ALSO MX_SortList(), MX_QuickSort() matrix.library/MX_NextForm matrix.library/MX_NextForm NAME MX_NextForm -- OBSOLETE FUNCTION SYNOPSIS MX_NextForm(formhandle) a0 matrix.library/MX_OpenForm matrix.library/MX_OpenForm NAME MX_OpenForm -- OBSOLETE FUNCTION SYNOPSIS formhandle = MX_OpenForm(name,type,mode,tags) d0 a0 a1 d0 d1 matrix.library/MX_OpenFormReq matrix.library/MX_OpenFormReq NAME MX_OpenFormReq -- OBSOLETE FUNCTION SYNOPSIS formhandle = MX_OpenFormReq(hail,path,file,type,mode,tags) d0 a0 a1 a2 a3 d0 d1 matrix.library/MX_OpenPathNew matrix.library/MX_OpenPathNew NAME MX_OpenPathNew -- open a file as NEW (V23) SYNOPSIS fh = MX_OpenPathNew(name) d0 a0 struct filehanle *fh; STRPTR name; FUNCTION Opens a file creating the path if necessary. INPUTS name = pointer to filename, if the path cannot be locked then an attempt is made to create that path. If it is not possible to make the path then this function returns FALSE as the file cannot be opened as NEW. If the path exists then This function is similar to fh = Open(filename,MODE_NEWFILE); RESULT Returns FALSE if unable to open file or create path to file. SEE ALSO dos.library/Open(), dos.library/Close() matrix.library/MX_PatternMatch matrix.library/MX_PatternMatch NAME MX_PatternMatch -- perform dos patternmatching on a string. (V23) SYNTAX result = MX_PatternMatch(string,pattern) d0 a0 a1 LONG result; STRPTR string; STRPTR pattern; FUNCTION Matches the string against the specified pattern. INPUTS string = pointer to string. pattern = pointer to pattern for pattern matching. RESULT result = success or failure of pattern match. Returns ~0 if run out of memory/stack. NOTES The pattern matching is not case sensitive. SEE ALSO dos.library/ParsePatternNoCase(), dos.library/MatchPatternNoCase() matrix.library/MX_ProcessArexxPort matrix.library/MX_ProcessArexxPort NAME MX_ProcessArexxPort -- process arexx messages (V23) SYNTAX MX_ProcessArexxPort(port,vectors,[userdata])(a0,a1,[d0]) struct MsgPort *port; APTR *vectors; ULONG userdata; FUNCTION Process any messages arriving at an arexx port through Hook functions. INPUTS port = pointer to an arexx message port. You can easily create an arexx message port by calling MX_AddArexxPort(). vectors = pointer to an array of pointers to command strings and hook functions, terminated by a command string pointer of null. The hook function is called as follows: result = Hook(msg,args,userdata) d0 a0 a1 d0 userdata = optional parameter, this is passed to the hook function. RESULT None. SEE ALSO MX_AddArexxPort(), MX_RemArexxPort() matrix.library/MX_QuickSort matrix.library/MX_QuickSort NAME MX_QuickSort() -- sort an array (v23) SYNOPSIS MX_QuickSort(array,hook,elements,data) a0 a1 d0 d1 FUNCTION Sort an array using callback hook. INPUTS array = pointer to an array of longwords, when this is called by MX_NewSortList() this is an array of pointers to nodes. hook = comparison hook function called as follows: result/d0 = hook(e1,e2,data)(a0,a1,a6) -1 = e1 > e2 0 = same 1 = e1 < e2 elements = number of elements in the array, if NULL then the list will be traversed to compute the number of elements. If provided, this *MUST* be at least the number of elements in the list. data = passed to user hook function in a6 RESULT None. SEE ALSO MX_NewSortList(), MX_ListToArray() matrix.library/MX_Random matrix.library/MX_Random NAME MX_Random -- generate a random number (V22) SYNOPSIS number = MX_Random(range) d0 d0 LONG number; LONG range; INPUTS range = the largest number to generate. The generated number will fall in the range from 0 to "range" RESULT number = the random number generated. SEE ALSO MX_RandomSeed(), MX_RandomInRange() matrix.library/MX_RandomInRange matrix.library/MX_RandomInRange NAME MX_RandomInRange -- generate a random number (V23) SYNOPSIS number = MX_RandomInRange(min,max) d0 d0 d1 LONG number; LONG min; LONG max; INPUTS min = the minimum value to generate max = the maximum value to generate RESULT number = a randomly generated number greater or equal to min and less or equal to max: min =< number =< max SEE ALSO MX_RandomSeed(), MX_Random() matrix.library/MX_RandomSeed matrix.library/MX_RandomSeed NAME MX_RandomSeed -- seed the random number tables. (V22) NOTES This function is private for use by matrix.library only. SEE ALSO MX_Random(), MX_RandomInRange() matrix.library/MX_RawFormat matrix.library/MX_RawFormat NAME MX_RawFormat -- format data into a character stream. (V21) SYNOPSIS NextData = MX_RawFormat(FormatString,DataStream,Destination) d0 a0 a1 a2 APTR NextData; STRPTR FormatString; APTR DataStream; APTR Destination; FUNCTION This function is identical to the exec.library/RawDoFmt() function except it does not require the PuchChProc. INPUTS FormatString - a "C"-language-like NULL terminated format string. DataStream - a stream of data that is interpreted according to the format string. Often this is a pointer into the task's stack. Destination - pointer to a buffer to fill with the formatted string. RESULT NextData = pointer to end of the data stream, this allows multiple formatting passes to be made using the same data. SEE ALSO exec.library/RawDoFmt(). matrix.library/MX_ReadArgs matrix.library/MX_ReadArgs NAME MX_ReadArgs -- Parse the command line / wbmsg input (V23) SYNOPSIS MXArgLock = MX_ReadArgs(template,array,[wbmsg]) d0 a0 a1 [a2] struct *MXArgLock; STRPTR *template; LONG *array; struct *WBMessage wbmsg; INPUTS template - see dos.library/ReadArgs() for details on definition of the template. Currently supported supported tool types are "/K, /N, /K/N, and /S". array - array of longwords for results, 1 per template entry wbmsg - pointer to message from workbench, this only needs to be provided if you were not started from CLI. RESULT MXArgLock - NULL for failure. Call MX_FreeArgs with this pointer to deallocated any resources used. NOTES This function is obsolete, use MX_NewReadArgs() instead. SEE ALSO MX_NewReadArgs(), MX_FreeArgs(), dos.library/ReadArgs() dos.library/FindArg(), dos.library/ReadItem(), dos.library/FreeArgs() matrix.library/MX_ReadForm matrix.library/MX_ReadForm NAME MX_ReadForm -- OBSOLETE FUNCTION SYNOPSIS MX_ReadForm(formhandle,buffer,size) a0 a1 d0 matrix.library/MX_ReadFormTagList matrix.library/MX_ReadFormTagList NAME MX_ReadFormTagList -- OBSOLETE FUNCTION SYNOPSIS MX_ReadFormTagList(formhandle,buffer,size,tags) a0 a1 d0 d1 matrix.library/MX_RemArexxPort matrix.library/MX_RemArexxPort NAME MX_RemArexxPort -- remove a public arexx message port. (V23) SYNOPSIS MX_RemArexxPort(port,hook,[userdata]) a0 a1 [d0] struct MsgPort *port; APTR hook; FUNCTION Remove an arexx port from the system safely, replying any waiting messages using ReplyMsg() or userhook(). INPUTS port - pointer to port added using MX_AddArexxPort(). May be NULL. hook - pointer to user function that is called to reply any messages waiting at this port. If NULL then the message will be replied using ReplyMsg(). The userhook is invoked as follows: userhook(msg,userdata) a1 d0 RESULT None. SEE ALSO MX_AddArexxPort(), MX_ProcessArexxPort(), exec.library/RemPort(), exec.library/DeleteMsgPort(), exec.library/ReplyMsg(). matrix.library/MX_RemVBlankNode matrix.library/MX_RemVBlankNode NAME MX_RemVBlankNode -- remove vblank node hook or signal (V23) SYNOPSIS MX_RemVBlankNode(vbn) a0 struct MXVBlankNode *vbn; FUNCTION Remove an added MXVBlank node. INPUTS vbn = pointer to MXVBlankNode to remove or NULL. RESULT None. SEE ALSO MX_AddVBlankNode(), MX_UpdateVBLankInterrupt() matrix.library/MX_RemakeGadgets matrix.library/MX_RemakeGadgets NAME MX_RemakeGadgets -- update the gadgets (V22) SYNOPSIS MX_RemakeGadgets(gadgets,window) d0 a0 struct Gadget *gadgets; strcut Window *window; FUNCTION Remakes the gadgets when the data changes. INPUTS gadgets = pointer to gadgets created by MX_CreateGadgets(). If NULL then the gadget pointer from the window will be used. window = pointer to window gadgets are in. RESULT None. SEE ALSO MX_CreateGadgets(), MX_CleanUpGList() matrix.library/MX_ReplaceTags matrix.library/MX_ReplaceTags NAME MX_ReplaceTags -- change the tag values in a tag array (V24) SYNOPSIS MX_ReplaceTags(tagArray,replaceArray,flags) a0 a1 d0 struct TagItem *tagArray; APTR replaceArray; ULONG flags; FUNCTION Changes the tag value id's in a tag array to those specified by the replacement array. INPUTS tagArray - pointer to a valid tag item array. replaceArray - an array of ULONG tag id pairs, the first is the source tag to search for and the second is its replacement tag id. flags - NULL. None defined. RESULT None. NOTES Tags not found in the replacement array are marked TAG_IGNORE. SEE ALSO matrix.library/MX_ReplaceVecStr matrix.library/MX_ReplaceVecStr NAME MX_ReplaceVecStr -- alloc/update a string and buffer (V23) SYNOPSIS mem = MX_ReplaceVecStr(string,handle,attributes) d0 a0 a1 d1 APTR mem; STRPTR string; APTR *handle; ULONG attributes; FUNCTION Allocates a buffer for the string and copys the string into the buffer. Frees the old buffer pointed to by the handle, and updates the handle to point to the new buffer. INPUTS string = pointer to a string. handle = pointer to storage space for string pointer. attributes = exec.library/AllocVec() memory attributes. RESULT Pointer to buffer containing the string, or NULL if not enough memory for the buffer. NOTE Use exec.library/FreeVec() to deallocate the buffer. SEE ALSO MX_AllocVecStr(), exec.library/AllocVec(), exec.library/FreeVec() matrix.library/MX_SaveIFF matrix.library/MX_SaveIFF NAME MX_SaveIFF() -- OBSOLETE SYNOPSIS result = MX_SaveIFF(iffhandle,filename,tags) d0 a0 a1 a2 matrix.library/MX_SeekForm matrix.library/MX_SeekForm NAME MX_SeekForm -- OBSOLETE FUNCTION SYNOPSIS MX_SeekForm(formhandle,pos,mode) a0 d0 d1 matrix.library/MX_SelectGadget matrix.library/MX_SelectGadget NAME MX_SelectGadget -- show a gadget being selected SYNOPSIS MX_SelectGadget(window,gadget) a0 a1 struct Window *window; struct Gadget *gadget; FUNCTION INPUTS window = pointer to window containing gadget gadget = pointer to the gadget to show being selected RESULT None BUGS SEE ALSO matrix.library/MX_SendArexxString matrix.library/MX_SendArexxString NAME MX_SendArexxString -- send a command to an arexx port (V20) SYNOPSIS res1,res2,port = MX_SendArexxString(string,portname,replyport) d0 d1 a0 a0 a1 a2 ULONG res1; ULONG res2; STRPTR string; STRPTR pointname; struct MsgPort *replyport; FUNCTION Sends an arexx message to an arexx port and waits for the reply. INPUTS string - pointer to null terminated string to send to specified arexx message port. portname - name of arexx message port to send message to. replyport - NULL. [Not Supported] RESULT res1,res2 = return values from arexx message or -1 if failed. SEE ALSO exec.library/FindPort(), exec.library/PutMsg() rexxsyslib.library/CreateRexxMsg(), rexxsyslib.library/CreateArgstring rexxsyslib.library/FillRexxMsg, rexxsyslib.library/ClearRexxMsg rexxsyslib.library/DeleteRexxMsg matrix.library/MX_SetListView matrix.library/MX_SetListView NAME MX_SetListView -- change/disable list and enable/disable gadget (V23). SYNOPSIS MX_SetListView(gad,win,list,entry) a0 a1 d0 d1 struct Gadget *gad; struct Window *win; struct List *list; WORD entry; FUNCTION Changes the list being used by the listview gadget and enables or disables the list if there are entries in it or not. INPUTS gad = pointer to the listview gadget or NULL for no action. win = pointer to the window or NULL for no action. list = pointer to a list or ~0 to disable the current list. If NULL then the listview will be disabled. entry = entry number in the list to set active. RESULT None. SEE ALSO gadtools.library/GT_SetGadgetAttrsA() matrix.library/MX_SetWaitPointer matrix.library/MX_SetWaitPointer NAME MX_SetWaitPointer -- make the pointer a busy pointer SYNOPSIS MX_SetWaitPointer(?) FUNCTION INPUTS ? RESULT None NOTE BUGS SEE ALSO matrix.library/MX_ShowWindow matrix.library/MX_ShowWindow NAME MX_ShowWindow -- show window active by a task (V23) SYNOPSIS MX_ShowWindow(window,[task]) a0 a1 struct Window *window; struct Task *task; FUNCTION Will make a window visible to the user by all means possible. If no window pointer is given then the task pointer is used and the pr_WindowPtr() field is extracted and used as the window pointer. INPUTS window = pointer to the window to show or NULL. task = pointer to task to use pr_WindowPtr(). You only need to specify this field if window is NULL. This may also be NULL, in which case nothing will happen. RESULT The window (if any) will be brought to the fron of the screen it is on, unzipped (if zipped) and the screen will come to the front of the display. SEE ALSO intuition.libraryActivateWindow(), intuition.libraryWindowToFront() intuition.libraryZipWindow(), intuition.libraryScreenToFront() matrix.library/MX_SortList matrix.library/MX_SortList NAME MX_SortList -- sort a linked list. (V22) SYNOPSIS MX_SortList(list) a0 APTR list; FUNCTION Sorts a linked list into prioritized alphbetic order. INPUTS list = pointer to linked list to sort. RESULT None. NOTES Make sure the LN_PRI field of each node is set, if you do not want a prioritized sort then set this to zero for all nodes. This function call MX_NewSortList(). SEE ALSO MX_NewSortList(),MX_AddNodeSorted(), MX_TextFileToList(), MX_FreeListNodes(), MX_FreeList() matrix.library/MX_SoundID matrix.library/MX_SoundID NAME MX_SoundID -- play a sound ID through MSD. (V23) SYNOPSIS result = MX_SoundID(basename,name) d0 a0 a1 STRPTR basename; STRPTR name; FUNCTION Plays a sound ID through matrix sound daemon (MSD). INPUTS basename - pointer to string to be used as a base path for the sample id. This may be NULL but it is suggested that a basename be used to identify the program requesting the sample. Eg. "myprogram" name - this is the specific sample ID to be played. If this is not provided then the name used is "Beep". RESULT Returns FALSE if unable to locate the MSD message port. NOTES The soundID name is built up from the basename and the name similar to DOS paths. Examples: "myprogram","TheSound" --> "myprogram/TheSound" "myprogram/general","Warning" --> "myprogram/general/Warning" SEE ALSO matrix.library/MX_StrCpyLen matrix.library/MX_StrCpyLen NAME MX_StrCpyLen -- copy string up to specified max length (V22) SYNOPSIS MX_StrCpyLen(source,dest,size) a0 a1 d0 STRPTR source; STRPTR dest; LONG size; FUNCTION Copy a string into a buffer of specified length. INPUTS source = pointer to a null terminated string. dest = pointer to a buffer to copy string into. size = maximum number of characters to copy. RESULT None. NOTES The destination buffer MUST be of size+1 bytes long, this is because the string is padded with a NULL byte. SEE ALSO MX_StrLen() matrix.library/MX_StrCpyWord matrix.library/MX_StrCpyWord NAME MX_StrCpyWord -- copy the next word from source string (V23) SYNOPSIS next = MX_StrCpyWord(source,dest) d0 a0 a1 STRPTR next; STRPTR source; STRPTR dest; FUNCTION Copy a the next word from the source buffer into the destination buffer. If there are no more words or the source pointer is NULL then NULL will be returned. INPUTS source = pointer to a null terminated string or NULL. dest = pointer to a buffer to copy string into. RESULT next = pointer to the start of the next word in the source buffer, or NULL if the end of string marker was reached. NOTES The destination buffer MUST be large enough to copy the word into. matrix.library/MX_StrLen matrix.library/MX_StrLen NAME MX_StrLen -- get the length of a string (V22) SYNOPSIS length MX_StrLen(string) d0 a0 LONG length; STRPTR string; FUNCTION Compute the length of a null terminated string. INPUTS string = pointer to a null terminated string. RESULT length = the number of characters in the string, excluding the null terminating byte. NOTES Register a0 (string pointer) is returned unchanged, other scratch registers are modified (a1,d1). SEE ALSO MX_StrCpyLen matrix.library/MX_TaskName matrix.library/MX_TaskName NAME MX_TaskName -- get the "real" name of our task. SYNOPSIS success = MX_TaskName(buffer,task,tags,size) d0 a0 a1 a2 d0 LONG success; STRPTR buffer; struct Task *task; struct TagItem *tags; LONG size; FUNCTION Fills a buffer with the name or full pathname of the specified task. INPUTS buffer = pointer to buffer to store the name/pathname. task = pointer to task or NULL. If NULL is used then the current task will be used unless overidden by the tag MXTN_TaskPtr or MXTN_TaskName. tags = pointer to a tag list or NULL. size = length of buffer in bytes. May not be ZERO. RESULT success = TRUE if successful, FALSE otherwise. TAGS MXTN_TaskPtr (struct Task *) - pointer to task, overides task parameter. MXTN_TaskName (UBYTE *) - pointer to name of task. Only really of use if used with MXTN_FullPath. Overides task parameter. MXTN_FullPath (BOOLEAN) - if TRUE then the full path name of the specified task will be given. If FALSE then only the name of the task will be given. Defaults to TRUE. SEE ALSO exec.library/FindTask() matrix.library/MX_TextFileToList matrix.library/MX_TextFileToList NAME MX_TextFileToList -- create a linked list from a text file. (V22) SYNOPSIS result = MX_TextFileToList(head,filename,tags) d0 a0 a1 a2 LONG result; APTR head; STRPTR filename; struct TagItem *tags; FUNCTION Creates a linked list from a text file. INPUTS head = pointer to a listhead that is initialized. If there are any entries in the list they are freed using MX_FreeListNodes(). filename = pointer to a filename to read. tags = pointer to a tag list. Please keep this NULL. RESULT result = count of number of lines added to the listview, or -1 on failure. TAGS MXTFL_AllocateFullLine (BOOLEAN) = should the allocated buffer be allocated to MXTFL_LineLength. This may not be used with a MXTFL_LineLength of -1. Default is FALSE. (V24) MXTFL_AllocateLNNAME (BOOLEAN) = if set to TRUE then the ln_Name field is allocated to the length of the line. When you free the list you *MUST* also free the ln_Name field using FreeVec(). MXTFL_AllocateStrings (BOOLEAN) = if set to FALSE then LN_NAME string pointers are not allocated and point to the source buffer. The source buffer will be modified after, having linefeeds converted to NULL bytes. You may not use the following tags in conjunction with this tag: MXTFL_FileHandle, MXTFL_LeadingSpaces, MXTFL_LineLength, MXTFL_SplitLines, MXTFL_AllocateFullLine. You must specify the buffer using MXTFL_SourceBuffer, but please note that this buffer may not be reused in this routine as the end of buffer NULL character will be encountered on the first line. Default = TRUE. (V24) MXTFL_FileHandle (APTR) = filehandle of file to read, this will be used instead of the filename passed in. NOTE: This filehandle will be closed when finished. (V23) MXTFL_LeadingSpaces (ULONG) = number of leading spaces. NOTE: This reduces the MXTFL_LineLength value so make sure it is less tha this. Default = 0. (V23) MXTFL_LineLength (ULONG) = maximum length for a line of text. The default length is 80 characters. Must be greater than 0. (V23) If -1 then the full line will be used. MXTFL_MemAttr (ULONG) = attributes for the memory allocations. Default = 0. (V24) MXTFL_NodeSize (ULONG) = size of list node entry, this defaults to LN_SIZEOF. Must be greater or equal to LN_SIZEOF. (V23) Note: The LN_TYPE and LN_PRI fields are initialized to zero always. MXTFL_SourceBuffer (APTR) = pointer to a text buffer. This will be used instead of the filename passed in. The buffer *MUST* be null terminated. (V23) MXTFL_SplitLines (BOOLEAN) = set to TRUE if you want lines longer than the buffer to be spread over several lines. Deafult = FALSE. Not implemented. (V23) NOTES The list entries allocated by this function may be deallocated by a call to MX_FreeListNodes(). SEE ALSO MX_FreeListNodes(), MX_FreeList() matrix.library/MX_TimeString matrix.library/MX_TimeString NAME MX_TimeString -- OBSOLETE SYNTAX MX_TimeString(buffer,seconds,type) a0 d0 d1 NOTES dos.library and locale.library provide satisfactory system routines for this. matrix.library/MX_UnlockMxBase matrix.library/MX_UnlockMxBase NAME MX_UnlockMxBase -- Surrender lock on MxBase by MX_LockMxBase(). (V23) SYNOPSIS MX_UnlockMxBase() NOTE This call is guaranteed to preserve all registers. SEE ALSO MX_LockMxBase() matrix.library/MX_UnlockWindow matrix.library/MX_UnlockWindow NAME MX_UnlockWindow -- enable a window. (V21) SYNOPSIS MX_UnlockWindow(window,lock) a0 a1 struct Window *window; APTR lock; FUNCTION Enable the gadgets and restore mouse pointer. INPUTS window - pointer to window to be unlocked. lock - the lock returned by MX_LockWindow() or NULL. RESULT None. SEE ALSO MX_LockWindow() matrix.library/MX_UpdateVBLankInterrupt matrix.library/MX_UpdateVBLankInterrupt NAME MX_UpdateVBLankInterrupt -- install remove the vblank interrupt (V23) SYNOPSIS state = MX_UpdateVBLankInterrupt() ULONG state; FUNCTION If the VBLANK list is empty and the interrupt is installed then the interrupt will be removed. If the list is not empty and the interrupt is not installed then it will be. This function is for private use by matrix.library. RESULT state = (0) if interrupt is not running, or (1) if the interrupt is running. NOTES This function is private for use by matrix.library only. SEE ALSO MX_AddVBlankNode(), MX_RemVBlankNode() matrix.library/MX_WhereAmI matrix.library/MX_WhereAmI NAME MX_WhereAmI -- OBSOLETE FUNCTION SYNOPSIS formhandle = MX_OpenFormReq(hail,path,file,type,mode,tags) d0 a0 a1 a2 a3 d0 d1 matrix.library/MX_WindowHandler matrix.library/MX_WindowHandler NAME MX_WindowHandler -- do some windowy stuff SYNOPSIS result = MX_WindowHandler(window,[screen],tags,vi) d0 a0 [a1] d0 d1 ULONG result; struct Window *window; struct Screen *screen; struct TagItem *tags; struct VisInfo *vi; FUNCTION Does lots of windowy stuff INPUTS window = screen = tags = vi = RESULT Returns FALSE if error occurs otherwise it is the value wh_ReturnVal set in the wh structure. TAGS MXWH_ASLInfo (APTR) = Pointer to matrix asl info structure, this consists of positional information for asl requestors associated with this window. MXWH_Catalog (APTR) = pointere to open catalog as returned by locale.library/OpenCatalogA() (V24) MXWH_CatalogName (STRPTR) = name of catalog file to load. (V24) MXWH_CatCompArray (APTR) = pointer to array of ID,STRPTRS. When specifying the labels for gadgets, you provide the string id for lookup using locale.library. (V24) MXWH_CloseWindow (ULONG) = wh_ReturnVal when the close gadget is selected. Default = ~0 = no close gadget. MXWH_ESCAddress (APTR) = Pointer to user function that is called when the ESC key is pressed. If Set to ~0 the active byte in the wh structure is cleared MXWH_ESCvalue tag data value is set in wh_ReturnVal. The user function is called as follows: void Function(wh) a0 MXWH_ESCvalue (ULONG) = wh_ReturnVal when the ESC key is pressed. Default = 0. MXWH_ESCAddress must also be set. MXWH_Events (APTR) = Pointer to array of longword pairs, terminated by a NULL longword. This array consists of IDCMP Code and Function pairs. used = Function(wh,intuiMsg) d0 a0 a1 The function should return TRUE if it used the message and does not want matrix.library to process it. You may also need to set the tag MXWH_IDCMPFlags. (V23.1032) It is no longer necessary to specify the tag MXWH_IDCMPFlags as matrix calculates what the mask is from the events you are requesting. MXWH_Gadgets (APTR) = Pointer to matrix gadget data to be passed to MX_CreateGadgets(). MXWH_Handler (APTR) = MXWH_IDCMPFlags (ULONG) = Mask of IDCMP flags to be recieved. Use this in conjunction with MXWH_Events. MXWH_InitCode (APTR) = Pointer to function called after the window has been opened. You should you this to set up any graphics you wish to render into the window. void Function(wh) a0 MXWH_Locale (APTR) = pointer to open locale as returned by locale.library/OpenLocale() (V24) MXWH_LocaleName (STRPTR) = pointer to locale name or NULL for the default locale. (V24) MXWH_Menus (APTR) = Pointer to menu array to be passed to CreateMenusA() and LayoutMenusA(). If not specified then the window will not have any menus and RMBTRAP will be set in the window flags. This array is localized. MXWH_MenusLocalize (BOOLEAN) = set to FALSE if you do not want the menustrip to be localized. Default = TRUE. MXWH_NoDepth (BOOLEAN) = Set to TRUE and the depth gadget will not be added to the window. Default = FALSE. MXWH_NoDrag (BOOLEAN) = Set to TRUE to disable the dragbar of the window. Default = FALSE. MXWH_Position (APTR) = Pointer to two WORDs that contain the windows desired position. These will be updated when the window is closed. Set either X or Y position to -1 and the window will be centered. MXWH_PositionInWindow (BOOLEAN) = if set to true then the when the window is opened, instead of centering it will open with its top left corner just inside the parent windows top left borders. It is necessary to specify a parent window. The MXWH_Position tag will overide this tag unless it is set to -1. (V23) Not this tag has been renamed MXWH_PositionWindow and is no longer a boolean MXWH_PositionWindow (ULONG) = method for positioning the window. See also MXWH_PositionInWindow MXWH_RemakeWindowHook (APTR) = Hook function to call when the window graphics need to be redrawn. (V23) void Function(wh,intuiMsg) a0 a1 MXWH_ScreenTitle (STRPTR) = pointer to the screen title to be displayed when the window is active. (V23) MXWH_Signals (ULONG) = Mask of signals to be processed by the MXWH_SignalHandler tag function. MXWH_SignalHandler (APTR) = Pointer to function to process the signals specified in the MXWH_Signals tags mask. void Function(wh,sigmaskRecievd) a0 d0 MXWH_UseParentPort (BOOLEAN) = Set to TRUE if you wish this window to share the parent window's message port. It is important for this to be TRUE if the parent window has additional graphics rendered into the window, such as the boxes/borders drawn by matrix.library. Also any custom rendering will have to be taken care of with a user callback through MXWH_RemakeWindowHook Default = TRUE. (V23) MXWH_UserData (ULONG) = User data set in the window handler structure which is passed to callback functions. The userdata field is wh_UserData. MXWH_VisualInfo (APTR) = MXWH_WindowPointer (APTR) = Pointer to a longword which is to cantain a pointer to the window. This is set to its original value when the window is closed. MXWH_WindowSize (ULONG) = This specifies the width AND the height of the window in characters, with the width given as a word in bits 16-31 and the height in bits 0-15. (V23) Default = NONE. This MUST be specified. MXWH_WindowTitle (STRPTR) = Pointer to the title to be used for the window. MXWH_WindowTitleMSGID (ULONG) = this is the stringNum that is passed to MX_GetCatalogStr() (V24) (many more) SEE ALSO MX_WindowHandler2(), MX_CreateGadgets(), MX_GetCatalogStr() matrix.library/MX_WrapText matrix.library/MX_WrapText NAME MX_WrapText -- remove the last word of a line SYNOPSIS MX_WrapText(source,dest) a0 a1 APTR source; APTR dest; FUNCTION INPUTS source = dest = RESULT None NOTE BUGS SEE ALSO MX_JustifyText() matrix.library/MX_WriteForm matrix.library/MX_WriteForm NAME MX_WriteForm -- OBSOLETE FUNCTION SYNOPSIS MX_WriteForm(formhandle,buffer,size,type) a0 a1 d0 d1 matrix.library/MX_WriteFormTagList matrix.library/MX_WriteFormTagList NAME MX_WriteFormTagList -- OBSOLETE FUNCTION SYNOPSIS MX_WriteFormTagList(formhandle,buffer,size,tags,type) a0 a1 d0 d1 d2