TABLE OF CONTENTS

mach.library/AllocMacroObject
mach.library/atox
mach.library/CloseListWindow
mach.library/DeallocMacroObject
mach.library/FindByName
mach.library/FindConfigByName
mach.library/FindMacroObject
mach.library/FindUnderscoreChar
mach.library/FreeMacroObject
mach.library/FreeTempMacroBuffer
mach.library/GetMacroObject
mach.library/InitMacroObject
mach.library/NewMacroObject
mach.library/OpenListWindow
mach.library/SortExecList

mach.library/AllocMacroObject                   mach.library/AllocMacroObject

	NAME
	AllocMacroObject -- Allocate a MacroObject.
   
	SYNOPSIS
	AllocMacroObject(void)
   
	struct MacroObject* AllocMacroObject( )
   
	FUNCTION
	Allocate memory for a MacroObject. This does nothing more than that.
	Do not use static MacroObjects because the struct size may change in
	the future.

	WARNING
   
	INPUTS
	None
   
	RESULTS
	Pointer to a MacroObject if successful,
	NULL if not and low memory alert put up.
   
	SEE ALSO
	DeallocMacroObject
mach.library/atox                                           mach.library/atox

	NAME
	atox -- Ascii hex to long.
   
	SYNOPSIS
	atox(char *)
   
	long atox(char *string )
   
	FUNCTION
	Convert an ascii string of hex characters to a long integer.

	INPUTS
	string - Pointer to ascii string.
   
	RESULTS
	Long integer.
   
	SEE ALSO
mach.library/CloseListWindow                     mach.library/CloseListWindow

	NAME
	CloseListWindow -- Close the list window.
   
	SYNOPSIS
	CloseListWindow(void)
   
	void CloseListWindow(void)
   
	FUNCTION
	Closes the list window. 

	INPUTS
	None.

	RESULTS
	The window is closed.

	SEE ALSO
	OpenListWindow
mach.library/DeallocMacroObject                mach.library/DellocMacroObject

	NAME
	DeallocMacroObject -- Deallocate a MacroObject.
   
	SYNOPSIS
	DeallocMacroObject(struct MacroObject* mo)
   
	void DeallocMacroObject(struct MacroObject* )
   
	FUNCTION
	Deallocate memory for a MacroObject. This does nothing more than that.
	Do not use static MacroObjects because the struct size may change in
	the future.

	WARNING
   
	INPUTS
	mo - a pointer to a MacroObject. NULL is ok.
   
	RESULTS
	The MacroObject is freed.
   
	SEE ALSO
	AllocMacroObject
mach.library/FindByName                               mach.library/FindByName
   
    NAME
    FindByName -- Find a MacroObject by its name.
   
    SYNOPSIS
    FindByName(cfg, sname, match_type )
               A0   A1     D0
   
    struct MacroObject* FindByName(struct MachCfg *, char *, UWORD , UWORD )
   
    FUNCTION
    Finds a MacroObject by its name. May expand or restrict search with 
    different values for match_type. 
   
    WARNING
	Be sure to surround calls to this function with Obtain/ReleaseSemaphore 
   
    INPUTS
    cfg			= pointer to the desired configuration.
    sname		= pointer to macro name.
    match_type	= control the search with these flags or'ed together:

       MT_LOCALS        - search only the supplied configuration.
       MT_GLOBALS       - search the supplied configuration and then
                          the first configuration if not the same.
       MT_WILDCARDS     - allow wild cards in the search.  
	   MT_EXACT_MATCH   - macro name must match exactly.
	   MT_SLOPPY_MATCH  - case insensitive and match only up to length of
                          supplied name.
	   MT_MATCH_NEXT	- continue to search after match with wildcards.

    RESULT
    results - pointer to found MacroObject if successful,
		 	  NULL if not.
   
    EXAMPLE
	#include <stdio.h>                                                       
	#include <ctype.h>                                                       
	#include <exec/types.h>
	#include <exec/libraries.h>
	#include <proto/exec.h>                                                  
	#include "mach.h"
	#include "machlib.h"                                            
	#include "machlib_protos.h"                                     
	#include "machlib_pragmas.h"                                    
	                                                                         
	void FindMacro(char *mname);                                             
	                                                                         
	struct MachLibrary *MachBase;                                            
	                                                                         
	main(int argc, char **argv)                                              
	{                                                                        
	    if (argc == 2) {                                                     
	        MachBase = (struct MachLibrary*)OpenLibrary("mach.library",37L); 
	        if (MachBase) {                                                  
	            FindMacro(argv[1]);                                          
	            CloseLibrary((struct Library*)MachBase);                     
	        }                                                                
	    }                                                                    
	}                                                                        
	                                                                         
	void FindMacro(char *mname)                                              
	{                                                                        
	    ULONG mt;                                                            
	    struct MacroObject *mo;                                              
	                                                                         
	    ObtainSemaphore(&MachBase->ml_BaseSemaphore);                        
	    mt = MT_WILDCARDS | MT_GLOBALS;                                      
	    while (mo = FindByName(MachBase->ml_CurConfig,mname,mt)) {           
	        printf("found %s\n", mo->mo_Name);                               
	        mt |= MT_MATCH_NEXT;
	    }                                                                    
	    ReleaseSemaphore(&MachBase->ml_BaseSemaphore);                       
	}

    SEE ALSO
   
