The Desk Manager - Apple IIgs Toolbox Ref. Information
                                                                            
Index

    Housekeeping Routines
    
     DeskBootInit
     DeskStartUp
     DeskShutDown
     DeskVersion
     DeskReset
     DeskStatus
     
    Installation Routines
    
     InstallNDA
     InstallCDA
     RemoveCDA
     RemoveNDA
     
    CDA Routines
    
     ChooseCDA
     SetDAStrPtr
     GetDAStrPtr
     
     
     
    Run Queue Routines
    
     AddToRunQ
     RemoveFromRunQ
     
    NDA Routines
    
     OpenNDA
     CloseNDA
     CloseNDAbyWinPtr
     CloseAllNDAs
     FixAppleMenu
     GetNumNDAs
     SystemClick
     SystemEdit
     SystemTask
     SystemEvent
     
     
     
    General DA Routines
    
     CallDeskAcc
     GetDeskAccInfo
     GetDeskGlobal
     
     
     
    State-saving Routines
    
     SaveScrn
     RestScrn
     SaveAll
     RestAll
     
    Constants
    
    Error Codes
    
   
     _________________________________________________________________
   
   
   
$0105

DeskBootInit

   Initializes the Desk Manager; called only by the Tool Locator when the
   tool set is initially loaded into memory.
   
    Warning
    
   An application must never make this call.
   
  Parameters
  
   There are no input or output parameters.
   
  Errors
  
   None
   
  C
  
   You shouldn't call this function.
   _________________________________________________________________
   
$0205

DeskStartUp

   Starts up the Desk Manager for use by an application. An application
   must call this if it wants to support desk accessories.
   
  Parameters
  
   There are no input or output parameters.
   
  Errors
  
   None
   
  C
  
   extern pascal void DeskStartUp(void)
   _________________________________________________________________
   
$0305

DeskShutDown

   Shuts down the Desk Manager. If you start up the Desk Manager, you
   must shut it down before your program exits.
   
  Parameters
  
   There are no input or output parameters.
   
  Errors
  
   None
   
  C
  
   extern pascal void DeskShutDown(void)
   _________________________________________________________________
   
$0405

DeskVersion

   Returns the version of the Desk Manager.
   
  Parameters
  
  Input:
  
   wordspace Word -- Space for result
   
  Output:
  
   versionInfo Word -- Version number of the Desk Manager
   
  Errors
  
   None
   
  C
  
   extern pascal Word DeskVersion(void)
   _________________________________________________________________
   
$0505

DeskReset

   Resets the Desk Manager; called only by the Tool Locator when the
   system is reset.
   
    Warning
    
   An application must never make this call.
   
  Parameters
  
   There are no input or output parameters.
   
  Errors
  
   None
   
  C
  
   You shouldn't call this function.
   _________________________________________________________________
   
$0605

DeskStatus

   Indicates whether or not the Desk Manager is active.
   
  Parameters
  
  Input:
  
   wordspace Word -- Space for result
   
  Output:
  
   activeFlag Word -- TRUE if Desk Manager is active, FALSE if not.
   
  Errors
  
   None
   
  C
  
   extern pascal Word DeskStatus(void)
   _________________________________________________________________
   
$1F05

AddToRunQ

   Adds the specified routine to the head of the run queue.
   
  Parameters
  
  Input:
  
   runItemPtr Long -- Pointer to the run item to add.
   
  Errors
  
   None
   
  C
  
   extern pascal void AddToRunQ(Pointer runItemPtr)
   _________________________________________________________________
   
$2405

