home *** CD-ROM | disk | FTP | other *** search
/ MacHack 2001 / MacHack 2001.toast / pc / The Hacks / CSFinalHack Module / ES Headers / ExtensionsStrip.h < prev   
Encoding:
C/C++ Source or Header  |  2001-06-23  |  18.7 KB  |  444 lines
  1. /*
  2.      File:        ExtensionsStrip.h
  3.  
  4.      Contains:    Extensions Strip Specific Interfaces for Control Strip modules.
  5.  
  6.      Version:    Technology:    System 7.5 or greater.
  7.                  Package:    Extensions Strip 2.0
  8.  
  9.      Copyright:    © 1995, 1998 - 2000 by Ammon Skidmore, Skidperfect Software Inc.
  10.                  All rights reserved.
  11.  
  12.      Bugs?:        If you find a problem, have a criticism or comment with this
  13.                  file, please inform the author at the following address:
  14.                      Internet:    skidperfect@kagi.com
  15.                                  http://www.skidperfect.com/
  16. */
  17.  
  18. #ifndef __EXTENSIONSSTRIP__
  19. #define __EXTENSIONSSTRIP__
  20.  
  21. #ifndef __CONTROLSTRIP__
  22. #include <ControlStrip.h>
  23. #endif
  24.  
  25. #ifndef __APPLEEVENTS__
  26. #include <AppleEvents.h>
  27. #endif
  28.  
  29. #ifdef __cplusplus
  30. extern "C" {
  31. #endif
  32.  
  33. #if PRAGMA_ALIGN_SUPPORTED
  34. #pragma options align=mac68k
  35. #endif
  36.  
  37. #if PRAGMA_IMPORT_SUPPORTED
  38. #pragma import on
  39. #endif
  40.  
  41.  
  42. /******************************************************************************************
  43.  
  44.     Special Extensions Strip selector calls to modules.
  45.  
  46. ******************************************************************************************/
  47. enum {
  48.     sdevInAppContext            = 2000,    /* called only once after the module specifically
  49.                                            requested to be executed from inside Extension
  50.                                            Strip's context. NB: you can return the special
  51.                                            result values. */
  52.  
  53.     sdevInterceptedEvent        = 2001,    /* if the module returned the sdevInterceptAllEvents
  54.                                            flag in its features, then this selector
  55.                                            will get called before _each_ event is processed
  56.                                            by Extensions Strip.  Meant to be used with
  57.                                            _SBGetCurrentEvent so each event can be looked at,
  58.                                            and modified if necessary (to prevent passing.)
  59.                                            NB: you can return the special result values. */
  60.  
  61.     sdevDragAccept                = 2002,    /* return 0 if you accept the current drag, and
  62.                                            1 if you do not.  Modules that do not have any
  63.                                            drag handlers will never get this called.
  64.                                            NB: sdevDragAccept is only called from within
  65.                                            Extensions Strip's dragTrackingInWindow.  So it
  66.                                            is recommended to only check if you accept the
  67.                                            drag from within your dragTrackingEnterWindow, and
  68.                                            then set a global var that you can pass onto ES */
  69.  
  70.     sdevEventMask                = 2003    /* if the module returned the sdevInterceptAllEvents
  71.                                            flag in its features, this selector will get
  72.                                            called to find the event mask to use.  Return your
  73.                                            mask as the result value of the sdev call.
  74.                                            sdevEventMask is called once upon initialization,
  75.                                            and every time sdevFeaturesChange is requested. */
  76. };
  77.  
  78. /******************************************************************************************
  79.  
  80.     Features supported by the module.  If a bit is set, it means that feature is supported.
  81.  
  82.     Tip: if you clear sdevWantMouseClicks and set sdevDontAutoTrack, your module
  83.     will receive clicks and Extensions Strip (plus Desktop Strip) will not
  84.     auto-hilite your module.
  85.  
  86. ******************************************************************************************/
  87. enum {
  88.     sdevHasDragHandlers            = 31,    /* module has installed a drag tracking and/or
  89.                                            receive handler in the Strip window.  Setting
  90.                                            this bit will also tell ES not to shrink the
  91.                                            module (see sdevMiniModulesFriendly below). */
  92.  
  93.     sdevDontPeriodicTickle        = 30,    /* module does not require any idle time so
  94.                                            by setting this bit it will never get
  95.                                            called with the sdevPeriodicTickle 
  96.                                            selector.  Note that you can set this along
  97.                                            with the sdevInterceptAllEvents bit (if you want)
  98.                                            and sdevInterceptedEvent will still get called.
  99.                                            So be nice and set this to help speed up idle
  100.                                            time processing. */
  101.  
  102.     sdevInterceptAllEvents        = 29,    /* module wants to be executed before each
  103.                                            event passes through Extension Strip's
  104.                                            jGNE filter.  Because the module is allowed
  105.                                            to modify every event, there is no more need
  106.                                            for modules, such as Terminator Strip, to
  107.                                            install their own jGNE filters!
  108.                                            NB: You need to return an event mask when your
  109.                                            module is called by the sdevEventMask selector. */
  110.  
  111.     sdevNoMiniShrink            = 28    /* this bit signifies that the module does not want
  112.                                             to be shrunk when the strip preference "Mini
  113.                                             Modules" is set. */
  114. };
  115.  
  116. /******************************************************************************************
  117.  
  118.     Special result values returned by the sdevPeriodicTickle and sdevMouseClick selectors.
  119.     If a bit is set, the module can request that a specific function is performed by
  120.     the Control Strip.  All undefined bits should be set to zero.
  121.  
  122.     Note: these values can also be returned by the sdevInAppContext and
  123.     sdevInterceptedEvent selectors.
  124.  
  125. ******************************************************************************************/
  126. enum {
  127.     sdevQueueModule                = 31,    /* module needs to be executed from within
  128.                                            Extension Strip's context: useful for
  129.                                            things like sending AppleEvents or
  130.                                            creating and tracking new drags. */
  131.  
  132.     sdevFeaturesChange            = 30    /* module wants to change its feature flags. Useful
  133.                                            for changing clickable state of the module and
  134.                                            for locking/unlocking the sdev code. */
  135. };
  136.  
  137. /******************************************************************************************
  138.  
  139.     miscellaneous
  140.  
  141. ******************************************************************************************/
  142. enum {
  143.     kModuleFolderType                = 'sdev',    /* FindFolder type for the root folder */
  144.     kModuleDisabledFolderType        = 'sdeD',    /* FindFolder type for the disabled
  145.                                                    root folder (place to put inactive
  146.                                                    modules that you don't want deleted.) */
  147.     sdevTypeCodePPC                    = 'Sdev'    /* resource type for PPC module code.
  148.                                                     Sdev resources have the highest priority
  149.                                                     in loading.  Then comes CS 2.0 PPC code
  150.                                                     (found in the data fork) and then the
  151.                                                     good old sdev resource. */
  152. };
  153.  
  154.  
  155. enum {
  156.     gestaltExtensionsStripAttr        = 'CsEs',    /* returns Extensions Strip's attributes. */
  157.     /* currently returned bits from gestaltExtensionsStripAttr: */
  158.     gestaltExtensionsStripExists    = 0,        /* Extensions Strip is currently launched */
  159.     gestaltSupportsFontTraps        = 1,        /* The new font traps of Control Strip 1.2
  160.                                                    are supported.  ES 1.0 incorrectly gave
  161.                                                    Control Strip's font trap gestalt bit. */
  162.     gestaltHasSBResolveAliasFile    = 2,        /* ES contains the new alias resolving trap.
  163.                                                    This bit also signifies that ES can only
  164.                                                    be run as a regular application. */
  165.     gestaltESUsingNewFloaters        = 3,        /* Set if ES is using the new method of
  166.                                                    displaying floating windows.  Check this
  167.                                                    bit if you plan to use translucent drags
  168.                                                    since they didn't work with the old kind
  169.                                                    of windows when TSM Fix was needed. */
  170.     gestaltESUsingLayerManager        = 4,        /* Set if ES is using the Layer Manager to
  171.                                                    have dialogs displayed by modules appear
  172.                                                    floating.  Check this bit to see if
  173.                                                    SBRestoreFrontLayer() is available. */
  174.  
  175.     gestaltESMoreLikeCS20            = 5,        /* First set under ES 1.9.1.  This tells you:
  176.                                                     - if ES will run modules in its own context
  177.                                                         (when at least OS 8.5 is present).
  178.                                                     - if ES supports the new Control Strip 2.0 traps
  179.                                                         from 68K code (in ES 1.9 it was PPC only).
  180.                                                     - if modules can change the cursor from
  181.                                                         within their drag handlers. */
  182.     gestaltHasES20FeatureSet        = 6,        /* If ES 2.0 or greater is installed. */
  183.  
  184.     gestaltDesktopStripAttr            = 'CsWT'    /* returns the Desktop Strip program
  185.                                                    attributes which are supported by
  186.                                                    Extensions Strip.  See Desktop Strip's
  187.                                                    docs for details about the bits */
  188. };
  189.  
  190.  
  191. typedef unsigned long ModuleReference;
  192.  
  193.  
  194. typedef pascal void (*SBQueueProcPtr)(unsigned long refCon);
  195.  
  196. #if GENERATINGCFM
  197. typedef UniversalProcPtr SBQueueUPP;
  198. #else
  199. typedef SBQueueProcPtr SBQueueUPP;
  200. #endif
  201.  
  202. enum {
  203.     uppQueueProcProcInfo = kPascalStackBased | STACK_ROUTINE_PARAMETER(1, kFourByteCode)
  204. };
  205.  
  206. #if GENERATINGCFM
  207. #define NewSBQueueProcProc(userRoutine)        \
  208.         (SBQueueUPP) NewRoutineDescriptor((ProcPtr)(userRoutine), uppAEIdleProcInfo, GetCurrentArchitecture())
  209. #else
  210. #define NewSBQueueProcProc(userRoutine)        \
  211.         ((SBQueueUPP) (userRoutine))
  212. #endif
  213.  
  214. /******************************************************************************************
  215.  
  216.     Control Strip trap calls
  217.  
  218. ******************************************************************************************/
  219.  
  220. //                                                                                 //
  221. // All routines are documented as to whether the Extensions Strip implementation //
  222. // of them they may move memory.  You can trust that a routine that says it         //
  223. // will not move memory in this version, will not move memory in future versions.//
  224. // Note though, that some Universal Control Strip traps may move memory under     //
  225. // Control/Desktop Strip but not in Extensions Strip (such as                     //
  226. // _SBIsControlStripVisible and _SBShowHideControlStrip.)                         //
  227. //                                                                                 //
  228.  
  229. // =====================================================
  230. // =========== Universal Control Strip traps ===========
  231. // =====================================================
  232. /*
  233. 'Yes' = May move memory!
  234. 'No'  = Will not move memory.
  235. 'unimplemented'    = Trap not supported by Extensions Strip when this header file
  236.                 was released.  Check the Control Strip gestalt features to
  237.                 determine if/when Extensions Strip supports these traps.
  238.  
  239. SBIsControlStripVisible        no
  240. SBShowHideControlStrip        no
  241. SBSafeToAccessStartupDisk    no
  242. SBOpenModuleResourceFile    yes
  243. SBLoadPreferences            yes
  244. SBSavePreferences            yes
  245. SBGetDetachedIndString        no
  246. SBGetDetachIconSuite        yes
  247. SBTrackPopupMenu            yes
  248. SBTrackSlider                yes
  249. SBShowHelpString            yes
  250. SBGetBarGraphWidth            no
  251. SBDrawBarGraph                yes
  252. SBModalDialogInContext        yes
  253.  
  254. Control Strip 1.2 and later
  255. ---------------------------
  256. SBGetControlStripFontID        no
  257. SBSetControlStripFontID        no
  258. SBGetControlStripFontSize    no
  259. SBSetControlStripFontSize    no
  260. SBGetShowHideHotKey            no
  261. SBSetShowHideHotKey            no
  262. SBIsShowHideHotKeyEnabled    no
  263. SBEnableShowHideHotKey        no
  264. SBHitTrackSlider            yes
  265. */
  266.  
  267. // =====================================================
  268. // ========== Extensions Strip specific traps ==========
  269. // =====================================================
  270.  
  271. /* Strip Window Utilities */
  272.  
  273.     // returns: true = vertical; false = horizontal
  274.     //        // Will not move memory. //
  275. extern pascal Boolean SBIsControlStripVertical(WindowPtr stripPort)
  276.  THREEWORDINLINE(0x303C, 0x02FF, 0xAAF2);
  277.  
  278.     // returns pixel depth of the monitor this Strip window is in (always a power of 2)
  279.     //        // Will not move memory. //
  280. extern pascal short SBGetControlStripDepth(WindowPtr stripPort)
  281.  THREEWORDINLINE(0x303C, 0x02FE, 0xAAF2);
  282.  
  283.     // returns the current normal back color of this Strip window
  284.     //        // Will not move memory. //
  285. extern pascal void SBGetStripBackColor(RGBColor *color, WindowPtr stripPort)
  286.  THREEWORDINLINE(0x303C, 0x04FD, 0xAAF2);
  287.  
  288.     //returns the current back color of this Strip window when a module is selected
  289.     //        // Will not move memory. //
  290. extern pascal void SBGetStripSelectedColor(RGBColor *color, WindowPtr stripPort)
  291.  THREEWORDINLINE(0x303C, 0x04FC, 0xAAF2);
  292.  
  293. /* Module Utilities */
  294.  
  295.     // returns a reference number that all of the Module Utilities need
  296.         /* NB: since SBGetMyReferenceNum can ONLY be called from sdevInitModule,
  297.            you should save its value into your globals if you are going to use
  298.            one of the Module Utilities later, such as inside a tracking handler. */
  299.     // Also, the reference number will always be non-zero.
  300.     //        // Will not move memory. //
  301. extern pascal ModuleReference SBGetMyReferenceNum(void)
  302.  TWOWORDINLINE(0x70FB, 0xAAF2);
  303.  
  304.     // total window space taken up by a module.  Useful for drag-n-drop calculations
  305.     // note that this rect will always be larger than the module's statusRect.
  306.     //        // Will not move memory. //
  307. extern pascal void SBGetTotalModuleBounds(Rect *bounds, WindowPtr stripPort, ModuleReference moduleRefNum)
  308.  THREEWORDINLINE(0x303C, 0x06FA, 0xAAF2);
  309.  
  310.     // returns the statusRect of the module.  Very useful for drag-n-drop routines
  311.     // because you no longer have to constantly set a global rectangle variable to
  312.     // hold the current location of the module in the Strip window.
  313.     //        // Will not move memory. //
  314. extern pascal void SBGetModuleBounds(Rect *bounds, ModuleReference moduleRefNum)
  315.  THREEWORDINLINE(0x303C, 0x04F9, 0xAAF2);
  316.  
  317. /* Miscellaneous Utilities */
  318.  
  319.     // runs this (locked!) piece of code once within Extensions Strip's context.
  320.     // PPC modules must pass a valid routine descriptor to this function.  Since
  321.     // the descriptor will not be disposed of after the code has executed, I would
  322.     // recommend creating the descriptor (NewSBQueueProcProc) when sdevInitModule
  323.     // is called and disposing it upon sdevCloseModule.
  324.     // A non-zero result code means that the UPP could not be queued (memory error).
  325.     //        // May move memory! //
  326. extern pascal OSErr SBQueueCode(SBQueueUPP theProc, unsigned long refCon)
  327.  THREEWORDINLINE(0x303C, 0x04F8, 0xAAF2);
  328.  
  329.     // sends the specified Apple Event within Extensions Strip's context to insure
  330.     // safe sending rather than trusting that the front application is AE aware.
  331.     // _SBSimpleAESend acts just like _AESend in that the AppleEvent you give to it
  332.     // must still be disposed of afterward by your code to free up memory (even
  333.     // though the event hasn't actually been sent yet.)
  334.     //
  335.     // _SBSimpleAESend is meant to be an easy way to send simple events.  If you
  336.     // need to check the reply AppleEvent or the _AESend error, ect., you should queue
  337.     // your code (with _SBQueueCode or by having your module return 'sdevQueueModule')
  338.     // and send the Apple Event yourself.  The result returned by _SBSimpleAESend
  339.     // is only non-zero if an error occured while queueing the event for later sending.
  340.     //
  341.     // Also, if an error does occur when Extensions Strip sends your AppleEvent, the
  342.     // user will be notified with a dialog that _AESend failed.
  343.     //
  344.     // Here are the parameters I give to _AESend.  They are basic enough for most
  345.     // kinds of Apple Events that modules send, hence the name _SBSimpleAESend.
  346.     // err = AESend(&theAppleEvent, &reply,                // your specified AppleEvent
  347.     //                                                    // and a dummy reply descriptor
  348.     //            kAENoReply + kAEAlwaysInteract + kAECanSwitchLayer,    // send mode
  349.     //            kAENormalPriority,                                    // send priority
  350.     //            kAEDefaultTimeout,                                    // time out
  351.     //            nil,                                                // idleProc
  352.     //            nil);                                                // filterProc
  353.     //        // May move memory! //
  354. extern pascal OSErr SBSimpleAESend(const AppleEvent *theAppleEvent)
  355.  THREEWORDINLINE(0x303C, 0x02F7, 0xAAF2);
  356.  
  357.     // returns a pointer to the current event being processed.  Modififations to
  358.     // the data in this pointer WILL take effect as the event gets passed along
  359.     // to the other processes and jGNE filters further on in the chain.  Although
  360.     // a module can use this function at any time, it is really meant to be called
  361.     // within the sdevInterceptedEvent selector because this is where a module can
  362.     // deny other modules the proper processing of the event (such as in the case
  363.     // of a keyDown.)  Another good use for SBGetCurrentEvent() is to find the exact
  364.     // point where a mouseDown occured if you have a queue of clickable objects.
  365.     //        // Will not move memory. //
  366. extern pascal EventRecord* SBGetCurrentEvent(void)
  367.  TWOWORDINLINE(0x70F6, 0xAAF2);
  368.  
  369.     // For Extensions Strip 1.2 and later.                                //
  370.     // Check for gestalt features bit 'gestaltHasSBResolveAliasFile'.    //
  371.  
  372.     // resolves a chain of alias files just like the toolbox routine ResolveAliasFile()
  373.     // but with an option to override the mounting of remote volumes.  Most of the code
  374.     // is from an Apple snippet in the Technote "Quietly Resolving Finder Aliases".
  375.     //
  376.     // Also, in the event of the display of an AppleShare mounting dialog, if the
  377.     // current process is not in front, then the front process will be set to the
  378.     // current one.  Since Extensions Strip 1.2 and later can only be run as regular
  379.     // applications, the use of this trap is almost always safe to display mount
  380.     // dialogs.  You should, however, set the mounting of remote volumes to false
  381.     // if called inside a drop handler when the current process is not the front one.
  382.     //        // May move memory! //
  383. extern pascal OSErr SBResolveAliasFileMountOption(FSSpec *fileFSSpec, Boolean resolveAliasChains,
  384.         Boolean *targetIsFolder, Boolean *wasAliased, Boolean mountRemoteVols)
  385.  THREEWORDINLINE(0x303C, 0x08F5, 0xAAF2);
  386.  
  387.     // For Extensions Strip 1.9 and later.                                //
  388.     // Check for gestalt features bit 'gestaltESUsingLayerManager'.        //
  389.     
  390.     // sets the current layer to that of the front process.  You should always call
  391.     // this function before displaying a get/save file dialog.  This workaround is
  392.     // only really needed for System 8.5 but it is a good idea to use with all Systems.
  393.     // I know it's a hastle, but hey, you can't display standard file dialogs at all
  394.     // (directly from module code) under any of the Control Strips to date.
  395.     // For now this function always returns noErr.
  396.     //        // May move memory! //
  397. extern pascal OSErr SBRestoreFrontLayer(void)
  398.  TWOWORDINLINE(0x70F4, 0xAAF2);
  399.  
  400.     // For Extensions Strip 2.0 and later.                                //
  401.     // Check for gestalt features bit 'gestaltHasES20FeatureSet'.        //
  402.     
  403.     // This function differs from SBTrackPopupMenu() by returning the full long word
  404.     // result from PopUpMenuSelect().  Checking the high word will reveal the selected
  405.     // menu's id # so you can tell if it was a submenu.
  406.     //
  407.     // Note:    If you wish to use submenus and have your module work with other module
  408.     //            hosts, like Control Strip, it's best to stick to SBTrackPopupMenu()
  409.     //            followed by a call to MenuChoice() to get the menu id.
  410.     //
  411.     // -fittsArea- is an optional parameter (pass NULL if you don't need to use it) that
  412.     // provides special compatibility with ES 2.0's menubar mode.  If you don't like how
  413.     // ES determines the screen area to leave the menu visible for, then pass a custom
  414.     // value in fittsArea.  Usually, only modules that display multiple items in multiple
  415.     // multiple columns need this feature, like the HandyMan module.
  416.     //
  417.     //        // May move memory! //
  418. extern pascal long SBTrackHierMenu(const Rect *moduleRect, MenuHandle theMenu, const Rect *fittsArea)
  419.  THREEWORDINLINE(0x303C, 0x04F3, 0xAAF2);
  420.  
  421.     // Returns true if the module's strip is in menubar mode.  If you have a module that
  422.     // delays before displaying a menu, you should call this function to determine
  423.     // whether the delay is necessary.  For examples of this, see the Process Manager
  424.     // or HandyMan modules.
  425.     //        // Will not move memory. //
  426. extern pascal Boolean SBStripInMenuMode(void)
  427.  TWOWORDINLINE(0x70F2, 0xAAF2);
  428.  
  429.  
  430.  
  431. #if PRAGMA_IMPORT_SUPPORTED
  432. #pragma import off
  433. #endif
  434.  
  435. #if PRAGMA_ALIGN_SUPPORTED
  436. #pragma options align=reset
  437. #endif
  438.  
  439. #ifdef __cplusplus
  440. }
  441. #endif
  442.  
  443. #endif /* __EXTENSIONSSTRIP__ */
  444.