mach.library/FindConfigByName                   mach.library/FindConfigByName

	NAME
	FindConfigByName -- Find a configuration by name.
   
	SYNOPSIS
	FindConfigByName(cname)
					 A0

	struct MachCfg* FindConfigByName(char *)
   
	FUNCTION
	Finds the configuration by matching titles with cname.
	Uses stpicmp() for case insensitive matching upto length of cname.
   
	INPUTS
	cname - pointer to a configuration name.
   
	RESULTS
	Pointer to found configuration if successful,
	NULL if not.
   
	SEE ALSO
   
mach.library/FindMacroObject                     mach.library/FindMacroObject

	NAME
	FindMacroObject -- Find an existing MacroObject.
   
	SYNOPSIS
	FindMacroObject(cfg, code, qual,match_type)
	   				A0	 D0    D1	D2
   
	struct MacroObject* FindMacroObject(struct MachCfg *,
	UWORD ,UWORD ,ULONG)
   
	FUNCTION
	Find a MacroObject in chain at code that matches qual.
	Searches global macros if match_type == MT_GLOBALS.
   
	INPUTS
	cfg		- a pointer to the desired configuration.
	code 	- keycode or UNKEYED for a un-keyed named macro.
	qual	- qualifiers for hotkey combination. -1 for UNKEYED.
	match_type - MT_GLOBALS to seach THE specified configuration and 
                 then the first for globals. Use MT_LOCALS to search 
                 just the specified configuration.
   
	RESULTS
	Pointer to old MacroObject if successful,
	NULL if not.
   
	SEE ALSO
	NewMacroObject, GetMacroObject
mach.library/FindUnderscoreChar               mach.library/FindUnderscoreChar

	NAME
	FindUnderscoreChar -- Find keycode for underscored character.

	SYNOPSIS
	FindUnderscoreChar(char *)
   
	UBYTE FindUnderscoreChar(char *s )
   
	FUNCTION
	Searches ascii string for underscore character. When found, returns
	keycode for the following character. Given the string '_Cancel', this
	function returns the keycode for the letter 'C' using the current 
	keymap. 

	This is usually used to find the keycode for a keyboard shortcut for
	a gadtools gadget.

	INPUTS
	s - Pointer to ascii string. 
   
	RESULTS
	Keycode for character following underscore.
   
	SEE ALSO
mach.library/FreeMacroObject                     mach.library/FreeMacroObject

	NAME
	FreeMacroObject -- Find and free a MacroObject.
   
	SYNOPSIS
	FreeMacroObject(cfg, code, qual)
					A0   D0    D1
   
	void FreeMacroObject(struct MachCfg *, char *, UWORD ,UWORD )
   
	FUNCTION
	Find and then free a MacroObject and its macro.
	Remove from configuration macro list.
   
	INPUTS
	cfg	 - a pointer to the desired configuration.
	code - keycode or UNKEYED for a un-keyed named macro.
	qual - qualifiers for hotkey combination. Ordinal number for UNKEYED 
	       macro.
   
	RESULTS
	None.
   
	SEE ALSO