CallDeskAcc

   Calls an NDA's Action or Initialization routine. You can specify which
   NDA to call by either index number or window pointer (for open NDAs).
   
   Since GetNumNDAs always returns the ID number of the most recently
   installed NDA, you can use pass that value into CallDeskAcc to call a
   newly-installed NDA.
   
    Warning
    
   Don't call NDAs that aren't open.
   
  Parameters
  
  Input:
  
   wordspace Word -- Space for result.
   flags Word -- Flags, described below.
   daReference Long -- Specifies which NDA to call.
   action Word -- Action code to pass to NDA.
   data Long -- Data value to pass to NDA.
   
  Output:
  
   result Word -- Result returned from NDA.
   
  Errors
  
   $0520 deskBadSelector Invalid desk accessory selector.
   
  C
  
   extern pascal Word CallDeskAcc(Word flags, LongWord daReference, Word
   action, Long data)
   
   flags
   bit 15: 0 = Call an NDA; 1 = Call a CDA (not implemented)
   bits 14-2: Reserve;set to 0.
   bit 1: 1 = Call the NDA's Initialization routine; 0 = call the NDA's
   Action routine.
   bit 0: 1 = daReference is a window pointer; 0 = daReference is an
   index number.
   daReference Either a window pointer to an open system window, or an
   index number (between 1 and GetNumNDAs), depending on bit 0 of flags.
   action
   
   The value to pass in the accumulator when the NDA is called. If bit 1
   of flags is clear.
   
   Action codes greater than 9 only get sent to the NDA if its event mask
   is $Axxx. If a value greater than 9 is passed and the event mask isn't
   $Axxx, error $0520 is returned.
   data Value to pass to the NDA in the X and Y registers. The high word
   is passed in X, and the low word in Y.
   _________________________________________________________________
   
$1105

ChooseCDA

   Activates the Desk Manager's CDA menu, just as if the
   Control-Apple-ESC key combination were pressed.
   
    Warning
    
   An application must never make this call.
   
  Parameters
  
   There are no input or output parameters.
   
  Errors
  
   None
   
  C
  
   You shouldn't call this function.
   _________________________________________________________________
   
$1D05

CloseAllNDAs

   Closes all NDAs that are currently open.
   
  Parameters
  
   There are no input or output parameters.
   
  Errors
  
   None
   
  C
  
   extern pascal void CloseAllNDAs(void)
   _________________________________________________________________
   
$1605

CloseNDA

   Closes the specified NDA. This is normally done for you automatically
   by the SystemClick routine.
   
  Parameters
  
  Input:
  
   refNum Word -- NDA refNum as returned by OpenNDA routine.
   
  Errors
  
   None
   
  C
  
   extern pascal void CloseNDA(Word refNum)
   _________________________________________________________________
   
$1C05

CloseNDAbyWinPtr

   Closes the NDA whose window pointer matches the specified pointer. The
   most common use for this function is when your application's Close
   menu item is chosen and the frontmost window is not an application
   window (ie, it belongs to an NDA). In this case, you can pass the
   window pointer to this function to close the NDA.
   
  Parameters
  
  Input:
  
   windowPtr Long -- Pointer to the window to close.
   
  Errors
  
   $0510 daNotFound Specified DA not available.
   $0511 notSysWindow Window pointer is not a pointer to an NDA window.
   
  C
  
   extern pascal void CloseNDAbyWinPtr(WindowPtr windowPtr)
   _________________________________________________________________
   
$1E05

FixAppleMenu

   Adds the names of the installed NDAs to a specified menu, usually the
   Apple menu. The first NDA installed is given the menu ID 1, the second
   is given the ID 2, and so forth.
   
  Parameters
  
  Input:
  
   menuID Word -- Menu in which the NDAs should be installed.
   
  Errors
  
   None
   
  C
  
   extern pascal void FixAppleMenu(Word menuID)
   _________________________________________________________________
   
$1405

GetDAStrPtr

   Returns the pointer to the table of strings that comprise the built-in
   CDA names.
   
  Parameters
  
  Input:
  
   longspace Long -- Space for result
   
  Output:
  
   stringTablePtr Long -- Pointer to table of strings for the built-in
   CDA names.
   
  Errors
  
   None
   
  C
  
   extern pascal Pointer GetDAStrPtr(void)
   _________________________________________________________________
   
$2305

