TABLE OF CONTENTS appshell.library/__ACTIVATE appshell.library/__ALIAS appshell.library/__CMDSHELL appshell.library/__DEACTIVATE appshell.library/__DISABLE appshell.library/__ENABLE appshell.library/__FAULT appshell.library/__RX appshell.library/__RXS appshell.library/__STUB appshell.library/__SYSTEM appshell.library/__WHY appshell.library/__WINDOW appshell.library/__WINDOWTOBACK appshell.library/__WINDOWTOFRONT appshell.library/AddFuncEntries appshell.library/AddFuncEntry appshell.library/AddProjects appshell.library/APSHClearPointer appshell.library/APSHGetGadgetInfo appshell.library/APSHGetWindowInfo appshell.library/APSHSetWaitPointer appshell.library/BuildParseLine appshell.library/ExpandPattern appshell.library/FindType appshell.library/FreeFuncEntries appshell.library/FreeFuncEntry appshell.library/FreeParseLine appshell.library/FreeProject appshell.library/FreeProjects appshell.library/GetFuncEntry appshell.library/GetFuncID appshell.library/GetFuncName appshell.library/GetProjNode appshell.library/GetText appshell.library/HandleApp appshell.library/HandleAppAsync appshell.library/HandlerDataA appshell.library/HandlerFuncA appshell.library/IconFromWBArg appshell.library/LMatchFirst appshell.library/LockAppInfo appshell.library/MatchValue appshell.library/NewProject appshell.library/NotifyUser appshell.library/ParseLine appshell.library/PerfFunc appshell.library/PrepText appshell.library/QStrCmpI appshell.library/RemoveMsgPort appshell.library/RemoveProject appshell.library/RenumProject appshell.library/setup_arexxA appshell.library/setup_dosA appshell.library/setup_idcmpA appshell.library/setup_notifyA appshell.library/setup_sipcA appshell.library/setup_toolA appshell.library/setup_wbA appshell.library/SwapProjNodes appshell.library/UnlockAppInfo appshell.library/__ACTIVATE appshell.library/__ACTIVATE NAME ACTIVATE - Restore the GUI to the state prior to DEACTIVATE SYNOPSIS ActivateID Function ID FUNCTION Restores the GUI to the state prior to deactivating the window. This will also reload user preferences. This function accepts no parameters. As a string command line: ACTIVATE , This function is implemented by the IDCMP message handler. SEE ALSO DEACTIVATE BUGS Doesn't handle tools properly. appshell.library/__ALIAS appshell.library/__ALIAS NAME ALIAS - Used to build new commands from existing commands. SYNOPSIS AliasID Function ID FUNCTION This command is used to build new commands from existing commands in the function table. As a string command line: ALIAS NAME,COMMAND/F NAME New name to assign to command. COMMAND Command, and its arguments to assign to NAME. EXAMPLE The following command line would assign the command OPEN to the new command name README, and would use READ.ME as the parameter to pass. ALIAS README OPEN READ.ME appshell.library/__CMDSHELL appshell.library/__CMDSHELL NAME CMDSHELL - Open/Close the application command shell. SYNOPSIS CMDShellID Function ID FUNCTION Opens a console window whereby the user can interact directly with the application at a command level. Allows the user quick access to functions or macros that they may use so infrequently that they don't wish to bind them to a key, menu or button. As a string command line: CMDSHELL OPEN/s,CLOSE/s,TITLE/k,SNAPSHOT/s,ACTIVATE/s,FRONT/s,BACK/s,WINDOW/k OPEN Open the command shell. CLOSE Close the command shell. TITLE Set the title of the command shell window. SNAPSHOT Save the window size to disk. ACTIVATE Activate the command shell. FRONT Send the command shell to the front. BACK Send the command shell to the back. WINDOW Name of window to open relative to. Defaults to "Main". As a TagItem attribute list: APSH_Command, where is a valid command, defaults to MH_OPEN. MH_OPEN Open the command shell. MH_CLOSE Close the command shell. This function is implemented by the DOS message handler. appshell.library/__DEACTIVATE appshell.library/__DEACTIVATE NAME DEACTIVATE - Shut down the GUI. SYNOPSIS DeActivateID Function ID DeActivateFunc Function prototype FUNCTION This function will shut down the graphical user interface of the application. This function accepts no parameters. As a string command line: DEACTIVATE , This function is implemented by the IDCMP message handler. SEE ALSO ACTIVATE BUGS Currently, only tracks the main process (no tools or clones receive the DEACTIVATE message yet) and the command shell. appshell.library/__DISABLE appshell.library/__DISABLE NAME DISABLE - Disable a function and its interfaces. SYNOPSIS DisableID Function ID FUNCTION This function allows an application or user to disable a function. If the function is attached to a gadget or menu item, then that item is also disabled. This function does wildcard expansion. As a string command line: DISABLE NAMES/M NAMES The list of valid function names to disable. As a TagItem attribute list: APSH_NameTag, where is a valid function name. EXAMPLE The following command would disable all commands in an application except for those that would be available before the users selects NEW. DISABLE #? ENABLE NEW OPEN ABOUT QUIT PREF#? SEE ALSO ENABLE BUGS Doesn't disable menu items yet. appshell.library/__ENABLE appshell.library/__ENABLE NAME ENABLE - Enable a function and its interfaces. SYNOPSIS EnableID Function ID FUNCTION This function allows an application or user to enable a function. If the function is attached to a gadget or menu item, then that item is also enabled. This function does wildcard expansion. As a string command line: ENABLE NAMES/M NAMES The list of valid function names to enable. As a TagItem attribute list: APSH_NameTag, where is a valid function name. SEE ALSO DISABLE BUGS Doesn't enable menu items yet. appshell.library/__FAULT appshell.library/__FAULT NAME FAULT - Return the text for an error number. SYNOPSIS FaultID Function ID FUNCTION This function will return the text assigned to an error number. As a string command line: FAULT /N /N Number to return the text for. This function is implemented by the ARexx message handler. appshell.library/__RX appshell.library/__RX NAME RX - Execute an ARexx macro. SYNOPSIS RXID Function ID FUNCTION Allows access to ARexx functions that may have otherwise been rerouted by the application. Should only be used if there are name conflicts between an application function and an ARexx function. As a string command line: RX ASYNC/S, CMD/F ASYNC Send the command to the asynchronous port. CMD Command to execute. As a TagItem attribute list: APSH_CmdString, where is a command line to pass to ARexx. This function is implemented by the ARexx message handler. BUGS ASYNC is not implemented. appshell.library/__RXS appshell.library/__RXS NAME RXS - Execute an ARexx string file. SYNOPSIS RXSID Function ID FUNCTION Allows access to ARexx functions that may have otherwise been rerouted by the application. Should only be used if there are name conflicts between an application function and an ARexx function. As a string command line: RXS ASYNC/S, STRING/F ASYNC Send the command to the asynchronous port. STRING String file to execute. As a TagItem attribute list: APSH_CmdString, where is a command line to pass to ARexx. This function is implemented by the ARexx message handler. BUGS ASYNC is not implemented. appshell.library/__STUB appshell.library/__STUB NAME STUB - A do nothing function. SYNOPSIS StubID Function ID FUNCTION This function does absolutely nothing. As a string command line: STUB appshell.library/__SYSTEM appshell.library/__SYSTEM NAME SYSTEM - Execute a system command or application. SYNOPSIS SystemID Function ID FUNCTION This function uses the AmigaDOS command Run to execute a command. As a string command line: SYSTEM ASYNC/S,PUBSCREEN/S,HOSTPORT/S,COMMAND/F ASYNC Run the command asynchronously. PUBSCREEN Pass the name of the applications public screen with the PUBSCREEN keyword. HOSTPORT Pass the name of the applications ARexx port with the HOSTPORT keyword. This function is implemented by the DOS message handler. appshell.library/__WHY appshell.library/__WHY NAME WHY - Return information on the last error. SYNOPSIS WhyID Function ID FUNCTION For scripting purpose, the primary return value of a command should return an error level. This limits the error return values to small ranges (to be consistent with DOS). Therefore, if commands use the secondary return field to contain information on the actual error, then this function will allow scripts to obtain information on what the last error actually was. This command takes no parameters. This function is implemented by the ARexx message handler. appshell.library/__WINDOW appshell.library/__WINDOW NAME WINDOW - Open/Close an AppShell window SYNOPSIS WindowID Function ID FUNCTION Provides a mechanism to open or close an AppShell window. As a string command line: WINDOW NAME,TITLE/k,OPEN/s,CLOSE/s,SNAPSHOT/s,ACTIVATE/s,MIN/s,MAX/s, FRONT/s,BACK/s,ZOOM/s,UNZOOM/s,LOCK/s,UNLOCK/s NAME Name of the window to manipulate. TITLE Title to assign to the window. OPEN Open the window. CLOSE Close the window. SNAPSHOT Save the window information to disk. ACTIVATE Activate the window. MIN Set the window to minimum size. MAX Set the window to maximum size. FRONT Send the window to the front. BACK Send the window to the back. ZOOM Set the window to its zoom size. UNZOOM Set the window to its normal size. LOCK Lock out input to the window. UNLOCK Unlock a locked window. As a TagItem attribute list: APSH_NameTag, where is a valid window name. APSH_WinPointer, where points to a valid window structure. APSH_Command, where is a valid command. APSH_MH_OPEN To open the window. APSH_MH_CLOSE To close the window. This function is implemented by the IDCMP message handler. SEE ALSO WINDOWTOBACK, WINDOWTOFRONT appshell.library/__WINDOWTOBACK appshell.library/__WINDOWTOBACK NAME WINDOWTOBACK - Send an AppShell window to the back. SYNOPSIS WindowToBackID Function ID FUNCTION Provides a mechanism to send an AppShell window to the back of the other windows on the same screen. As a string command line: WINDOWTOBACK NAME NAME Name of the window to send to the back. Defaults to MAIN. As a TagItem attribute list: APSH_NameTag, where is a valid window name. APSH_WinPointer, where points to a valid window structure. This function is implemented by the IDCMP message handler. SEE ALSO WINDOWTOFRONT, WINDOW appshell.library/__WINDOWTOFRONT appshell.library/__WINDOWTOFRONT NAME WINDOWTOFRONT - Bring an AppShell window to the front. SYNOPSIS WindowToFrontID Function ID FUNCTION Provides a mechanism to bring an AppShell window in front of the other windows on the same screen. As a string command line: WINDOWTOFRONT NAME NAME Name of the window to bring to the front. Defaults to MAIN. As a TagItem attribute list: APSH_NameTag, where is a valid window name. APSH_WinPointer, where points to a valid window structure. This function is implemented by the IDCMP message handler. SEE ALSO WINDOWTOBACK, WINDOW appshell.library/AddFuncEntries appshell.library/AddFuncEntries NAME AddFuncEntries - Add an array of entries to the function table. SYNOPSIS results = AddFuncEntries (ai, entries) D0 D0 D1 BOOL results; struct AppInfo *ai; struct Funcs *entries; FUNCTION This function is used to add a NULL terminated array of entries to the application's function table. The function table is maintained as an Exec linked list. The AppShell will free all entries when the application is shutdown. INPUTS ai - Pointer to the application's AppInfo structure. entries - Pointer to a NULL terminated array of Funcs structures that describes the entry to be added to the function table. RESULT TRUE - AppShell was able to add the array to the table. FALSE - Unable to add the array to the function table. SEE ALSO AddFuncEntry(), FreeFuncEntry(), FreeFuncEntries() appshell.library/AddFuncEntry appshell.library/AddFuncEntry NAME AddFuncEntry - Add an entry to the function table SYNOPSIS results = AddFuncEntry (ai, entry) D0 D0 D1 BOOL results; struct AppInfo *ai; struct Funcs *entry; FUNCTION This function is used to add a new entry to the application's function table. The function table is maintained as an Exec linked list. The AppShell will free all entries when the application is shutdown. INPUTS ai - Pointer to the application's AppInfo structure. entry - Pointer to a Funcs structure that describes the entry to be added to the function table. RESULT TRUE - AppShell was able to add the function to the table. FALSE - Unable to add the entry to the function table. SEE ALSO AddFuncEntries(), FreeFuncEntry(), FreeFuncEntries() appshell.library/AddProjects appshell.library/AddProjects NAME AddProjects - Add an array of WBArgs to the project list. SYNOPSIS result = AddProjects (ai, numargs, args, attrs) D0 D0 D1 A0 A1 BOOL result; struct AppInfo *ai; LONG numargs; struct WBArg *args; struct TagItem *attrs; FUNCTION Add an array of WBArgs to the given project list. Defaults to the main project list. Valid TagItems are: APSH_ProjInfo, Where is a valid pointer to a Project structure. Defaults to the AppInfo project structure. INPUTS ai - Pointer to the application AppInfo structure. numargs - Number of arguments in the array. args - Pointer to an array of WBArg structures. attrs - Pointer to an optional TagItem array. appshell.library/APSHClearPointer appshell.library/APSHClearPointer NAME APSHClearPointer - Restore the default pointer. SYNOPSIS APSHClearPointer (ai, attrs) D0 D1 struct AppInfo * ai; struct TagItem * attrs; FUNCTION This function restores the default pointer for the specified window. Defaults to the current window (according to AppShell). The image comes from ENV:/pointer.ilbm Valid TagItems are: APSH_WinName, where is a valid window name. APSH_WinPointer, where points to a valid window. INPUTS ai - Optional pointer to the AppInfo structure for this application. attrs - Optional pointer to an array of TagItems. SEE ALSO APSHSetWaitPointer appshell.library/APSHGetGadgetInfo appshell.library/APSHGetGadgetInfo NAME APSHGetGadgetInfo - Obtain a pointer to a gadget and its window. SYNOPSIS success = APSHGetGadgetInfo (ai, winname, gadname, winptr, gadptr) BOOL success; struct AppInfo *ai; STRPTR winname, gadname; ULONG *winptr, *gadptr; FUNCTION Obtain a pointer to a gadget and the window that it belongs in. Always use this function to get a pointer to a gadget before manipulating it. Never store the gadget or window pointers in your UserData for the application. It is possible that the window is closed or been closed since the time you last obtained a gadget pointer and are therefore referencing invalid memory locations. This function is implemented by the IDCMP message handler. EXAMPLE /* Sample function showing how to use APSHGetGadgetInfo */ VOID StubFunc (struct AppInfo * ai, STRPTR cmd, struct TagItem * tl) { struct Gadget *gad; struct Window *win; /* Get a pointer to the main window, named MAIN, and the Scrolling * List gadget, which is named LIST. */ if (APSHGetGadgetInfo (ai, "MAIN", "LIST", (ULONG *)&win, (ULONG *)&gad)) { /* ... do something with the fields ... */ } } INPUTS ai - Pointer to the AppInfo structure winname - Pointer to the name of the window that the gadget is supposed to be located in. gadname - Pointer to the name of the gadget. winptr - Address of the variable to place the window pointer in. gadptr - Address of the variable to place the gadget pointer in. RETURN success - TRUE indicates that the system was able to locate the gadget and that gadptr is set. winptr can be used to determine if the window is actually open. FALSE indicates that the system was unable to locate the gadget. BUGS This version of the AppShell has stolen the window and gadget UserData fields. Until a method is provided to access per window and gadget data, don't use the window->UserData or gadget->UserData. appshell.library/APSHGetWindowInfo appshell.library/APSHGetWindowInfo NAME APSHGetWindowInfo - Obtain a pointer to a window. SYNOPSIS success = APSHGetWindowInfo (ai, winname, winptr) BOOL success; struct AppInfo *ai; STRPTR winname; ULONG *winptr; FUNCTION Obtain a pointer to the named window. Always use this function to get a pointer to a window before manipulating it. Never store the window pointers in the application's UserData. It is possible that the window is closed or been closed since the time you last obtained its pointer and are therefore referencing invalid memory locations. This function is implemented by the IDCMP message handler. EXAMPLE /* Sample function showing how to use APSHGetWindowInfo */ VOID StubFunc (struct AppInfo * ai, STRPTR cmd, struct TagItem * tl) { struct Window *win; /* Get a pointer to the main window, named MAIN */ if (APSHGetWindowInfo (ai, "MAIN", (ULONG)&win)) { /* ... do something with the fields ... */ } } INPUTS ai - Pointer to the AppInfo structure winname - Pointer to the name of the window. winptr - Address of the variable to place the window pointer in. RETURN success - TRUE indicates that the system was able to locate the named window and that it was open. FALSE indicates that the system was unable to locate the named window or that it wasn't open. BUGS This version of the AppShell has stolen the window and gadget UserData fields. Until a method is provided to access per window and gadget data, don't use the window->UserData or gadget->UserData. appshell.library/APSHSetWaitPointer appshell.library/APSHSetWaitPointer NAME APSHSetWaitPointer - Display a wait pointer. SYNOPSIS APSHSetWaitPointer (ai, attrs) D0 D1 struct AppInfo * ai; struct TagItem * attrs; FUNCTION This function displays a wait pointer in the specified window. Defaults to the current window (according to AppShell). The image comes from ENV:/busypointer.ilbm Valid TagItems are: APSH_WinName, where is a valid window name. APSH_WinPointer, where points to a valid window. EXAMPLE struct TagItem attr[2]; /* Set the wait pointer */ attr[0].ti_Tag = APSH_WinName; attr[0].ti_Data = (ULONG) "Main"; attr[1].ti_Tag = TAG_DONE; APSHSetWaitPointer (ai, attr); /* Bring up the ASL file requester */ if (AslRequest (ad->ad_FR, SaveTags)) { /* Build up the complete project file name */ strcpy (ad->ad_Name, ad->ad_FR->rf_Dir); AddPart (ad->ad_Name, ad->ad_FR->rf_File, 256); /* Save the file */ } /* Clear the wait pointer */ APSHClearPointer (ai, attr); INPUTS ai - Optional pointer to the AppInfo structure for this application. attrs - Optional pointer to an array of TagItems. SEE ALSO APSHClearPointer appshell.library/BuildParseLine appshell.library/BuildParseLine NAME BuildParseLine - Non-destructive string parser SYNOPSIS handle = BuildParseLine (line, argc, argv) D0 D0 D1 A0 STRPTR handle; STRPTR line; ULONG *argc; STRPTR argv[MAXARGS]; FUNCTION This function is used to parse a string that may end up being passed to another function. It does not modify the passed string. Requires a corresponding call to FreeParseLine, when the application's function is done with the parsed line. INPUTS line - Pointer to the string to parse. argc - Pointer to variable to hold the number of arguments. argv - Pointer to an array to hold the arguments. The array must contain MAXARGS entries. RETURN handle - Pointer to a temporary work area which must be passed back to FreeParseLine when done with the parsed array. EXAMPLE /* sample function showing how to use BuildParseLine & FreeParseLine */ function() { STRPTR argv[MAXARGS], handle = NULL; ULONG argc; /* Parse the command line */ handle = BuildParseLine ("ACTIVATE ME", &argc, argv); /* Do something with the parsed command line. The strings * must be copied before calling FreeParseLine if they are * going to be used later. */ printf("%ld words, first is %s\n", argc, argv[0]); /* free the BuildParseLine resources */ FreeParseLine(handle); } SEE ALSO FreeParseLine(), ParseLine() appshell.library/ExpandPattern appshell.library/ExpandPattern NAME ExpandPattern - Expand pattern into files. SYNOPSIS success = ExpandPattern (ai, cmd, attrs) D0 A1 A2 A3 struct AppInfo *ai; STRPTR cmd; struct TagItem *attrs; FUNCTION Expands a pattern into a list of file names, the names are added to a project list. Valid TagItems are: APSH_ArgList, NULL terminated argument list, as returned by ReadArgs for a /M argument. INPUTS ai - Pointer to the application AppInfo structure. cmd - Pointer to an optional command string. attrs - Pointer to the TagItem array. RESULT success - TRUE to indicate success, FALSE for failure. appshell.library/FindType appshell.library/FindType NAME FindType - Find the value of a variable. SYNOPSIS value = FindType(argv, name, defvalue) D0 D0 D1 A0 STRPTR value; STRPTR argv[MAXARGS]; STRPTR name, defvalue; FUNCTION This function searches a parsed text array for a given entry and returns a pointer to the value bound to that entry. If the entry is not found, then a pointer to defvalue is returned. EXAMPLE /* sample fragment showing how to use FindType */ VOID StubFunc (struct AppInfo *ai, STRPTR cmd, struct TagItem *tl) { STRPTR name; STRPTR argv[MAXARG], clone=NULL; ULONG argc; /* make sure we have a command line */ if (cmd) { /* parse the command line */ clone = BuildParseLine (cmd, &argc, argv); /* Get the file name. If there isn't a FILE keyword, then * use "config". If the return value is to be used outside * of this function, then it must be copied. */ name = FindType (argv, "FILE", "config"); } /* free the BuildParseLine */ FreeParseLine (clone); } INPUTS argv - Pointer to the preparsed text array. name - Entry to search for. defvalue - Value to return if name isn't found. RESULTS value - A pointer to the string that is the value bound to name or defvalue if name isn't found. SEE ALSO MatchValue(), BuildParseLine(), FreeParseLine(), ParseLine(), icon.library/FindToolType appshell.library/FreeFuncEntries appshell.library/FreeFuncEntries NAME FreeFuncEntries - Free an application's function table. SYNOPSIS FreeFuncEntries (ai) D0 struct AppInfo *ai; FUNCTION This function is used to free an application's entire function table. INPUTS ai - Pointer to the application's AppInfo structure. SEE ALSO AddFuncEntry(), AddFuncEntries(), FreeFuncEntries() appshell.library/FreeFuncEntry appshell.library/FreeFuncEntry NAME FreeFuncEntry - Free an entry from the function table SYNOPSIS FreeFuncEntry (ai, f_entry); D0 D1 struct AppInfo *ai; struct FuncEntry *f_entry; FUNCTION This function is used to free an entry from the application's function table. INPUTS ai - Pointer to the application's AppInfo structure. f_entry - Pointer to a FuncEntry structure that describes the entry to be added to the function table. SEE ALSO AddFuncEntry(), AddFuncEntries(), FreeFuncEntries() appshell.library/FreeParseLine appshell.library/FreeParseLine NAME FreeParseLine - Free the BuildParseLine temporary work area SYNOPSIS FreeParseLine(handle) D0 STRPTR handle; FUNCTION Free the temporary work space used by BuildParseLine. A NULL is a valid argument. INPUTS handle - Pointer to the return value from BuildParseLine. SEE ALSO BuildParseLine(), ParseLine() appshell.library/FreeProject appshell.library/FreeProject NAME FreeProject - Removes and deallocate a project from the project list. SYNOPSIS FreeProject ( proj ) D0 struct ProjNode *proj; FUNCTION Removes and deallocates a project node from the project list. INPUTS proj - Pointer to a valid ProjNode structure. appshell.library/FreeProjects appshell.library/FreeProjects NAME FreeProjects - Remove and deallocate all the projects in a project list. SYNOPSIS FreeProjects (ai, attrs) D0 D1 struct AppInfo *ai; struct TagItem *attrs; FUNCTION Removes and deallocate all the projects in a project list. Defaults to the main project list. Valid TagItems are: APSH_ProjInfo, Where is a valid pointer to a Project structure. Defaults to the AppInfo project structure. INPUTS ai - Pointer to the application AppInfo structure. attrs - Pointer to an optional TagItem array. appshell.library/GetFuncEntry appshell.library/GetFuncEntry NAME GetFuncEntry - Get a pointer to a function table entry. SYNOPSIS entry = GetFuncEntry (ai, cmd, fid) D0 D0 D1 A0 struct FuncEntry *entry; struct AppInfo *ai; STRPTR cmd; ULONG fid; FUNCTION This function is used to obtain a pointer to a function table entry. Currently the FuncEntry structure is private. INPUTS ai - Pointer to the application's AppInfo structure. cmd - Pointer to the command name to locate. Either cmd or fid must be provided. fid - Command ID of the command to locate. RESULT entry - Pointer to a FuncEntry structure that describes the command. SEE ALSO GetFuncID(), GetFuncName() appshell.library/GetFuncID appshell.library/GetFuncID NAME GetFuncID - Given a command name, return the ID for the function. SYNOPSIS fid = GetFuncID (ai, cmd) D0 D0 D1 ULONG fid; struct AppInfo *ai; STRPTR cmd; FUNCTION This function will return the command ID for the function. INPUTS ai - Pointer to the application's AppInfo structure. cmd - Pointer to the command name to locate. RESULT fid - Command ID of the function. SEE ALSO GetFuncEntry(), GetFuncName() appshell.library/GetFuncName appshell.library/GetFuncName NAME GetFuncName - Given a command ID, return the name of the function. SYNOPSIS cmd = GetFuncName (ai, fid) D0 D0 D1 STRPTR cmd; struct AppInfo *ai; ULONG fid; FUNCTION This function will return the name of the function for the given command ID. INPUTS ai - Pointer to the application's AppInfo structure. fid - Command ID of the function. RESULT cmd - Pointer to the command name. SEE ALSO GetFuncEntry(), GetFuncID() appshell.library/GetProjNode appshell.library/GetProjNode NAME GetProjNode - Get the requested project node. SYNOPSIS proj = GetProjNode (ai, id, attrs) D0 D0 D1 A0 struct ProjNode *proj; struct AppInfo *ai; LONG id; struct TagItem *attrs; FUNCTION Given a project ID, find the correct ProjNode. Valid TagItems are: APSH_ProjInfo, Where is a valid pointer to a Project structure. Defaults to the AppInfo project structure. INPUTS ai - Pointer to the application AppInfo structure. id - Project ID to locate. attrs - Pointer to an optional TagItem array. appshell.library/GetText appshell.library/GetText NAME GetText - Obtain a pointer to a permanent read-only text message. SYNOPSIS text = GetText(ai, base, id, def) D0 D0 D1 A0 A1 STRPTR text; struct AppInfo *ai; ULONG base, id; STRPTR def; FUNCTION Used to obtain a pointer to a permanent text message. The text return value must not be modified. The main use for this function is for setting up text labels. NOTE: The text table can not have any NULL entries, except to mark the end of the table. Due to the text table being exposed to the public (via the FAULT command), this function makes sure the number is within the valid range of the table. EXAMPLE /* sample function to show how to use GetText */ VOID StubFunc (struct AppInfo *ai, STRPTR cmd, struct TagItem *tl) { STRPTR label; /* get the current text to use for Okay */ label = GetText (ai, APSH_MAIN_ID, APSH_OKAY_TXT, NULL); } INPUTS ai - Pointer to the AppInfo structure for this application. base - Text table to use. APSH_USER_ID for the application text table. APSH_MAIN_ID for the AppShell text table. or may provide a custom message handler base ID. id - Text Table entry id. def - Must be NULL. SEE ALSO PrepText() appshell.library/HandleApp appshell.library/HandleApp NAME HandleApp - startup function for AppShell application SYNOPSIS results = HandleApp (argc, argv, wbm, attrs) D0 D0 D1 A0 A1 BOOL results; int argc; char **argv; struct WBStartup *wbm; struct TagItem *attrs; FUNCTION This function is the application entry point to the AppShell. EXAMPLE /* ... application description tags ... */ extern struct WBStartup *WBenchMsg; void main(int argc, char **argv) { HandleApp(argc, argv, WBenchMsg, tags); } INPUTS argc - Number of Shell arguments being passed. argv - Pointer to the Shell argument list wbm - Pointer to the Workbench startup message. attrs - Pointer to the application's user interface description. RESULT TRUE - Application was able to initialize and run. FALSE - Application failed. AppShell has already informed user of what and where the failure was. SEE ALSO HandleAppAsync() appshell.library/HandleAppAsync appshell.library/HandleAppAsync NAME HandleAppAsync - startup function for an asynchronous AppShell application. SYNOPSIS results = HandleAppAsync (attrs, sipc) D0 D0 D1 BOOL results; struct TagItem *attrs; struct MsgPort *sipc; FUNCTION This function is the application entry point for an asynchronous AppShell application. This function should be called via the Tool Message Handler and allows an AppShell application to have multiple projects each with their own process. Note that directly calling this function will not cause an asynchronous process to be launched. EXAMPLE /* This example shows how an application can clone itself to handle * multiple projects. * * APSH_Tool the name to give to the cloned process. * APSH_ToolData the user interface tag description. */ VOID CloneFunc(struct AppInfo *ai, STRPTR args, struct TagItem *tl) { HandlerFunc (ai, APSH_Handler, "TOOL", APSH_Command, APSH_MH_OPEN, APSH_Tool, "AppShell_Clone", APSH_ToolData, Cloned_App, TAG_DONE); } INPUTS attrs - Pointer to the application's user interface description. sipc - SIPC message port by which the master application can control the cloned application. RESULT TRUE - Application was able to initialize and run. FALSE - Application failed. AppShell has already informed user of what and where the failure was. SEE ALSO HandleApp() appshell.library/HandlerDataA appshell.library/HandlerDataA NAME HandlerDataA - Obtain a pointer to a message handlers' instance data SYNOPSIS mh = HandlerDataA (ai, attrs) D0 D0 D1 struct MsgHandler *mh; struct AppInfo *ai; struct TagItem *attrs; FUNCTION Used to obtain a pointer to a message handlers' instance data. EXAMPLE /* sample stub function to show how to obtain a message handlers' * data */ VOID StubFunc(struct AppInfo *ai, STRPTR cmd, struct TagItem *tl) { struct MsgHandler *mh; /* get a pointer to the message handler data */ if (mh = HandlerData(ai,APSH_Handler,"MYH",TAG_DONE)) { struct MHObject *mho = &(mh->mh_Header); struct myhInfo *md = mho->mho_SysData; /* do something with the data now... */ } } INPUTS ai - pointer to the AppInfo structure for this application. tags - stack based TagItems. RESULTS mh - Pointer to a MsgHandler structure. SEE ALSO HandlerFuncA() appshell.library/HandlerFuncA appshell.library/HandlerFuncA NAME HandlerFuncA - entry point for a low-level message handler function. SYNOPSIS success = HandlerFuncA (ai, attrs) D0 D0 D1 BOOL success; struct AppInfo *ai; struct TagItem *attrs; FUNCTION Provides an entry point for the low-level message handler functions. EXAMPLE /* sample stub function to show how to call a low-level message * handler function. * * This example tells the IDCMP message handler to open the window * (and it's environment) named MAIN. */ VOID StubFunc(struct AppInfo *ai, STRPTR cmd, struct TagItem *tl) { HandlerFunc(ai, APSH_Handler, "IDCMP", APSH_Command, APSH_MH_OPEN, APSH_NameTag, "MAIN", TAG_DONE); } INPUTS ai - pointer to the AppInfo structure for this application. tags - stack based TagItems. SEE ALSO HandlerDataA() appshell.library/IconFromWBArg appshell.library/IconFromWBArg NAME IconFromWBArg - Obtains the icon from a Workbench argument. SYNOPSIS dob = IconFromWBArg (wbarg) D0 D0 struct DiskObject *dob; struct WBArg *wbarg; FUNCTION Given a valid Workbench argument, this command will return the proper icon. This call uses the new (V36) GetDiskObjectNew call to ensure that an icon will be returned. INPUTS wbarg - Pointer to a filled in WBArg structure. RESULTS dob - Pointer to a DiskObject structure. Application must call FreeDiskObject when done with the icon. appshell.library/LMatchFirst appshell.library/LMatchFirst NAME LMatchFirst - Finds node that matches pattern. SYNOPSIS error = LMatchFirst(list, pat, anchor); D0 D0 D1 D2 FUNCTION Locates the first node that matches a given pattern. This function is the same as the corresponding DOS function MatchFirst except that this function operates on an Exec list instead of the file system. This set of functions is case insensitive. Set the APSHF_ANCHOR_NOCASE flag in the al_Flags field to get a caseless comparision. INPUTS list - List to search through. pat - Pattern to search for. anchor - Bookmark for the search. EXAMPLES /* sample function showing how to step through a list of * of arguments and expand wildcards, if any */ VOID StubFunc (struct AppInfo *ai, STRPTR cmd, struct TagItem *tl) { struct AppData *ad = ai->ai_UserData; struct List *list = &(ad->ad_MyList); struct AnchorList al = {NULL}; LONG retval = RETURN_ERROR; STRPTR *sptr = NULL, name; struct Funcs *fe; /* make sure that we have a tag list */ if (tl) { /* get a pointer to the function entry */ if (fe = (struct Funcs *)GetTagData(APSH_FuncEntry, NULL, tl)) { /* our first argument is a MultiArg */ sptr = (STRPTR *) fe->fe_Options[0]; } } /* make sure we have an argument array to step thru */ if (sptr) { /* step thru the argument array */ while (*sptr) { for (retval = LMatchFirst (list, *sptr, &al); retval == 0L; retval = LMatchNext (&al)) { /* get the current node name */ name = al.al_CurNode.ln_Name; /* do something with the name/node */ printf ("%s\n", name); } /* end the pattern match */ LMatchEnd (&al); /* next name/pattern */ sptr++; } /* end of while arguments */ } /* end of if arguments */ } RESULT error - 0 for success or error code from SEE ALSO LMatchNext LMatchEnd dos/MatchFirst dos/MatchNext dos/MatchEnd appshell.library/LockAppInfo appshell.library/LockAppInfo NAME LockAppInfo - Lock an application context for exclusive access. SYNOPSIS key = LockAppInfo ( ai ); D0 A1 LONG key; struct AppInfo *ai; FUNCTION This function locks an application context while the application manipulates the AppInfo structure. EXAMPLE LONG key; /* Lock the AppInfo structure for exclusive access */ key = LockAppInfo (ai); /* Modify some part of the AppInfo structure */ /* Unlock the AppInfo structure */ UnlockAppInfo (key); INPUTS ai - Pointer to a valid AppInfo structure. RETURNS key - Key to be passed to UnlockAppInfo to unlock the application context. SEE ALSO UnlockAppInfo() appshell.library/MatchValue appshell.library/MatchValue NAME MatchValue - Check a text argument for a particular flag. SYNOPSIS success = MatchValue(entry, value) D0 D0 D1 BOOL success; STRPTR entry, value; FUNCTION This function searchs to see if a particular text flag is set in a text entry. EXAMPLE /* sample fragment showing how to use MatchValue */ VOID StubFunc (struct AppInfo *ai, STRPTR cmd, struct TagItem *tl) { STRPTR flagstr; ULONG flags = NULL; STRPTR argv[MAXARG], clone=NULL; ULONG argc; /* make sure we have a command line */ if (cmd) { /* parse the command line */ clone = BuildParseLine (cmd, &argc, argv); /* get the flag entry from the argument list */ if (flagstr = FindType (argv, "FLAGS", NULL)) { /* see if the CLOSE flag is present */ if (MatchValue (flagstr, "CLOSE")) flags |= CLOSEWINDOW; /* see if the SIZE flag is present */ if (MatchValue (flagstr, "SIZE")) flags |= NEWSIZE; } } /* free the BuildParseLine */ FreeParseLine (clone); } INPUTS entry - Entry to search in. value - Value to search for. RESULTS value - TRUE if the value was in the entry, otherwise returns FALSE. SEE ALSO FindType(), BuildParseLine(), FreeParseLine(), ParseLine(), icon.library/MatchToolValue appshell.library/NewProject appshell.library/NewProject NAME NewProject - Create a project node and add it to the project list. SYNOPSIS proj = NewProject (ai, name, attrs) D0 D0 D1 A0 struct ProjNode *proj; struct AppInfo *ai; STRPTR name; struct TagItem *attrs; FUNCTION Creates a project node of the given name and adds it to the requested project list. The project list defaults to the main project list. If the name is NULL, the function will determine the name by finding the next available Unnamed slot. Valid TagItems are: APSH_ProjInfo, Where is a valid pointer to a Project structure. Defaults to the AppInfo project structure. APSH_NameTag, Where is the name to be added to the project list. APSH_TextID, Where is the text ID from the applications text table to use for the prefix when a name isn't given. Defaults to Unnamed from the AppShell text table. The resulting prefix will be truncated to twenty characters. APSH_BaseID, Where is the text table to use when APSH_TextID is supplied. Defaults to APSH_USER_ID. INPUTS ai - Pointer to the application AppInfo structure. name - Pointer to the name to give to the project. attrs - Pointer to an optional TagItem array. RESULT proj - Pointer to a filled in ProjNode structure appshell.library/NotifyUser appshell.library/NotifyUser NAME NotifyUser - Display a text message to the user. SYNOPSIS success = NotifyUser (ai, msg, attrs) D0 D0 D1 A0 BOOL success; struct AppInfo * ai; STRPTR msg; struct TagItem * attrs; FUNCTION This function will display a text message to the user. Currently uses EasyRequest (AutoRequest if OS version less than 2.0) to display messages. INPUTS ai - Optional pointer to the AppInfo structure for this application. msg - Pointer to message to display. If this field is NULL, then the text will come from the ai->ai_TextRtn field. attrs - Optional pointer to an array of TagItems. appshell.library/ParseLine appshell.library/ParseLine NAME ParseLine - Destructive string parser SYNOPSIS argc = ParseLine (line, argv) D0 D0 D1 ULONG argc; STRPTR line; STRPTR argv[MAXARGS]; FUNCTION String parser. Inserts '\0' after each word in the passed text line. INPUTS line - Pointer to the string to parse. argv - Pointer to an array to hold the arguments. The array must contain MAXARGS entries. RETURN argc - Number of arguments returned in argv EXAMPLE /* sample function showing how to use ParseLine */ VOID StubFunc (struct AppInfo *ai, STRPTR cmd, struct TagItem *tl) { UBYTE text[] = "ACTIVATE ME"; STRPTR argv[MAXARGS]; ULONG argc; /* parse the command line */ argc = ParseLine (text, argv); /* simple display of some of the parse variables */ printf("%ld words, first is %s\n", argc, argv[0]); } SEE ALSO BuildParseLine(), FreeParseLine() appshell.library/PerfFunc appshell.library/PerfFunc NAME PerfFunc - The entry point to all commands in the function table. SYNOPSIS success = PerfFunc (ai, fid, cmdline, attrs) D0 D0 D1 A0 A1 BOOL success; struct AppInfo *ai; ULONG fid; STRPTR cmdline; struct TagItem *attrs; FUNCTION This is the main and only entry point for all commands in the function table. In order to respect state, such as whether the function is enabled or disabled, function table commands should never be called directly. If the function isn't in the function table and the ARexx message handler has been initialized, then the command is passed to ARexx. EXAMPLE /* how to call a function using its ID */ PerfFunc (ai, QuitID, NULL, NULL); /* how to call a function using its name */ PerfFunc (ai, NULL, "QUIT", NULL); INPUTS ai - Pointer to the AppInfo structure fid - ID of function to perform. cmdline - Pointer to the text command line to use to trigger the command. attrs - Pointer to the TagItem array to use to triggered the command. RESULT success - Returns TRUE if the function was performed, FALSE if it didn't. appshell.library/PrepText appshell.library/PrepText NAME PrepText - Obtain a pointer to a temporarily modifiable text message. SYNOPSIS text = PrepText(ai, base, id, args, ...) D0 D0 D1 A0 A1 STRPTR text; struct AppInfo *ai; ULONG base, id; int args; FUNCTION Build a temporary text message using a text table entry and the passed arguments. The text table entry must contain valid RawDoFmt formatting commands. The text pointer is only valid until the next call to PrepText. There is one PrepText buffer per AppInfo, so each cloned AppShell has its own work buffer. The string must be copied to a more permanent storage place if you wish to keep it for a longer period. The main use for this function is for formatting of temporary error messages. EXAMPLE /* set up error return values */ ai->ai_Pri_Ret = RETURN_FAIL; ai->ai_Sec_Ret = APSH_PORT_ACTIVE; /* "%s port already active", pname */ ai->ai_TextRtn = PrepText(ai, APSH_MAIN_ID, ai->ai_Sec_Ret, pname); INPUTS ai - Pointer to the AppInfo structure for this application. base - Text table to use. APSH_USER_ID for the application text table. APSH_MAIN_ID for the AppShell text table. or may provide a custom message handler base ID. id - Text Table entry id. args - Variables to be sprintf'ed into the text entry. SEE ALSO GetText() appshell.library/QStrCmpI appshell.library/QStrCmpI NAME QStrCmpI - Quick case insensitive string comparision. SYNOPSIS success = QStrCmpI (str1, str2) D0 D0 D1 BOOL value; STRPTR str1, str2; FUNCTION This function performs a quick, case insensitive, string comparision. Stops as soon as it determines that the strings are not the same. EXAMPLE /* sample code fragment showing how to use QStrCmpI */ VOID StubFunc (struct AppInfo *ai, STRPTR cmd, struct TagItem *tl) { STRPTR name; STRPTR argv[MAXARG], clone=NULL; ULONG argc; /* make sure we have a command line */ if (cmd) { /* parse the command line */ clone = BuildParseLine (cmd, &argc, argv); /* make sure we have some arguments */ if (argc >= 2L) { /* check to see if the first argument is CLOSE. * Note that FindType(argv, "CLOSE", NULL) could also be * used in this example. */ if (QStrCmpI (argv[1], "CLOSE")) { /* do something because of CLOSE */ } } } /* free the BuildParseLine */ FreeParseLine (clone); } INPUTS str1 - Pointer to the first string. str2 - Pointer to the second string. RESULTS value - TRUE if the strings are the same, otherwise returns FALSE. appshell.library/RemoveMsgPort appshell.library/RemoveMsgPort NAME RemoveMsgPort - Safely remove a message port. SYNOPSIS RemoveMsgPort (mp) D0 struct MsgPort *mp; FUNCTION This function will remove and reply to all messages that are outstanding on a message port before removing the port itself. NULL is a valid argument. INPUTS mp - A pointer to the message port to delete. appshell.library/RemoveProject appshell.library/RemoveProject NAME RemoveProject - Remove a project node from the project list. SYNOPSIS success = RemoveProject (ai, name, attrs) D0 D0 D1 A0 BOOL success; struct AppInfo *ai; STRPTR name; struct TagItem *attrs; FUNCTION Removes a project node of the given name from the requested project list. Defaults to removing the current project node from the main project list. Valid TagItems are: APSH_ProjInfo, Where is a valid pointer to a Project structure. Defaults to the AppInfo project structure. APSH_NameTag, Where is a valid project name to be removed. INPUTS ai - Pointer to the application AppInfo structure. name - Pointer to the name of the project to be removed. attrs - Pointer to an optional TagItem array. RESULT TRUE - Able to remove the project from the list. FALSE - Unable to remove the project. BUGS name is not currently implemented. Just removes the current project. appshell.library/RenumProject appshell.library/RenumProject NAME RenumProject - Renumber the project list. SYNOPSIS RenumProject (ai, cmd, attrs) D0 D1 A0 struct AppInfo *ai; STRPTR cmd; struct TagItem *attrs; FUNCTION Renumbers the project list. Valid TagItems are: APSH_ProjInfo, Where is a valid pointer to a Project structure. Defaults to the AppInfo project structure. INPUTS ai - Pointer to the application AppInfo structure. cmd - Pointer to the command string. attrs - Pointer to the TagItem array. appshell.library/setup_arexxA appshell.library/setup_arexxA NAME setup_arexxA - Initializes the ARexx message handler. SYNOPSIS mh = setup_arexxA (ai, tags) D0 D0 D1 struct MsgHandler *mh; struct AppInfo *ai; struct TagItem *tags; FUNCTION This is the low-level function used to initialize the ARexx message hander. NOTE: This call should not be called directly by the application, but should invoked by using the APSH_AddARexx_UI tag. Valid tagitems to use at INITIALIZATION are: APSH_ARexxError, ID of the function to call whenever an ARexx message returns with an error. APSH_ARexxOK, ID of the function to call whenever an ARexx message returns successfully. APSH_Extens, Used to specify the default macro file extension to use. Defaults to .REXX APSH_Port, Used to specify a name for the ARexx port. Defaults to APSH_BaseName. APSH_Status, Where flags can be: APSHP_INACTIVE When set, then the ARexx port will be initialized, but will fail all messages received. APSHP_SINGLE When set, will not add a use count to the end of the ARexx port name. In addition to the standard message handler functions, the ARexx function handler provides the following functions: AH_SENDCMD Send a command to ARexx. EXAMPLE /* To send an command to ARexx */ struct MsgHandler *mh; STRPTR cmd; cmd = "\"ADDRESS COMMAND DIR\""; /* Get a pointer to the ARexx message handler */ if (mh = HandlerData (ai, APSH_Handler, "AREXX", TAG_DONE)) { /* Send the command to ARexx */ retval = HandlerFunc (ai, APSH_Handler, "AREXX", APSH_Command, AH_SENDCMD, APSH_CmdString, cmd, TAG_DONE); } INPUTS ai - Pointer to the application's AppInfo structure. tags - Pointer to an array of TagItem attributes for the function. RESULT mh - Pointer to a MsgHandler structure. SEE ALSO appshell.library/setup_dosA appshell.library/setup_dosA NAME setup_dosA - Initializes the Command Shell message handler. SYNOPSIS mh = setup_dosA (ai, attrs) D0 D0 D1 struct MsgHandler *mh; struct AppInfo *ai; struct TagItem *attrs; FUNCTION This is the low-level function used to initialize the Command Shell message handler. NOTE: This call should not be called directly by the application, but should invoked by using the APSH_AddCmdShell_UI tag. Valid tagitems to use at INITIALIZATION are: APSH_Status, Where flags can be: APSHP_INACTIVE When set, then the command shell will be initialized, but will remain closed until opened explicitly by the user. APSH_CloseMsg, Text ID of the message displayed when attempting to close the command shell. Defaults to "Waiting for macro return". APSH_CMDWindow, Text ID of the console window spec. A reasonable default spec is provided. APSH_Prompt, Text ID of the text to used for a prompt. "Cmd> " is the default prompt. APSH_CMDTitle Used to specify the text ID of title for the Command Shell. Defaults to Command Shell. APSH_ParentWindow APSH_CMDParent (obsolete, don't use). Used to specify the text ID the parent window of the Command Shell. Should be the main project window of the application. Using this tag helps the AppShell keep the Command Shell near the application when the user is using a virtual screen. Not fully implemented yet. INPUTS ai - Pointer to the application's AppInfo structure. attrs - Pointer to an array of TagItem attributes for the function. RESULT mh - Pointer to a MsgHandler structure. SEE ALSO appshell.library/setup_idcmpA appshell.library/setup_idcmpA NAME setup_idcmpA - Initializes the Intuition message handler. SYNOPSIS mh = setup_idcmpA (ai, attrs) D0 D0 D1 struct MsgHandler *mh; struct AppInfo *ai; struct TagItem *attrs; FUNCTION This is the low-level function used to initialize the Intuition, or GUI, message handler. NOTE: This call should not be called directly by the application, but should invoked by using the APSH_AddIntui_UI tag. Valid tagitems to use at INITIALIZATION are: APSH_Status, Where flags can be: APSHP_INACTIVE When set, then the window environment, that is passed in with the initialization tags, will be not be initialized. The following tags allow the programmer to specify a function to be executed whenever the corresponding IDCMP event occurs. APSH_SizeVerify, APSH_NewSize, APSH_RefreshWindow, APSH_MouseButtons, APSH_ReqSet, APSH_CloseWindow, APSH_ReqVerify, APSH_ReqClear, APSH_MenuVerify, APSH_DiskInserted, APSH_DiskRemoved, APSH_ActiveWindow, APSH_InactiveWindow, APSH_IntuiTicks, APSH_MouseMove, APSH_WinBOpen, Function to execute before opening a window. APSH_WinAOpen, Function to execute after opening a window. APSH_WinBClose, Function to execute before closing a window. APSH_WinAClose, Function to execute after closing a window. APSH_RefreshData, Function to execute whenever the data for gadgets needs refreshing. Because GadTools doesn't support relative gadgets, the AppShell has to free the gadgets and build new ones whenever the user resizes a sizeable window. INPUTS ai - Pointer to the application's AppInfo structure. attrs - Pointer to an array of TagItem attributes for the function. RESULT mh - Pointer to a MsgHandler structure. SEE ALSO appshell.library/setup_notifyA appshell.library/setup_notifyA NAME setup_notifyA - Initializes the notification message handler. SYNOPSIS mh = setup_notifyA (ai, attrs) D0 D0 D1 struct MsgHandler *mh; struct AppInfo *ai; struct TagItem *attrs; FUNCTION This is the low-level function used to initialize the file notification message handler. This handler is responsible for dispatching events when marked files are modified. NOTE: This call should not be called directly by the application, but is automatically initialized by all AppShell applications. Valid tagitems to use at OPEN time: APSH_NameTag, Complete file name of file to watch. APSH_CmdID, Function to execute when file is modified. Examine APSH_NameTag to get the name of the file modified. NOTES This handler is used by the AppShell to automatically handle preference files, with notification, for the application. When the application closes, all notification events will be automatically terminated. EXAMPLE /* Start notification on a file */ VOID WatchClipFile (struct AppInfo *ai, STRPTR cmd, struct TagItem *attrs) { /* Start the notification */ HandlerFunc (ai, APSH_Handler, "NOTIFY", APSH_Command, APSH_MH_OPEN, APSH_NameTag, "ram:temp", APSH_CmdID, ClipFileChangeID, TAG_DONE); } INPUTS ai - Pointer to the application's AppInfo structure. attrs - Pointer to an array of TagItem attributes for the function. RESULT mh - Pointer to a MsgHandler structure. SEE ALSO appshell.library/setup_sipcA appshell.library/setup_sipcA NAME setup_sipcA - Initializes the SIPC message handler. SYNOPSIS mh = setup_sipcA (ai, attrs) D0 D0 D1 struct MsgHandler *mh; struct AppInfo *ai; struct TagItem *attrs; FUNCTION This is the low-level function used to initialize the Simple InterProcess Communications message handler. NOTE: This call should not be called directly by the application, but should invoked by using the APSH_AddSIPC_UI tag. Valid tagitems to use at INITIALIZATION are: APSH_Port, Used to specify a name for the SIPC port. Defaults to APSH_BaseName plus _SIPC. APSH_Status, Where flags can be: APSHP_INACTIVE When set, then the port will be initialized, but will fail all messages received. APSHP_SINGLE When set, will not add a use count to the end of the message port name. APSH_SIPCOK, Function to execute when a SIPC message returns successfully. APSH_SIPCError, Function to execute when a SIPC message returns with an error. APSH_AlreadyRunning, Function to execute if port (when APSHP_SINGLE specified) already exists. In addition to the standard message handler functions, the SIPC function handler provides the following functions: AH_SENDCMD Send a command to another AppShell application. This function understands the following tags: APSH_NameTag, Name of the destination SIPC message port. APSH_PortAddr, Address of the destination SIPC message port. APSH_CmdID, Function ID for the destination application to invoke. APSH_CmdData, Information to send to the destination application. Data can be a tag list or a block of data. APSH_CmdDataLength, This is used to indicate a block of data. APSH_CmdString, This is used to send a command string to another application. EXAMPLE STRPTR port_name; struct MsgPort *mp; struct TagItem *attr_list; LONG data; LONG data_len; /* To send a command string to another AppShell application */ HandlerFunc (ai, APSH_Handler, "SIPC", APSH_Command, AH_SENDCMD, APSH_NameTag, port_name, APSH_CmdString, "window front activate", TAG_DONE); /* To call a function with tags */ HandlerFunc (ai, APSH_Handler, "SIPC", APSH_Command, AH_SENDCMD, APSH_PortAddr, port_addr, APSH_CmdID, OpenID, APSH_CmdData, attr_list, TAG_DONE); /* To send a block of a data */ HandlerFunc (ai, APSH_Handler, "SIPC", APSH_Command, AH_SENDCMD, APSH_PortAddr, ad->ad_ProjSIPC, APSH_CmdID, SendDataID, APSH_CmdData, data, APSH_CmdDataLength, data_len, TAG_DONE); INPUTS ai - Pointer to the application's AppInfo structure. attrs - Pointer to an array of TagItem attributes for the function. RESULT mh - Pointer to a MsgHandler structure. SEE ALSO appshell.library/setup_toolA appshell.library/setup_toolA NAME setup_toolA - Initializes the tool message handler. SYNOPSIS mh = setup_toolA (ai, attrs) D0 D0 D1 struct MsgHandler *mh; struct AppInfo *ai; struct TagItem *attrs; FUNCTION This is the low-level function used to initialize the tool message handler. This message handler is responsible for maintaining the initialization & shutdown of asynchronous processes within an application. NOTE: This call should not be called directly by the application, but should invoked by using the APSH_AddTool_UI tag. Valid tagitems to use at OPEN time: APSH_Tool, Name to give to the process that is spawned. Required. APSH_ToolData, Data to pass to the new process. Passes a pointer to the AppInfo structure as default. If you are starting a new AppShell application, then a tag list should be passed. APSH_ToolAddr, Pointer to the function to spawn as a new process. Defaults to HandleAppAsync. APSH_ToolStack, Stack size to allocate for the new process. Defaults to 4096 bytes. APSH_ToolPri, Priority to run the new process at. Defaults to zero. EXAMPLE /* Start a project as a new process */ VOID NewProject (struct AppInfo *ai, STRPTR cmd, struct TagItem *attrs) { extern struct TagItem Cloned_App[]; struct MsgHandler *mh; struct TagItem *tag; /* Search for the tag to store our SIPC address in */ if (tag = FindTagItem (APSH_PortAddr, Cloned_App)) { /* See if we have a SIPC port */ if (mh = HandlerData (ai, APSH_Handler, "SIPC", TAG_DONE)) { /* Get the address of our SIPC port */ tag->ti_Data = (ULONG) mh->mh_Port; } } /* Start the new process */ HandlerFunc (ai, APSH_Handler, "TOOL", APSH_Command, APSH_MH_OPEN, APSH_Tool, "MiniBuild_Project", APSH_ToolData, Cloned_App, TAG_DONE); } INPUTS ai - Pointer to the application's AppInfo structure. attrs - Pointer to an array of TagItem attributes for the function. RESULT mh - Pointer to a MsgHandler structure. SEE ALSO appshell.library/setup_wbA appshell.library/setup_wbA NAME setup_wbA - Initialize the Workbench message handler. SYNOPSIS mh = setup_wbA (ai, tags) D0 D0 D1 struct MsgHandler *mh; struct AppInfo *ai; struct TagItem *tags; FUNCTION This is the low-level Workbench message handler function used to initialize the Workbench message hander. This handles the AppIcon, AppWindow and AppMenuItem features of Workbench. NOTE: This call should not be called directly by the application, but should invoked by using the APSH_AddWB_UI tag. Valid tagitems to use at INITIALIZATION are: APSH_Status, Where flags can be APSHP_INACTIVE or NULL. Any of the OPEN tags can be used to make a Workbench object active immediately. Valid tagitems to use at OPEN are: These tags are used when adding a new entry to the Workbench message handler object list. APSH_AppWindowEnv, Where is a tag array that describes the AppWindow to add. APSH_AppIconEnv, Not implemented. APSH_AppMenuEnv, Not implemented. These tags are used to specify functions for a new entry in the Workbench message handler object list. APSH_AppOpen, Function to call after the object is opened, whenever it is opened. APSH_AppBDrop, Function to call when an AppMessage is received, before any further processing. APSH_AppDDrop, Function to call for each WBArg in an AppMessage argument list. The APSH_WBF_NOLIST must be set for this function to be called. APSH_AppADrop, Function to call after the AppMessage has been processed. APSH_AppClose, Function to call before closing a Workbench message handler object. APSH_AppRemove, Function to call before removing a Workbench message handler object. APSH_AppDblClick, Function to call when an AppIcon has been double-clicked. INPUTS ai - Pointer to the application's AppInfo structure. tags - Pointer to an array of TagItem attributes for the function. RESULT mh - Pointer to a MsgHandler structure. SEE ALSO appshell.library/SwapProjNodes appshell.library/SwapProjNodes NAME SwapProjNodes - Swap two project nodes within the same Project list. SYNOPSIS SwapProjNodes (ai, pn1, pn2, attrs) D0 D1 A0 A1 struct AppInfo *ai; struct ProjNode *pn1; struct ProjNode *pn2; struct TagItem *attrs; FUNCTION This function will swap two project nodes within the same project list. Valid TagItems are: APSH_ProjInfo, Where is a valid pointer to a Project structure. Defaults to the AppInfo project structure. INPUTS ai - Pointer to the application AppInfo structure. pn1 - Pointer to a valid ProjNode structure. pn2 - Pointer to a valid ProjNode structure. attrs - Pointer to an optional TagItem array. appshell.library/UnlockAppInfo appshell.library/UnlockAppInfo NAME UnlockAppInfo - Unlock a locked application context. SYNOPSIS UnlockAppInfo ( key ); D0 LONG key; FUNCTION This functions unlocks a locked application context. INPUTS key - Key returned by LockAppInfo. SEE ALSO LockAppInfo()