mach.library/FreeTempMacroBuffer             mach.library/FreeTempMacroBuffer

	NAME
	FreeTempMacroBuffer -- Frees MachBase->ml_TempMacroBuffer.

	SYNOPSIS
	FreeTempMacroBuffer(void)

	void FreeTempMacroBuffer(void)

	FUNCTION
	Free the buffer MachBase->ml_TempMacroBuffer. This is the buffer
	used when recording a macro. Its size is taken from
	MachBase->ml_CurConfig->mc_Buffersize.

	INPUTS
	None.

	RESULTS
	MachBase->ml_TempMacroBuffer is freed and nulled.

	SEE ALSO
   
mach.library/GetMacroObject                       mach.library/GetMacroObject

	NAME
	GetMacroObject -- Find an old or insert new MacroObject.
   
	SYNOPSIS
	GetMacroObject(cfg, code, qual)
				   A0   D0    D1

	struct MacroObject* GetMacroObject(struct MachCfg *,
	UWORD ,UWORD ,ULONG)
   
	FUNCTION
	Find a MacroObject matching code/qual. If not found, allocate
	new MacroObject and add it to the hotkey list in the specified
	configuration.
	mo_Link.ln_Name will point to mo_Name.
   
	WARNING
	This function returns an existing MacroObject if code and qual match.
   
	INPUTS
	cfg		- a pointer to the desired configuration.
	code 	- keycode or UNKEYED for a un-keyed named macro.
	qual	- qualifiers for hotkey combination. -1 for UNKEYED.
	match_type - MT_GLOBALS to seach THE specified configuration and 
                 then the first for globals. Use MT_LOCALS to search 
                 just the specified configuration.

	RESULTS
	Pointer to old or new MacroObject if successful,
	NULL if not and low memory requester put up.
	mo_Code and mo_Qual are set.
	mo_Link.ln_Name will point to mo_Name.
   
	SEE ALSO
	NewMacroObject
mach.library/InitMacroObject                     mach.library/InitMacroObject

	NAME
	InitMacroObject -- Initialize a MacroObject.
   
	SYNOPSIS
	InitMacroObject(mo)
					A0

	struct MacroObject* InitMacroObject(struct MacroObject *)

	FUNCTION
	Initialize (zeroes) a MacroObject. Does not affect linkage
	pointers. Frees a macro if mo_Macro is not NULL.
   
	WARNING
   
	INPUTS
	mo - a pointer to a MacroObject
   
	RESULTS
	results - a pointer to the initialized MacroObject.
   
	SEE ALSO

mach.library/NewMacroObject                       mach.library/NewMacroObject

	NAME
	NewMacroObject -- Alloc and connect a new (or old) MacroObject.
   
	SYNOPSIS
	NewMacroObject(cfg, string, code, qual)
				   A0   A1      D0    D1
   
	struct MacroObject* NewMacroObject(struct MachCfg *, char *,
	UWORD ,UWORD )
   
	FUNCTION
	Allocate a new MacroObject and add it to the hotkey list in the
	specified configuration. Space is allocated for the string and
	it is copied to mo_Macro. mo_Size, mo_Code and mo_Qual are set.
	mo_Link.ln_Name will point to mo_Name.
   
	WARNING
	This function uses an existing MacroObject if code and qual match.
	It will discard existing macro and replace it with string.
   
	INPUTS
	cfg		- a pointer to the desired configuration.
	string	- pointer to a null terminated text string.
	code 	- keycode or UNKEYED for a un-keyed named macro.
	qual	- qualifiers for hotkey combination. -1 for UNKEYED.
   
	RESULTS
	results - pointer to new MacroObject if successful,
			  NULL if not and low memory alert put up.
   
	SEE ALSO
	GetMacroObject