GetDeskAccInfo

   Lets you get safe access to some information about a desk accessory.
   
  Parameters
  
  Input:
  
   flags Word -- Flags, described below.
   daReference Long -- Specifies which NDA to call.
   buffSize Word -- Size of the result buffer.
   bufferPtr Long -- Pointer to the result buffer.
   
  Errors
  
   $0520 deskBadSelector Invalid desk accessory selector.
   
  C
  
   extern pascal void GetDeskAccInfo(Word flags, LongWord daReference,
   Word buffSize, Pointer bufferPtr)
   
   flags
   bit 15: 1 = Get information about a CDA; 0 = Get information about an
   NDA.
   bits 14-1: Reserve;set to 0.
   bit 0: 1 = daReference is a window pointer; 0 = daReference is an
   index number.
   daReference Either a window pointer to an open system window, or an
   index number (between 1 and GetNumNDAs), depending on bit 0 of flags.
   buffSize Number of bytes the result buffer can hold, not including the
   first two bytes. For information on a CDA, buffSize must be at least
   4.
   bufferPtr
   
   Pointer to a result buffer. For CDAs, the buffer has this format:
   
   $00 size Word -- Returned data size
   $02 theHandle Long -- Handle to the CDA
   
   For NDAs, the buffer is formatted as follows:
   
   $00 size Word -- Returned data size
   $02 status Word -- 0 if closed, non-zero if open
   $04 openPtr Long -- Pointer to the NDA's Open routine
   $08 closePtr Long -- Pointer to the NDA's Close routine
   $0C actionPtr Long -- Pointer to the NDA's Action routine
   $10 initPtr Long -- Pointer to the NDA's Initialization routine
   $14 period Word -- NDA's period
   $16 eventMask Word -- NDA's event mask
   $18 tickCount Long -- Tick count for the last Run event sent to the
   NDA
   $1C windowPtr Long -- Pointer to the NDA's main window; NIL if none
   $20 theHandle Long -- Handle to the NDA
   $24 userID Word -- NDA's user ID.
   _________________________________________________________________
   
$2505

GetDeskGlobal

   Retreives information from the Desk Manager.
   
   Selector $0000 (the only value currently defined) returns the pointer
   to the last window examined by the Desk Manager. This should be used
   inside NDA-style procedures called by the Desk Manager to determine
   which window is being handled. This lets the same NDA-style procedure
   be used to handle multiple system windows.
   
  Parameters
  
  Input:
  
   wordspace Long -- Space for result
   selector Word -- Selects which value to retrieve
   
  Output:
  
   value Long -- The selected value
   
  Errors
  
   $0520 deskBadSelector Selector out of range.
   
  C
  
   extern pascal LongWord GetDeskGlobal(Word selector)
   _________________________________________________________________
   
$1B05

GetNumNDAs

   Returns the number of NDAs currently installed.
   
  Parameters
  
  Input:
  
   wordspace Word -- Space for result
   
  Output:
  
   ndaCount Word -- The number of NDAs installed.
   
  Errors
  
   None
   
  C
  
   extern pascal Word GetNumNDAs(void)
   _________________________________________________________________
   
$0F05

InstallCDA

   Installs a CDA into the system. This routine is normally used only by
   GS/OS when the system is started up, to initially install CDAs into
   the system's CDA menu; however, you can call this function if you want
   to add CDAs later.
   
   For more information on how this works, see the Apple IIgs Toolbox
   Reference, Volume 1, page 5-3.
   
  Parameters
  
  Input:
  
   cdaHandle Long -- Handle of memory containing the CDA.
   
  Errors
  
   None
   
  C
  
   extern pascal void InstallCDA(Handle cdaHandle)
   _________________________________________________________________
   
$0E05

InstallNDA

   Installs an NDA into the system. This routine is normally used only by
   GS/OS when the system is started up; however, you can call this
   function if you want to add NDAs later.
   
   For more information on how this works, see the Apple IIgs Toolbox
   Reference, Volume 1, page 5-6.
   
  Parameters
  
  Input:
  
   ndaHandle Long -- Handle of memory containing the NDA.
   
  Errors
  
   None
   
  C
  
   extern pascal void InstallNDA(Handle ndaHandle)
   _________________________________________________________________
   
$1505

