home *** CD-ROM | disk | FTP | other *** search
/ Mac Mania 3 / MacMania 3.toast / Tools&Utilities / extensions 12 strip / Developer’s toolkit / Programming Notes < prev    next >
Encoding:
Text File  |  1995-12-09  |  7.0 KB  |  166 lines  |  [TEXT/R*ch]
  1. { /*
  2.  
  3. Extensions Strip Programming Notes
  4. by Ammon Skidmore 10/95, 11/95, 12/95
  5.  
  6. Despite what the title may imply, this document does not explain the new API. 
  7. The purpose of the file at this point in time is to give out tips and explain
  8. special issues to be concerned with when programming modules for use with
  9. Extensions Strip.
  10.  
  11. To learn more about the API, please read the header file and source code since
  12. they are both heavily commented.  The whole of the Control Strip API is
  13. documented in the New Technical Notes OS 6 – Control Strip Modules (this
  14. information originally appeared in the PowerBook 500 series Developer Note.)
  15.  
  16. NB: at the time of this writing, free registrations of Extensions Strip are
  17. being offered to programmers who support ES' API in their modules.  Also, if
  18. someone wants to convert the ESDemo source code to MW Pascal, I would be very
  19. grateful in the same manner.  Yes, I care about Pascal even though ES was
  20. totally written in C and 68K assembly.  I also want to cut back on new (and
  21. seasoned) programmers asking: "What the %[^\n]%* is this?" :-)
  22.  
  23. -=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-
  24.  
  25. • How to make module programming lots of fun!
  26.  
  27. Create an alias to your module's project folder and add the alias to the root
  28. module folder.  Whenever you build your module, click on the strip's title bar
  29. with the command & option keys down to get the new compile to load.  You will
  30. never have to leave your development application to try the latest build!
  31.  
  32.  
  33. • Gestalt info:
  34.  
  35. Extensions Strip implements its own features selector, as well as the Control
  36. Strip & Desktop Strip selectors.  Here are the selectors and what they return:
  37.  
  38. 'CsEs'(gestaltExtensionsStripAttr) - returns bits:
  39.     0 (gestaltExtensionsStripExists) when Extensions Strip is launched.
  40.     1 (gestaltSupportsFontTraps) returned by ES 1.1 and later because the
  41.                     CS gestalt selector in ES 1.0 returned that fonts were
  42.                     supported, yet the font traps were not.
  43.     2 (gestaltHasSBResolveAliasFile) returned by ES 1.2 and later.  Means
  44.                     that ES contains the new alias resolving trap
  45.                     SBResolveAliasFileMountOption.  This bit also signifies
  46.                     that ES can only be run as a regular application.
  47.  
  48. 'csvr'(gestaltControlStripVersion) - current version of Extensions Strip in
  49.     the standard System format.  Ex, version 1.2.3 would be returned as $0123.
  50.  
  51. 'sdev'(gestaltControlStripAttr) - currently returned bits:
  52.     0 (gestaltControlStripExists)
  53.     1 (gestaltControlStripVersionFixed)
  54.     2 (gestaltControlStripUserFont)
  55.  
  56. 'CsWT'(gestaltDesktopStripAttr) - currently returns bits 0 and 1.  I don't
  57.     know what these bits signify, but they are returned anyway since that's
  58.     what Desktop Strip 1.2.1 returns.
  59.  
  60.  
  61. • PowerPC notes:
  62.  
  63. ExtensionsStripLib, the shared library that the control strip traps are linked
  64. to, is distributed for programmers in its regular shared library form.  This
  65. allows you to easily drag and drop it onto a CodeWarrior project, among other
  66. things.  For the end user however, they never see ExtensionsStripLib because
  67. it is embedded into Extensions Strip Control version 1.2 and later.
  68.  
  69. Remember to use 'weak' links to libraries that are not guaranteed to be present.
  70. Not doing so will crash the computer if the lib cannot be found.
  71. ExtensionsStripLib and the InterfaceLib are always guaranteed to be present so
  72. do not require 'weak' links.
  73.  
  74. Calling SBSafeToAccessStartupDisk() from PPC code will always return true
  75. regardless of the state of the hard disk.  This is because I do not have Apple's
  76. shared library to link the required calls to.  Has Apple has even made a library
  77. for this yet?  If anyone out there has a copy of this library, or know if one
  78. exists, could you please e-mail me?
  79.  
  80.  
  81. • Intelligent Alias Resolving:
  82.  
  83. AppleShare login dialog boxes create alias resolving difficulties for control
  84. strip modules.  To combat this problem, ES 1.2 and later contain the trap
  85. SBResolveAliasFileMountOption.
  86.  
  87. SBResolveAliasFileMountOption works like the Apple trap call ResolveAliasFile,
  88. except that you can tell it not to mount remote volumes.  If you do tell it
  89. to mount volumes, however, and the current process is not the front process,
  90. then the front process will be temporarily switched to the front one so that
  91. AppleShare login dialogs (if any) will be in front of all other windows.  This
  92. is very nice if you call the trap from sdevInAppContext.
  93.  
  94. Now that I've said the above, do NOT flag to mount remote volumes from drag
  95. handlers if the current process is not the frontmost one.  This is because
  96. AppleShare login boxes will appear inside the current process, which the user
  97. will not be able to switch to because you can't switch processes while TrackDrag
  98. is being called.  My Process Manager module does the following from its
  99. drag receive handler to prevent this nasty situation:
  100.  
  101. if ((**globH).hasESResolveAliasTrap)
  102.     // if we have it, call a friendly alias resolver
  103.     err = SBResolveAliasFileMountOption(&hfsData.fileSpec, TRUE, &targetIsFolder,
  104.                                         &wasAliased, IsCurProcessInFront());
  105. else
  106.     // if not, live on the wild side
  107.     err = ResolveAliasFile(&hfsData.fileSpec, TRUE, &targetIsFolder, &wasAliased);
  108.  
  109. /******************************************************************************
  110.  IsCurProcessInFront        return true if the current process is in front
  111.  ******************************************************************************/
  112. static Boolean IsCurProcessInFront(void)
  113. {
  114.     Boolean                result = FALSE;
  115.     ProcessSerialNumber    curPSN, frontPSN;
  116.     
  117.     if    (    (GetCurrentProcess(&curPSN) == noErr) &&
  118.             (GetFrontProcess(&frontPSN) == noErr)    )
  119.     {
  120.         SameProcess(&curPSN, &frontPSN, &result);
  121.     }
  122.     
  123.     return(result);
  124. }
  125.  
  126.  
  127. • ModalDialog() notes:
  128.  
  129. With Extensions Strip, your dialogs may call ModalDialog() instead of
  130. SBModalDialogInContext().  The only real benefit to this is that the user gains
  131. access to the edit menu.  Note though, that as of this writing, Desktop Strip
  132. crashes when ModalDialog() is called so if you are concerned with compatibility,
  133. stick with SBModalDialogInContext().
  134.  
  135.  
  136. • Crashes:
  137.  
  138. Tip: If a module crashes your computer, but you are able to resume using your
  139. computer (usually through the use of MacsBug's 'es' command), then clicking on
  140. any strip will result in a beep.  You could resume the use of Extensions Strip
  141. by turning it off and back on, but if you are sure that the "crash" was not
  142. serious (ex. you felt like force-quitting), then you can resume the use of ES by
  143. dragging something onto any strip.
  144.  
  145. Note that I have left in the debugging names to Extensions Strip's functions. 
  146. This helps me to locate possible bugs that you may encounter (nobody's perfect!)
  147. So, if ES crashes while you are using a low level debugger, and you don't think
  148. that it's your module's fault, then kindly e-mail me a dump to disk of at the
  149. following things:
  150. ---------------
  151. log esCrash1
  152.  
  153. stat;sc6;sc7;ip;hc;td;ir
  154.  
  155. log
  156. ---------------
  157. BTW, if you are wondering what some of these commands do, just snap into
  158. MacsBug and type 'help' followed by the command.  Happy hacking!
  159.  
  160. -=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-
  161.  
  162. "The Windows API has done more to retard skill development
  163. than anything since COBOL maintenance."    --Larry O'Brien
  164.  
  165. */ }
  166.