mach.library/OpenListWindow                       mach.library/OpenListWindow

	NAME
	OpenListWindow -- Open a window listing macros or configurations.
   
	SYNOPSIS
	OpenListWindow(tags)
                   A0
   
	BOOL OpenListWindow(struct TagItem *tags)
   
	FUNCTION
	This opens a window with a list gadget containing macro names, alarm 
	names, window or screen titles, or configuration titles. When called, 
	a separate process is created which waits on the window signals.
	When the user makes a selection, your task will be signaled and 
    MachBase->ml_ListSelection will point to the string. If the user made 
    no selection (clicked on Cancel, the close gadget or pressed Return with 
    the string gadget empty), MachBase->ml_ListSelection will be NULL.

	Current tags:

	LIST_TaskInfo      Pointer to a TaskInfo struct (see mach.h).
	LIST_Type          See below for types.
	LIST_LeftEdge      Default = -1 which centers the window.
	LIST_TopEdge       Default = -1 which places it at 10 below screen top.
	LIST_Globals       Current configuration + globals? Default = TRUE.
	LIST_AlarmsOnly    List only alarms. Default = FALSE.
	LIST_Title         List window title.
	LIST_OkayString    Okay gadget text.
	LIST_CancelString  Cancel gadget text.

	Allowable tag values for LIST_Type:

	LIST_WINDOWS		List window titles.
	LIST_SCREENS		List screen titles.
	LIST_MACRONAMES		List macro names.
	LIST_MACROALARMS	List macros with clk_alarm.
	LIST_CONFIGNAMES	List configuration names.

	WARNING
	This routine is not reentrant! Only one list window may be open at a
	time.
	The window will open on the front screen, public or not. If the screen
	closes with the list still open, the system will crash. However, MachV
	monitors screen closings and will close it for you. MachV will also
	close it when MachV is terminated. You will receive your signal if the 
    list window is being closed for you.

	INPUTS
	tags - tags describing desired attributes.
   
	RESULTS
	TRUE if opened successfully or is already open.
	FALSE if not.
   
    EXAMPLE
	#include <stdio.h>                                                       
	#include <ctype.h>                                                       
	#include <exec/types.h>
	#include <exec/libraries.h>
	#include <proto/exec.h>                                                  
	#include "mach.h"
	#include "machlib.h"                                            
	#include "machlib_protos.h"                                     
	#include "machlib_pragmas.h"                                    

	struct MachLibrary *MachBase;                                            

	/* This lets you call OpenListWindow() with a variable number of tags. */

	BOOL OpenListWindowTags(ULONG tags,...);

	BOOL OpenListWindowTags(ULONG tags,...)
	{
		return(OpenListWindow((struct TagItem *)&tags));
	}

	main(int argc, char **argv)                                              
	{                                                                        
		struct TaskInfo list_task_info;
		LONG listsig_nr;
		ULONG list_sig;

		MachBase = (struct MachLibrary*)OpenLibrary("mach.library",37L); 
		if (MachBase) {                                                  
			if ((listsig_nr = AllocSignal(-1L)) != -1L) {
				list_sig = 1 << listsig_nr;
				list_task_info.Task = FindTask(NULL);
				list_task_info.Sig = list_sig;
	
				/* Open list window listing macro names */
	
				if (OpenListWindowTags(LIST_TaskInfo,	(ULONG)&list_task_info,
									   LIST_Type,		LIST_MACRONAMES,
									   LIST_Title,		(ULONG)"Macro Names",
									   TAG_DONE)) {
	
					/* Wait for selection, ok, cancel or close window */
	
					Wait(list_sig);
	
					FreeSignal(listsig_nr);

					if (MachBase->ml_ListSelection ) 
						printf("Selected %s\n",MachBase->ml_ListSelection);
					else
						printf("No selection\n" );
				}
			}
			CloseLibrary((struct Library*)MachBase);                     
		}                                                                
	}                                                                        
	                                                                         
	SEE ALSO
	DeallocMacroObject
mach.library/SortExecList                           mach.library/SortExecList

	NAME
	SortExecList -- Sort an exec list.
   
	SYNOPSIS
	SortExecList(struct List *)
   
	void SortExecList(struct List *list)
   
	FUNCTION
	Sorts an exec list based on ln_Name. Uses Stricmp() for a case insensitive 
	sort.

	WARNING
	No arbitration is performed. The user should ensure that the list is
	protected from access by other tasks by using semaphores or Forbid().

	INPUTS
	list - Pointer to an exec list.

	RESULTS
	The list is sorted.

	SEE ALSO