OpenNDA

   Opens the specified NDA. The specified ID number is the menu ID of the
   NDA.
   
   If your application uses TaskMaster, you don't need to call this
   function.
   
   Otherwise, you should call this function when the user selects an NDA
   from the Apple menu.
   
  Parameters
  
  Input:
  
   wordspace Word -- Space for result
   idNum Word -- ID number of the NDA's menu item
   
  Output:
  
   refNum Word -- Reference number to pass to CloseNDA.
   
  Errors
  
   $0510 daNotFound Specified DA not available.
   
  C
  
   extern pascal Word OpenNDA(Word idNum)
   _________________________________________________________________
   
$2105

RemoveCDA

   Removes the specified CDA from the system. Does not dispose of the
   memory occupied by the CDA.
   
   Be careful using this call. If the CDA has added a procedure to the
   run queue or the HeartBeat task queue (for example), removing the CDA
   could cause problems if you don't remove those as well.
   
  Parameters
  
  Input:
  
   cdaHandle Long -- Handle to the CDA to remove.
   
  Errors
  
   $0510 daNotFound Specified DA not available.
   
  C
  
   extern pascal void RemoveCDA(Handle cdaHandle)
   _________________________________________________________________
   
$2005

RemoveFromRunQ

   Removes the specified run item from the run queue.
   
  Parameters
  
  Input:
  
   runItemPtr Long -- Pointer to the run item to remove.
   
  Errors
  
   None
   
  C
  
   extern pascal void RemoveFromRunQ(Pointer runItemPtr)
   _________________________________________________________________
   
$2205

RemoveNDA

   Removes the specified NDA from the system. Doesn't dispose of the
   memory occupied by the NDA.
   
   The Apple menu is not rebuilt by this call; you should call
   FixAppleMenu after this call.
   
  Parameters
  
  Input:
  
   ndaHandle Long -- Handle to the NDA to remove.
   
  Errors
  
   $0510 daNotFound Specified DA not available.
   
  C
  
   extern pascal void RemoveNDA(Handle ndaHandle)
   _________________________________________________________________
   
$0C05

RestAll

   Restores all the variables saved when the CDA menu is activated.
   
    Warning
    
   An application must never make this call.
   
  Parameters
  
   There are no input or output parameters.
   
  Errors
  
   None
   
  C
  
   You shouldn't call this function.
   _________________________________________________________________
   
$0A05

RestScrn

   Restores the screen area saved by the Desk Manager, including both the
   text screen itself and the screen holes.
   
    Warning
    
   An application must never make this call.
   
  Parameters
  
   There are no input or output parameters.
   
  Errors
  
   None
   
  C
  
   You shouldn't call this function.
   _________________________________________________________________
   
$0B05

SaveAll

   Saves all the variables that the Desk Manager preserves when the CDA
   menu is activated, then sets the text screen to either 40 or 80
   columns, depending on the Control Panel setting for the text display.
   
    Warning
    
   An application must never make this call.
   
  Parameters
  
   There are no input or output parameters.
   
  Errors
  
   None
   
  C
  
   You shouldn't call this function.
   _________________________________________________________________
   
$0905

SaveScrn

   Saves the 80-column text screen in banks $00, $01, $E0, and $E1. This
   image of the screen is used to restore the display for subsequent
   calls to RestScrn. The entire screen and all screen holes are
   preserved.
   
    Warning
    
   An application must never make this call.
   
  Parameters
  
   There are no input or output parameters.
   
  Errors
  
   None
   
  C
  
   You shouldn't call this function.
   _________________________________________________________________
   
$1305

SetDAStrPtr

   Changes the names of the built-in CDAs. This routine can be used to
   localize the names of these desk accessories.
   
   See page 5-24 of the Apple IIgs Toolbox Reference, Volume 1 for more
   information.
   
  Parameters
  
  Input:
  
   altDispHandle Long -- Handle to the new Alternate Display Mode desk
   accessory.
   stringTablePtr Long -- Pointer to table of strings.
   
  Errors
  
   None
   
  C
  
   extern pascal void InstallNDA(Handle ndaHandle)
   _________________________________________________________________
   
$1705

