home *** CD-ROM | disk | FTP | other *** search
/ MacFormat 1995 March / macformat-022.iso / Shareware City / Developers / CMaster Demo v2.0.3 / CMaster XTRN Projects / XTRN.h < prev    next >
Encoding:
C/C++ Source or Header  |  1994-06-12  |  16.8 KB  |  364 lines  |  [TEXT/KAHL]
  1. /*
  2.  *
  3.  *            XTRN.h:    external interface definitions and structures
  4.  *            © 1994 Jersey Scientific, All Rights Reserved
  5.  *
  6.  *            History:
  7.  *                01/01/94: Version 1 of xtern structure
  8.  *                03/01/94: OK to have globals in the code
  9.  *                06/01/94: Added Zoom, WindowCloseIntercept
  10.  *                06/10/94: Added AEOpen callback
  11.  *                06/12/94: keyEquivalent and keyFunction have #include files
  12.  */
  13.  
  14. #ifndef __XTRN__
  15. #define __XTRN__
  16.  
  17. /*
  18.     Each external has a 'mres' resource of ID == 128 consisting of an array of
  19.     'mres' structures which describe the resources which the external needs to function.
  20.     The PROC resource MUST be described as the the first 'mres' structure.
  21.     
  22.     All resources will be loaded and HLock'ed before the external is called, and are 
  23.     HUnlocked and HPurged after the call, except the PROC resource, which gets restored
  24.     to its previous state (the state you set it when it was created).
  25.     
  26.     The external's ID can change during an editing session if an external is deleted,
  27.     so never cache this number! DLOGs and ALRTs will be pre-centered so no need to call
  28.     your own position dialog routine unless you want something different.
  29.     
  30.     You can use Globals in your code resource.
  31. */
  32.  
  33. #define CAPSLOCK ((*(short*)0x17A & 0x2) != 0)
  34. /* Handy, as you can use it for debugging as
  35.  * if(CAPSLOCK) { 
  36.  *         (xt->debugPrintf("Got a problem %d", i);
  37.  * }
  38.  */
  39.  
  40. typedef struct  {
  41.     short    flags;                    // what type is this item
  42. #    define     NX_FUNCTION    0x0001    // type 
  43. #    define     NX_PRAGMA_MARK    0x0002    // type 
  44. #    define     NX_MPSR        0x0004    // type 
  45. #    define     NX_IFDEF_MARK    0x0008    // type 
  46. #    define     NX_ELSEIF_MARK    0x0010    // type 
  47. #    define     NX_ENDIF_MARK    0x0020    // type 
  48. #    define     NX_CPLUS        0x0040    // C++ function
  49. #    define     NX_NOCOUNT        0x0080    // no count this function (used with exclusion feature)
  50. #    define     NX_NEVERCOUNT    0x0100    // never count this resource
  51. #    define     NX_INCLUDE        0x0200    // #include file (not normally passed to Externals)
  52. #    define     NX_CLASS        0x0400    // class ... lines
  53. #    define     NX_ENUM        0x0800    // enum ... lines
  54. #    define     NX_STRUCT        0x1000    // struct... lines
  55. #    define     NX_TYPEDEF        0x2000    // typdef struct ... lines
  56.     short    protoLen;                // includes the '{' at the end
  57.     long    commentStart;            // best guess where the comment starts
  58.     long     protoStart;                // information needed for developing prototypes
  59.     long    nameStart;                // points to function name
  60.     long    startBrace;                // offset to the starting brace
  61.     long    endBrace;                // offset to the final brace
  62.     Byte    nameLen;                // function name len
  63.     Byte    classLen;                // length of the class in "class :: method"
  64.     Byte    methodLen;                // length of the method in "class :: method"
  65.     Byte    _unused;                // spare
  66. } NameNode, *NameNodePtr, **NameNodeHdl;
  67.  
  68. typedef struct {
  69.     short            version;                // version number to get all fields below - now 1
  70.     Handle             text;                    // actual handle of the windows text (usually unlocked!)
  71.     long            textLngth;                // don't GetHandleSize of above - use this number
  72.     long            topOfScreen;            // offset to the char at top left of window
  73.     long            startSelect;            // offset to the cursor or the current selection start
  74.     long            endSelect;                // offset to the cursor or the current selection end
  75.     unsigned long    upDateTime;                // System time of last update
  76.     FSSpec            fileFSSpec;                // FSSpec of the current text file
  77.     StringPtr        fileName;                // file name of current window
  78.     short            vRefNum;                // file volume reference number
  79.     long            dirID;                    // file directory reference number
  80.     short            tabCount;                // chars-per-tab
  81.     NameNodeHdl        nnH;                    // parsed data (see above struct)
  82.     short            nnCount;                // size of above
  83.     short            windDirty;                // true if window is "dirty"
  84.     short            windType;                // 0 == no write, 1 write OK, 2 write/modified
  85.     Handle            ckidHdl;                // the 'ckid' handle attached to this window
  86.     long            _growth[3];                // we might add more stuff during the beta
  87. } TextData, *TextDataPtr, **TextDataHdl;
  88.  
  89. typedef struct {
  90.     char            function[32];            // name for menus (C style)
  91.     short            keyEquivalent;            // used to temporarily store equivalents
  92. } PxItem, *PxItemPtr, **PxItemHdl;
  93.  
  94. typedef struct {
  95.     char            fileName[32];            // USED BY CMASTER - DO NOT CHANGE
  96.     short            _cmReserved0;            // USED BY CMASTER - DO NOT CHANGE
  97.     short            inited;                    // USED BY CMASTER - DO NOT CHANGE
  98.     short            wantRawEvents;            // want to see events before CMaster
  99.                                             // - events passes in the parameter block,
  100.                                             // - CMaster passes your return code as
  101.                                             // - GetNextEvent return
  102.     short            wantProcessedEvents;    // want to see events after CMaster has perhaps
  103.                                             // - changed it,
  104.                                             // - events passes in the parameter block.
  105.                                             // - CMaster passes your return code as the
  106.                                             // - GetNextEvent return.
  107.     short            wantOpenWindow;            // want to do something just as a window opens.
  108.                                             // - CMaster responds with two calls.
  109.                                             // - One, when the window size can be changed.
  110.                                             // - Two, when you can look at the data, and 
  111.                                             // - possibly change it (we haven't tested this.) 
  112.                                             // - WindowPeek, fileRefNum, passed in the parameter block
  113.     short            wantCloseWindow;        // want to intercept the user closing a window. Return TRUE
  114.                                             // - in response to the XTRN_WIND_CLOSE event to prevent the window
  115.                                             // - actually closing. To actually close the window, you must
  116.                                             // - later post a CMD-W event (while getting RAW or COOKED events,
  117.                                             // - change a nullEvent into a CMD-W). See NOTE below on this event.
  118.                                             // - WindowPeek, fileRefNum, passed in the parameter block
  119.     short            wantZoom;                // want to do something when user presses Zoom box
  120.                                             // - or they type Cmd-/
  121.                                             // - You can change either of the userState or stdState
  122.                                             // - rectangles, so you could move the window to another
  123.                                             // - monitor if you wanted to. You would return FALSE
  124.                                             // - to let the Zoom proceed as normal, or you can
  125.                                             // - return inZoomIn (Windows.h) to have the window zoom
  126.                                             // - to the userState, or inZoomOut to the WDEF's out state.
  127.                                             // - WindowPeek, fileRefNum, passed in the parameter block
  128.     short            _unused[2];                // future something...
  129.  
  130.     long            reserved0;                // use for semi-permanent storage (during one project cycle)
  131.     long            reserved1;                // use for semi-permanent storage (during one project cycle)
  132.     long            reserved2;                // use for semi-permanent storage (during one project cycle)
  133.     long            reserved3;                // use for semi-permanent storage (during one project cycle)
  134.     short            _cmReserved1;            // USED BY CMASTER - DO NOT CHANGE
  135.  
  136.     PxItem            normalFunc;
  137.     PxItem            optionFunc;
  138.     PxItem            cmdFunc;
  139.     PxItem            controlFunc;
  140.     PxItem            shiftFunc;
  141.     PxItem            shiftOptionFunc;
  142.     PxItem            shiftCmdFunc;
  143.     PxItem            optionCmdFunc;
  144.     PxItem            optionControlFunc;
  145.     PxItem            optionShiftCmdFunc;
  146. } XtItem, *XtItemPtr, **XtItemHdl;                // resource 'xitm'
  147.  
  148. typedef struct {
  149.     short            version;                    // version of this structure
  150.     short            resID;                        // the current XTRN's resource ID (20000 -> ...)
  151.     EventRecord        *evp;                        // NULL or event record (XTRN_RAW, XTRN_COOKED, XTRN_KEY)
  152.     WindowPeek        window;                        // NULL, foremost text window, or window for XTRN_WIND_OPEN & XTRN_WIND_CLOSE
  153.     short            projResFile;                // refNum of resource fork of the Project file
  154.     short            xtrnResFile;                // refNum of resource fork of the CMaster Pref file
  155.     short            xtrnVRefNum;                // vRefNum of the CMaster XTRN folder
  156.     long            xtrnDirID;                    // dirID of the CMaster XTRN folder
  157.     long            private[4];                    // needed by future callbacks
  158.     
  159.     void            (*deActivate)(void);
  160.         // call this before showing a dialog (or another) window - it unhilites the 
  161.         // foremost window as needed
  162.     void            (*debugPrintf)(char *fmt, ...);
  163.         // Printf-style DebugStr- just makes debugging nices and CMaster eats the extra
  164.         // space instead of you
  165.     void            (*doneBeep)(void);
  166.         // DoneBeep sound used by CMaster to signal the end of an activity otherwise not
  167.         // obvious
  168.     Handle            (*fullFileName)(FSSpec *fssP);
  169.         // Given a FSSpec pointer, CMaster builds the complete path name and stores
  170.         // it into a handle, which you then must DisposeHandle(). A handle is used as 
  171.         // a Str255 may not be large enought to store the string. The handle contains
  172.         // text only, that is, it is neither a Pascal nor a C string.
  173.     Handle            (*getScrapHandle)(void);    // get current scrap
  174.         // Returns a handle containing a copy of the current scrap.
  175.         // DisposeHandle() after using.
  176.     void            (*hardBeep)(void);
  177.         // HardBeep sound used to signal serious problems that will likely lead to a crash
  178.     Boolean            (*putScrapHandle)(Handle textH);
  179.         // loading THINK's scrap with this handle, but don't paste it. The user can then
  180.         // paste this text by typing Cmd-V. Before pasting your own text, you can use
  181.         // the getScrapHandle call to get the current scrap, paste your stuff, then use this
  182.         // command to reload THINK's scrap with the original contents.
  183.     Boolean            (*pasteText)(Handle textH);
  184.         // paste the supplied text handle into the window at the current cursor or selection
  185.         // range, perhaps overwriting text.
  186.     void            (*positionDialog)(OSType type, short resID);
  187.         // put a 'DLOG' or 'ALRT' onto the main screen either 1/3 or 1/5 from the top, respectively
  188.     void            (*positionSubDialog)(OSType type, short resID);
  189.         // put a DLOG or ALRT positioned over another window. the Apple HIM recommends this
  190.         // type of action when the dialog refers to the foremost window. This call could
  191.         // place the dialog offscreen if the window is poorly located or small relative to
  192.         // the dialog.
  193.     void            (*softBeep)(void);
  194.         // SoftBeep sound - used to signal incorrect input, a user error, etc
  195.     void             (*reFreshWindows)(WindowPeek wp);
  196.         // callback for Moveable Modal dialogs to UpDate THINK C windows as the window
  197.         // moves. In a Modal Dialog filter function, call the code located at the bottom
  198.         // of this file to get a "cheap" Moveable-Modal-Dialog.
  199.         
  200.     TextDataPtr        (*getTextData)(WindowPeek wp);// returns nil or a struct ptr
  201.         // function to get data for the foremost window's text handle,
  202.         // length of the text (which may be smaller than GetHandleSize!!).
  203.         // This is the actual text handle - may or may not be locked,
  204.         // so return to its original state when you return.
  205.         // Also, don't change text directly - use pasteText below.
  206.         // Remember that you have to call DisposePtr on this data.
  207.     void            (*setSelection)(WindowPeek wp, long beginChar, long beginSelChar, long endSelChar, Boolean forceChange);
  208.         // Set window to start showing text at offset "beginChar", hiliting 
  209.         // the text between offsets beginSelChar and endSelChar. The forceChange option,
  210.         // if TRUE, says ignore "beginChar" and center the selection, This may happen in
  211.         // any case, if the text does not all fit on the screen.
  212.     Boolean            (*getFiles)(WindowPeek wp, short type, FSSpec **fsspP, short *fsspNum);
  213.         // CMaster returns a Ptr in fsspP containing an array of FSSpec records,
  214.         // each containing a file which is either a header file (type == FILES_HEADER) or
  215.         // a .c file (type == FILES_PROJ_SRC). Note that these values reference the STR#
  216.         // 1030x strings that CMaster lets you override. They are the negative of the string
  217.         // you want to get, so you could also get other files from that string too.
  218.         // When calling this function, you define a variable "FSSpec *fsPtr", and use it
  219.         // in the call as (..., &fsPtr, ...). When done, you must DisposePtr((Ptr)fsPtr).
  220.         #define            FILES_HEADERS        -2        // Get header files in the current source file
  221.         #define            FILES_PROJ_HEADERS    -5        // Get all header files in the project
  222.         #define            FILES_PROJ_SRC        -6        // Get all source files in the project
  223.     Boolean            (*keyFunction)(WindowPeek wp, short type, EventRecord *evp);
  224.         // Actuate a CMaster Key Function. The type is the 0-based offset in the pnmk 10000
  225.         // resource. #include "CallKeyFunctions.h" to get #defines for them...
  226.     Boolean            (*keyEquivalent)(WindowPeek wp, short type, EventRecord *evp);
  227.         // Actuate a CMaster Key Equivalent. The type is the 0-based offset in the pnme
  228.         // 10000 resource. #include "CallKeyEquivalents.h" to get #defines for them...
  229.     Boolean            (*drawWindow)(WindowPeek wp, Boolean showIt);
  230.         // If you muck with the size of the window as it opens (XTRN_WIND_OPEN), then
  231.         // call this with "showIt" either false or true, depending on what works best for you...
  232.     Boolean            (*getResFile)(FSSpec *fssP);
  233.         // Return a FSSpec containing a reference to the Project.π.rsrc file, or a 
  234.         // Aliased Project Resource File if one exists.
  235.     short            (*sprintf)(char *s, char *fmt, ...);
  236.         // Standard File package Routine
  237.         // Aliased Project Resource File if one exists.
  238.     Boolean            (*AEOpen)(FSSpec *fssP);
  239.         // Open a file FSSpec, open that file. If THINK 5, this call queues a call
  240.         // which is not processed until later (next NULL Event). Otherwise, CMaster
  241.         // uses AppleEvents with THINK to open the file during the call. Note that
  242.         // the current file will most likely NOT be the foremost file after this
  243.         // call, so you probably should not do further text editing (however, we didn't
  244.         // test this hypothesis, so all might work just fine.)
  245.         // The file must be of type 'TEXT' or this call fails.
  246. } Xtrn, *XtrnPtr, **XtrnHdl;
  247.  
  248. // NOTE: to change the text of a window as it closes, you intercept the WIND_CLOSE action
  249. // - first must set wantCloseWindow to TRUE. When you get a WIND_CLOSE_WIND call, you
  250. // - can change the file text, then set the wantProcessedEvents to TRUE (to look for nullEvents).
  251. // - Change the nullevent into a CMD-S to save the file, then at the next null event
  252. // - change it into a CMD-W event (and keep a flag around so that you will remember to
  253. // - return FALSE which lets THINK finally close the file.  Sorry we can't give you a
  254. // - callback to do this, but CMaster has no way or doing this the "right" way.
  255.  
  256. // NOTE: to remove a selection, get an empty handle (NewHandle(0L), then use it to
  257. // - in a call to PasteText(), and don't forget the DisposeHandle.
  258.  
  259. // this is how your main function will be called
  260. typedef Boolean (*xProc)(
  261.     short            type,    // type of call (XTRN_xxxx, see above)
  262.     XtrnPtr            xP,     // xtern structure
  263.     XtItemPtr        iP,        // some fields are for your private use - see above
  264.     short            keys    // modifier keys associated with this event (KEY, MENU, and ZOOM only)
  265.                             // - XTRN_WIND_OPEN: TRUE if a Untitled window, FALSE otherwise
  266. );
  267. // type values
  268. #define    XTRN_INIT                0    // init message: allocate temp memory, etc
  269. #define    XTRN_QUIT                1    // quit message: deallocate temp memory, etc
  270. #define    XTRN_RAW                2    // raw event in 
  271. #define    XTRN_COOKED                3    // event after CMaster could have changed it
  272. #define    XTRN_WIND_OPEN1_SIZE    4    // window opening - you could resize it if you wanted to
  273.                                     // - however, GetTextData fails at this point
  274. #define    XTRN_WIND_OPEN2_DATA    8    // window opening - can now call GetTextData()
  275. #define    XTRN_WIND_CLOSE            5    // selected by a menu selection (evp invalid) - see NOTE below
  276. #define XTRN_KEY                6    // selected by a key stroke (evp valid)
  277. #define XTRN_MENU                7    // selected by a menu selection (evp invalid)
  278. #define XTRN_ZOOM                9    // selected by a menu selection (evp invalid)
  279.  
  280.  
  281. // Externsion defines
  282. #define XTRN_START        20000                    // CMaster starts numbering resources from here
  283. #define XTRN_GAP        32                        // each XTRN gets a range of 32
  284. #define XTRN_DEFAULT    128                        // default number
  285.  
  286. /*
  287.  *  THIS IS A HANDY switch to use if you want to support many modifier options
  288.  *
  289.     switch(keys) {
  290.     case 0:
  291.         break;
  292.     case (optionKey):
  293.         break;
  294.     case (cmdKey):
  295.         break;
  296.     case (controlKey):
  297.         break;
  298.     case (shiftKey):
  299.         break;
  300.     case (shiftKey|optionKey):
  301.         break;
  302.     case (shiftKey|cmdKey):
  303.         break;
  304.     case (optionKey|cmdKey):
  305.         break;
  306.     case (optionKey|controlKey):
  307.         break;
  308.     case (optionKey|shiftKey|cmdKey):
  309.         break;
  310.     }
  311. */
  312.  
  313. /* code to add to a filter function for a cheap Moveable Modal Dialog Window (Thanks Max!)
  314.     case mouseDown:
  315.     case mouseUp:
  316.         gWhere = evt->where;                // Make info available to DoDialog()
  317.         GlobalToLocal(&gWhere);
  318.         theWindow = dlog;
  319.         mouseLoc = FindWindow(evt->where, &theWindow);
  320.         switch (mouseLoc) {
  321.         case inDrag:
  322.             bounds = (**GetGrayRgn()).rgnBBox;
  323. #define DRAG_MARGIN 4
  324.             InsetRect(&bounds, DRAG_MARGIN, DRAG_MARGIN);
  325.             DragWindow(theWindow, evt->where, &bounds);
  326.             ans = TRUE;                        // Make sure Modal dialog doesn't handle event
  327.             break;
  328.         default:
  329.             break;
  330.         }
  331.         break;
  332.     case updateEvt:
  333.         GetPort(&oldPort);
  334.         SetPort(w);
  335.         BeginUpdate(w);
  336.         if (w == dlog) {                            // Update our dialog contents
  337.             UpdtDialog(w, w->visRgn);
  338.             {
  339. #                define kButtonFrameInset  (-4)        // inset rectangle adjustment around button
  340. #                define kButtonFrameSize     3                    // button frame’s pen size
  341.                 short type; Handle hndl; Rect box;
  342.                 PenState    oldPen;
  343.                 short        buttonOval;
  344.     
  345.                 GetPenState(&oldPen);
  346.                 PenNormal();
  347.     
  348.                 GetDItem(dlog, 1, &type, &hndl, &box);
  349.                 InsetRect(&box, kButtonFrameInset, kButtonFrameInset);
  350.                 buttonOval = (box.bottom - box.top) / 2 + 2;
  351.  
  352.                 PenMode(patCopy);                    // Paint or delete frame
  353.                 PenSize(kButtonFrameSize, kButtonFrameSize);
  354.                 FrameRoundRect(&box, buttonOval, buttonOval);
  355.  
  356.                 SetPenState(&oldPen);
  357.             }
  358.         } else {
  359.             (*xP->reFreshWindows)((WindowPeek)w);                // the call back
  360.         }
  361.         EndUpdate((WindowPtr)w);
  362.         SetPort(oldPort);
  363. */
  364. #endif    /* __XTRN__ */