Club Amiga de Montreal

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

/ Club Amiga de Montreal - CAM / CAM_CD_1.iso / files / 390.lha / mxm.library / mxm.doc.pp / mxm.doc

Wrap

Text File | 1990-07-01 | 32.1 KB | 2,579 lines

mxm.library/PURPOSE mxm.library/PURPOSE BACKGROUND mxm.library was created to support our in-house development environment. It contains basic support functions as well as routines frequently used but never to be found in any library. It seems strange that most functions to be found in mxm.library will be included in Kickstart 1.4. The contents of the library were put together from various sources. You will find code derived from 'ancient' Developers' kit sources, sample routines suggested on older public-domain disks as well as new routines written by us. Many different areas of programming are covered by mxm.library routines. Some routines check gadgets while other deal with data encryption or produce sounds. All in all we have tried to keep the library as small as possible and - most important - reentrant. CREDITS The ikm.c source code was developed by Jimm Mackraz of Commodore-Amiga, Inc., Los Gatos. AllocRem/FreeRem were created from old EA IFF sources. PopMenu was extended from example source code by Gambit Software. The Crc-16-bit checksumming routines were created by Stephen Satchell and Chuck Forsberg. CONTRIBUTIONS If you are interested in adding new functions to mxm.library mail them to us on disk. They will be included in the next library release. ADDRESS Olaf Barthel, MXM Brabeckstrasse 35 D-3000 Hannover 71 Federal Republic of Germany mxm.library/AllocRem mxm.library/AllocRem NAME AllocRem - Allocate a chunk of memory SYNOPSIS MemoryBlock = AllocRem(Size Requirements) FUNCTION Very similar to AllocMem, AllocRem allocates a chunk of memory, according to size and type passed in arguments. The only difference is that the size of the memory block being allocated is remembered. INPUTS Size - The number of bytes to allocate. Requirements - Flags such as MEMF_CHIP, MEMF_FAST, MEMF_PUBLIC, MEMF_CLEAR. RESULTS MemoryBlock - A pointer to the allocated chunk of memory or NULL. BUGS SEE ALSO exec.library/AllocMem exec.library/FreeMem mxm.library/AllocRem mxm.library/FreeRem mxm.library/FreeRem NAME FreeRem - Free a chunk of memory SYNOPSIS Pointer = FreeRem(MemoryBlock) FUNCTION FreeRem deallocates a block of memory previously allocated by AllocRem. The size of the block does not need to specified since it is stored in the first longword of the MemoryBlock. This function is quite safe since NULL pointers are skipped. INPUTS MemoryBlock - Pointer to the chunk of memory to be allocated. RESULTS Pointer - This function always returns NULL, so user can do Pointer = FreeRem(Pointer). BUGS FreeRem cannot be used to deallocate memory allocated via AllocMem. SEE ALSO exec.library/AllocMem exec.library/FreeMem mxm.library/FreeRem mxm.library/CreateFuncTask mxm.library/CreateFuncTask NAME CreateFuncTask - Create a task SYNOPSIS Task = CreateFuncTask(TaskName Priority InitialPC StackSize) FUNCTION CreateFuncTask creates a task from a given function and adds it to the system list. The name of the task to be created does not need to be statically initialized. It is copied into a separate chunk of memory and gets freed by DeleteFuncTask(). INPUTS TaskName - Pointer to null-terminated string. Priority - The priority the task will be started from. InitialPC - Pointer to function to be started as a task. StackSize - The stack size you wish to execute the task with. RESULTS Task - Pointer to a Task-structure, or NULL. BUGS SEE ALSO exec.library/AddTask mxm.library/DeleteFuncTask mxm.library/DeleteFuncTask NAME DeleteFuncTask - Delete a task SYNOPSIS Pointer = DeleteFuncTask(Task) FUNCTION DeleteFuncTask removes a Task from the system list previously created with CreateFuncTask. INPUTS Task - Pointer to a Task-structure. RESULTS This function always returns NULL, so user can do Pointer = DeleteFuncTask(Pointer). BUGS This function does not handle self-deletion properly. SEE ALSO mxm.library/CreateFuncTask mxm.library/CreateFuncProc mxm.library/CreateFuncProc NAME CreateFuncProc - Create a process SYNOPSIS Proc = CreateFuncProc(ProcName Priority InitialPC StackSize) FUNCTION CreateFuncProc creates a process from a given function and adds it to the system list. INPUTS ProcName - Pointer to null-terminated string. Priority - The priority the process will be started from. InitialPC - Pointer to function to be started as a process. StackSize - The stack size you wish to execute the process with. RESULTS Proc - Pointer to a Process-structure, or NULL. BUGS Currently this function can only be called from processes, since DOS-routines are employed to install the new process. SEE ALSO exec.library/AddTask mxm.library/CreateFuncTask mxm.library/MovePointer mxm.library/MovePointer NAME MovePointer - Move the mouse pointer to given position SYNOPSIS Success = MovePointer(Screen Button X Y) FUNCTION MovePointer positions the mouse pointer at the given x/y position relative to the top/leftedge of a screen. Optionally a mouse-click can be simulated. INPUTS Screen - Pointer to a Screen-structure. Button - Boolean, TRUE if you want a mouse-click to be simulated, FALSE if not. X - New X-position for the mouse pointer. Y - New Y-position for the mouse pointer. RESULTS Success - Boolean. BUGS SEE ALSO mxm.library/WriteConsole mxm.library/WriteConsole NAME WriteConsole - Write a string to a window. SYNOPSIS Success = WriteConsole(Window String) FUNCTION This function behaves very much like a call to the ANSI-function puts(). A string, which may include ANSI control codes, is printed into a window. INPUTS Window - Pointer to a Window-structure. String - Pointer to a null-terminated string. RESULTS Success - Boolean. BUGS SEE ALSO ANSI puts() command mxm.library/DeletePrinterSupport mxm.library/DeletePrinterSupport NAME DeletePrinterSupport - Deallocate a PrinterSupport request. SYNOPSIS Pointer = DeletePrinterSupport(Support) FUNCTION All necessary cleanups for the PrinterSupport functions are provided with this function (allocated memory is freed, device actions stopped and device driver is closed). INPUTS Support - Pointer to a PrinterSupport-structure. RESULTS This function always returns NULL, so user can do Pointer = DeletePrinterSupport(Pointer). BUGS SEE ALSO mxm.library/CreatePrinterSupport mxm.library/StartPrinterDump mxm.library/StopPrinterDump mxm.library/CreatePrinterSupport mxm.library/CreatePrinterSupport NAME CreatePrinterSupport - Allocate a PrinterSupport-structure and prepare the unit driver for printing. SYNOPSIS Support = CreatePrinterSupport(RastPort ViewPort LeftEdge TopEdge Width Height Large) FUNCTION This function creates a Dump-Rastport request for the printer.device and passes it back to the caller who has to start the dump by a call to StartPrinterDump(). INPUTS RastPort - Pointer to a RastPort-structure, area to be printed. ViewPort - Pointer to a ViewPort-structure. LeftEdge/TopEdge - Corner of area to start printing from. Width/Height - Size of area to be printed. Large - Set this to TRUE if you wish to have the area printed as large as possible. RESULTS Support = Pointer to a PrinterSupport-structure, or NULL. BUGS SEE ALSO printer.device/PRDDUMPRPORT mxm.library/StartPrinterDump mxm.library/StartPrinterDump NAME StartPrinterDump - Send a graphics dump to the printer. SYNOPSIS StartPrinterDump(Support WaitUntilDone) FUNCTION A printer graphics dump following a call to CreatePrinterSupport is executed. INPUTS Support - Pointer to a PrinterSupport-structure. WaitUntilDone - TRUE if you want the request to be satisfied before this function returns. RESULTS BUGS SEE ALSO mxm.library/CreatePrinterSupport printer.device/PRDDUMPRPORT mxm.library/StopPrinterDump mxm.library/StopPrinterDump NAME StopPrinterDump - Stop a graphics dump being in progress. SYNOPSIS Success = StopPrinterDump(Support WaitUntilDone) FUNCTION A printer graphics dump started with StartPrinterDump() can be stopped with this function. INPUTS Support - Pointer to a PrinterSupport-structure. WaitUntilDone - TRUE if you want this function to return after the AbortIO function has been satisfied. RESULTS Success - Boolean, FALSE if printer graphics dump was not to be aborted. BUGS SEE ALSO mxm.library/CreatePrinterSupport mxm.library/StartPrinterSupport, printer.device/PRDDUMPRPORT mxm.library/DeleteTimer mxm.library/DeleteTimer NAME DeleteTimer - Delete a timer-request. SYNOPSIS DeleteTimer(TimeRequest) FUNCTION This function deallocates a timer.device request previously allocated via CreateTimer. INPUTS TimeRequest - Pointer to a timerequest structure. RESULTS BUGS SEE ALSO mxm.library/CreateTimer mxm.library/CreateTimer NAME CreateTimer - Create a timer-request SYNOPSIS TimeRequest = CreateTimer(Unit) FUNCTION A timer-request is created with this function, depending on the requested device driver unit. INPUTS Unit - The unit to be opened, can be either UNITVBLANK or UNITMICROHZ. RESULTS TimeRequest - Pointer to a timerequest-structure, or NULL. BUGS SEE ALSO mxm.library/WaitForTimer mxm.library/WaitForTimer NAME WaitForTimer - Wait a given period of time. SYNOPSIS WaitForTimer(TimeRequest TimeVal) FUNCTION This function gets the timer.device to wait a period of time. INPUTS TimeRequest - Pointer to a timerequest-structure. TimeVal - Pointer to a timeval-structure. RESULTS BUGS SEE ALSO mxm.library/TimeDelay mxm.library/TimeDelay NAME TimeDelay - Wait a given period of time. SYNOPSIS TimeDelay(Seconds Micros Unit) FUNCTION This function gets the timer.device to wait a period of time. INPUTS Seconds - Seconds to wait. Micros - Microseconds to wait. Unit - The unit to be opened, can be either UNITVBLANK or UNITMICROHZ. RESULTS BUGS SEE ALSO mxm.library/KeyConvert mxm.library/KeyConvert NAME KeyConvert - Convert a raw-key to an ANSI character. SYNOPSIS Character = KeyConvert(IntuiMesssage) FUNCTION This function converts the contents of an IntuiMessage raw-key event according to the current keymap settings into a real ANSI-character. INPUTS IntuiMessage - Pointer to IntuiMessage-structure. RESULTS Character - ANSI character, or NULL. BUGS SEE ALSO mxm.library/InvertKey mxm.library/InvertKey NAME InvertKey - Convert an ANSI character into an InputEvent. SYNOPSIS Event = InvertKey(Code Event Command ExtraInfo) FUNCTION This function turns an ANSI character into an InputEvent structure which can be used to feed it back into the stream of input events. INPUTS Code - ANSI character to be converted. Event - Pointer to InputEvent-structure. Command - A combination of the flags IK_BUILDLIST, IK_USEIKM, IK_USELIST or IK_NOSPECIAL. ExtraInfo - This flag should be set to zero. RESULTS Event - Pointer back to input argument, or NULL. BUGS SEE ALSO mxm.library/EraseGadget mxm.library/EraseGadget NAME EraseGadget - Clear the background of a gadget. SYNOPSIS EraseGadget(RastPort Gadget Colour) FUNCTION The imagery of gadget is erased with this function. INPUTS RastPort - Pointer to the RastPort-structure the gadget will be erased from. Gadget - Pointer to a Gadget-structure. Colour - The pen number to erase the Gadget imagery with. RESULT The gadget's imagery is erased. BUGS SEE ALSO mxm.library/RefreshGadget mxm.library/RefreshGadget NAME RefreshGadget - Refresh a single Gadget. SYNOPSIS RefreshGadget(Gadget Window) FUNCTION This function refreshes a single gadget, not the whole list. INPUTS Gadget - Pointer to a Gadget-structure. Window - Pointer to a Window-structure. RESULTS The gaget's imagery gets redrawn. BUGS SEE ALSO mxm.library/GetLongInt mxm.library/GetLongInt NAME GetLongInt - Get a value from a long integer gadget. SYNOPSIS Value = GetLongInt(Gadget) FUNCTION This function returns the value currently displayed in a long integer gadget. INPUTS Gadget - Pointer to a Gadget-structure. RESULTS Value - The long integer value. BUGS SEE ALSO mxm.library/SetLongInt mxm.library/SetLongInt NAME SetLongInt - Set the value of a long integer gadget. SYNOPSIS SetLongInt(Gadget Val) FUNCTION This function sets the value to be displayed in a long integer gadget. INPUTS Gadget - Pointer to a Gadget-structure. Val - Long integer value to be put into the gadget. RESULTS BUGS The Gadget has to be refreshed to actually see the value displayed. SEE ALSO mxm.library/GetGadgetString mxm.library/GetGadgetString NAME GetGadgetString - Get a string from a string gadget. SYNOPSIS String = GetGadgetString(Gadget) FUNCTION This function returns a pointer to the ASCII-string buffer of a string gadget. INPUTS Gadget - Pointer to a Gadget-structure. RESULTS String - Pointer to an unsigned char (UBYTE). BUGS SEE ALSO mxm.library/SetGadgetString mxm.library/SetGadgetString NAME SetGadgetString - Set the string for a string gadget. SYNOPSIS SetGadgetString(Gadget String) FUNCTION This function sets the string to be displayed in a string gadget. INPUTS Gadget - Pointer to a Gadget-structure. String - Pointer to an unsigned char (UBYTE), i.e. String to be set. RESULTS BUGS The Gadget has to be refreshed to actually see the string displayed. SEE ALSO mxm.library/GetToggleGadget mxm.library/GetToggleGadget NAME GetToggleGadget - Get the state of a Bool-Gadget. SYNOPSIS State = GetToggleGadget(Gadget) FUNCTION This function returns the state of a Bool-Gadget which has the TOGGLEGADGET flags set and can be selected/unselected. INPUTS Gadget - Pointer to a Gadget-structure. RESULTS State - Boolean value, TRUE if gadget is selected, false if otherwise. BUGS SEE ALSO mxm.library/SetToggleGadget mxm.library/SetToggleGadget NAME SetToggleGadget - Set the state of a Bool-Gadget. SYNOPSIS SetToggleGadget(Gadget State) FUNCTION This function sets the select state of a Bool-Gadget which has the TOGGLEGADGET flags set and can be selected/unselected. INPUTS Gadget - Pointer to a Gadget-structure. State - Boolean, TRUE if gadget is to be selected, FALSE if otherwise. RESULTS BUGS The Gadget has to be refreshed to actually see the state displayed. SEE ALSO mxm.library/SetWaitPointer mxm.library/SetWaitPointer NAME SetWaitPointer - Change the pointer to a Zzz-Balloon. SYNOPSIS SetWaitPointer(Window) FUNCTION This function changes the mouse pointer of a window to the standard Workbench-Balloon, indicating that the running task is busy. INPUTS Window - Pointer to a Window-structure. RESULTS The mouse pointer gets changed. BUGS SEE ALSO mxm.library/PopRequest mxm.library/PopRequest NAME PopRequest - Display a pop-up-requester. SYNOPSIS Result = PopRequest(ParentWindow TitleText BodyText PosText NegText Default ExtraInfo) FUNCTION This function brings up a pop-up-requester which is automatically centered under the mouse pointer. The requester can be answered via keyboard, supported positive keys are: Y, J, V, C, R, Return; negative keys are: N, Q, B, Escape. Having answered the requester the original front screen is brought to the front again. INPUTS ParentWindow - Pointer to a Window structure in which you want the requester to appear, may be NULL, so requester will appear on the Workbench screen. TitleText - The title of the requester window, may be NULL, so "System Request:" will be used. BodyText - The text you want to be displayed inside the requester may include ANSI-control sequences (boldface, italics, different colours, etc.) PosText - Text for positive response Gadget, may be NULL in which case no positive Gadget will be displayed. NegText - Tetx for negative response Gadget, may be NULL in which case no negative Gadget will be displayed. PosText & NegText being NULL, NegText will default to "Okay". Default - Boolean value indicating the default value expected from the requester. ExtraInfo - Pointer to a PopSupport structure. RESULTS Result - Boolean, depending on the gadget being selected. BUGS SEE ALSO mxmbase.h/struct PopSupport mxm.library/PopMenu mxm.library/PopMenu NAME PopMenu - Display a pop-up-menu. SYNOPSIS Item = PopMenu(Menu Window) FUNCTION This function displays a menu, very similar to the standard Intuition menus, just under the mouse pointer. INPUTS Menu - Pointer to a Menu-structure. Window - Pointer to a Window-structure. RESULTS The menu item selected, or -1 if no item was selected. BUGS PopMenu does not handle sub-items in the current release. SEE ALSO mxmbase.h mxm.library/Announce mxm.library/Announce NAME Announce - Produce an audible signal. SYNOPSIS Announce() FUNCTION Announce produces a sound, not a beep but a chime, on two stereo channels. INPUTS RESULTS BUGS SEE ALSO mxm.library/CheckSumCRC mxm.library/CheckSumCRC NAME CheckSumCRC - Calculate the 16-bit crc checksum for a memory block. SYNOPSIS CRC = CheckSumCRC(Mem Size) FUNCTION This function uses the Satchell/Forsberg-crc-function to calculate the 16-bit checksum for a memory block with given size. INPUTS Mem - Pointer to memory block to be checksummed. Size - Size of the memory block to be checksummed. RESULTS CRC - The 16-bit crc value for the memory block. BUGS SEE ALSO mxm.library/CheckSumSimple mxm.library/CheckSumSimple NAME CheckSum - Calculate a simple checksum for a memory block. SYNOPSIS Check = CheckSum(Mem Size) FUNCTION Similar to CheckSumCRC this function calculates a checksum for a memory block with given size. The algorithm employed is simpler. INPUTS Mem - Pointer to memory block to be checksummed. Size - Size of the memory block to be checksummed. RESULTS Check - The 32-bit checksum value for the memory block. BUGS SEE ALSO mxm.library/CheckSumCRC mxm.library/CryptBlock mxm.library/CryptBlock NAME CryptBlock - Encrypt/Decrypt a memory block. SYNOPSIS CryptBlock(Mem Size String) FUNCTION This function encrypts/decrypts a block of memory using a pseudo-random number generator. The data is XOR encoded, so a double CryptBlock will result in decryption of the memory block. Additionally a string can be used as a second encryption key. The string is optional and can be left out. INPUTS Mem - Pointer to memory block to be checksummed. Size - Size of the memory block to be checksummed. String - Pointer to second encryption string, may be null. RESULTS BUGS SEE ALSO mxm.library/IsASCII mxm.library/IsASCII NAME IsASCII - Check if a character is a valid Amiga ASCII character. SYNOPSIS IsIt = IsASCII(Character) FUNCTION This function checks if a character belongs to the list of valid Amiga ASCII characters. Unlike compiler macros the international character set of the Amiga is considered. INPUTS Character - The character to be checked. RESULTS IsIt - Boolean, TRUE if Character is a valid Amiga ASCII character. BUGS SEE ALSO toupper() macro mxm.library/IsPrintable mxm.library/IsPrintable NAME IsPrintable - Check if a character is a printable Amiga ASCII character. SYNOPSIS IsIt = IsPrintable(Character) FUNCTION This function checks if a character produces a visible result if printed. Unlike compiler macros the international character set of the Amiga is considered. INPUTS Character - The character to be checked. RESULTS IsIt - Boolean, TRUE if Character is a valid Amiga ASCII character. BUGS SEE ALSO isprintable() macro mxm.library/ToUpper mxm.library/ToUpper NAME ToUpper - Change a character to upper case. SYNOPSIS NewCharacter = ToUpper(Character) FUNCTION This function turns a character into an upper case character. Unlike compiler macros the international character set of the Amiga is considered. INPUTS Character - The character to be turned to upper case. RESULTS NewCharacter - The upper case equivalent to the input character. BUGS SEE ALSO toupper() macro mxm.library/UStrCmp mxm.library/UStrCmp NAME UStrCmp - Case insensitive strcmp(). SYNOPSIS Difference = UStrCmp(Source Target) FUNCTION This function does a strcmp(), character by character, and uses the ToUpper() function to compare the characters. It also matches lower/upper case international characters. INPUTS Source - Pointer to source string. Target - Pointer to target string. RESULTS Difference - The Difference between the strings to be compared, 0 if no difference. BUGS SEE ALSO mxm.library/ToUpper() mxm.library/Random mxm.library/Random NAME Random - Generate a random value. SYNOPSIS Value = Random(MaxValue) FUNCTION Random returns a random value between 0 and MaxValue - 1. The random seed is XORed with the current video beam position, so the random value is guaranteed not to produce repeated sequences of pseudo-random values. INPUTS MaxValue - The maximum value + 1 expected from this function. RESULTS Value - Random value. BUGS SEE ALSO mxm.library/FindFileWindow mxm.library/FindFileWindow NAME FindFileWindow - Find the window associated with a FileHandle. SYNOPSIS Window = FindFileWindow(Handle) FUNCTION This function finds the Intuition window associated with a Console FileHandle by passing the handler task a a request to identify its volume node (i.e.: the Window). INPUTS Handle - BPTR to a FileHandle-structure. RESULTS Window - Pointer to a Window-structure. BUGS This function will produce garbage if used on non-console FileHandles. SEE ALSO mxm.library/DeleteHiddenRPort mxm.library/DeleteHiddenRPort NAME DeleteHiddenRPort - Delete a hidden RastPort created by CreateHiddenRPort(). SYNOPSIS Pointer = DeleteHiddenRPort(RastPort) FUNCTION This function deallocates a hidden RastPort previously created with CreateHiddenRPort(). INPUTS RastPort - Pointer to a RastPort-structure. RESULTS This function always returns NULL, so user can do Pointer = DeleteHiddenRPort(Pointer). BUGS SEE ALSO mxm.library/CreateHiddenRPort mxm.library/CreateHiddenRPort NAME CreateHiddenRPort - Create a hidden RastPort. SYNOPSIS RastPort = CreateHiddenRPort(Width Height Depth) FUNCTION This function allocates a RastPort structure, a BitMap structure, initializes them and adds the requested number of planes to the BitMap. The planes are zeroed out before this function returns. INPUTS Width - Width of the RastPort. Height - Height of the RastPort. Depth - Depth of the RastPort. RESULTS RastPort - Pointer to a RastPort structure, or NULL. BUGS SEE ALSO mxm.library/EnableWindow mxm.library/EnableWindow NAME EnableWindow - Enable all gadgets of a window and restore the mouse pointer. SYNOPSIS EnableWindow(Window) FUNCTION This function reenables the gadgets of a window previously disabled with DisableWindow() and sets the standard system mouse pointer. INPUTS Window - The Window to be reenabled. RESULTS BUGS Can only handle windows really disabled via DisableWindow(), may crash on other windows. SEE ALSO mxm.library/DisableWindow() mxm.library/DisableWindow mxm.library/DisableWindow NAME DisableWindow - Disable all gadgets of a window and set a Zzz mouse pointer. SYNOPSIS Success = DisableWindow(Window) FUNCTION This function disables all custom gadgets to be found in the window and sets a Zzz mouse pointer. INPUTS Window - Pointer to a Window-structure. RESULTS Success - Boolean, TRUE if window was disabled. BUGS You MUST not remove or add Gadgets to the window after it has been disabled, or EnableWindow() will panic. SEE ALSO mxm.library/EnableWindow()