SystemClick

   Handles mouse-down events in the size, drag, zoom, and close boxes of
   NDAs. Your application should call this function whenever it detects a
   mouse-down event in a system window.
   
   If you're using TaskMaster, you don't have to call this function.
   
   If the window isn't active and the event is in the content area,
   information bar, frame, or frame scroll bars of the window,
   SystemClick makes the window active. If it's already active, this
   function passes the event along to the NDA.
   
  Parameters
  
  Input:
  
   eventRecPtr Long -- Pointer to event record.
   windowPtr Long -- Pointer to the system window.
   findWindowResult Word -- Result of the FindWindow call.
   
  Errors
  
   None
   
  C
  
   extern pascal void SystemClick(EventRecordPtr eventRecPtr, WindowPtr
   windowPtr, Word findWindowResult)
   _________________________________________________________________
   
$1805

SystemEdit

   Passes standard Edit menu commands to system windows. The valid edit
   types are:
   
   1 undo
   2 cut
   3 copy
   4 paste
   5 clear
   
  Parameters
  
  Input:
  
   wordspace Word -- Space for result.
   editType Word -- Edit type.
   
  Output:
  
   processedFlag Word -- TRUE if frontmost window is a system window and
   desk accessory has to handle the call, FALSE otherwise.
   
  Errors
  
   None
   
  C
  
   extern pascal Boolean SystemEdit(Word editType)
   _________________________________________________________________
   
$1A05

SystemEvent

   The Event Manager uses this function to handle Desk Accessory events;
   every event returned to an application is first processed by
   SystemEvent, which returns TRUE if the event has been processed by a
   desk accessory and FALSE if it is to be sent to the application for
   processing.
   
   This function handles processing the Control-Apple-ESC sequence for
   accessing the CDA menu.
   
    Warning
    
   An application must never make this call.
   
  Parameters
  
  Input:
  
   wordspace Word -- Space for result.
   eventWhat Word -- From event record.
   eventMessage Long -- From event record.
   eventWhen Long -- From event record.
   eventWhere Long -- From event record.
   eventMods Word -- From event record.
   
  Output:
  
   processFlag Word -- TRUE if event was handled by an NDA, FALSE if not.
   
  Errors
  
   None
   
  C
  
   extern pascal Boolean SystemEvent(Word eventWhat, LongWord
   eventMessage, LongWord eventWhen, LongWord eventWhere, Word eventMods)
   _________________________________________________________________
   
$1905

SystemTask

   SystemTask causes each NDA to perform its periodic action (for those
   NDAs that have periodic actions and it's been long enough since the
   action was last performed).
   
   Applications that don't use TaskMaster should call this function
   periodically to allow these NDAs to function properly.
   
  Parameters
  
   There are no input or output parameters.
   
  Errors
  
   None
   
  C
  
   extern pascal void SystemTask(void)
   _________________________________________________________________
   
Desk Manager Constants

   Name
   
   Value
   
   Description
   
    NDA action codes
    
   eventAction $0001 Code passed if event is to be handled by NDA.
   runAction $0002 Code passed when the specified run action delay has
   passed.
   cursorAction $0003 Code passed when NDA is frontmost window when
   SystemTask is called.
   undoAction $0005 Undo selected in Edit menu.
   cutAction $0006 Cut selected in Edit menu.
   copyAction $0007 Copy selected in Edit menu.
   pasteAction $0008 Paste selected in Edit menu.
   clearAction $0009 Clear selected in Edit menu.
   
    Edit types
    
   undo $0001 Undo edit type
   cut $0002 Cut edit type
   copy $0003 Copy edit type
   paste $0004 Paste edit type
   clear $0005 Clear edit type
   
   
   
Desk Manager Error Codes

   Code
   
   Name
   
   Description
   $0510 daNotFound Specified DA not available.
   $0511 notSysWindow Window pointer is not a pointer to an NDA window.
   $0520 deskBadSelector Invalid desk accessory selector.
   
   

This text file is freely available public domain information. As
such...It may be duplicated or reprinted, in whole or in part, without
the express written permission of anybody.