home *** CD-ROM | disk | FTP | other *** search
/ Celestin Apprentice 2 / Apprentice-Release2.iso / Source Code / Developer Kits / Arrange Developer Kit / Examples / Generic Plugin / GenericPlugin.cp < prev    next >
Encoding:
Text File  |  1994-07-15  |  11.0 KB  |  340 lines  |  [TEXT/MPS ]
  1. #include "ArrangeCallbacks.h"
  2. #include "PluginLibrary.h"
  3.  
  4. #include <Dialogs.h>
  5.  
  6.  
  7. /* This file defines a "generic" plugin module for Arrange 2.0.  To
  8.  * use it, you should modify the Plugin class definition by adding
  9.  * new fields and private functions, and make corresponding changes in the
  10.  * "Plugin" section at the bottom of the file.  You should not have to
  11.  * look at or make any changes to the "Main entry point" section in the middle
  12.  * of the file.  This section contains code to create an instance of
  13.  * Plugin when the module is loaded, and forward hook calls from Arrange to
  14.  * the appropriate Plugin functions.
  15.  * 
  16.  * There is an associated Rez file, GenericPlugin.r, which defines the
  17.  * 'MDdf' resource needed for each Arrange plugin module.  To create a plugin
  18.  * module, compile GenericPlugin.r to produce an 'MDdf' resource, and
  19.  * compile and link this file to produce an 'MDcd' resource with the same ID.
  20.  * 
  21.  * This version of GenericPlugin.cp was written by Steve Newman on 12/24/93.
  22.  * Last updated 7/15/94.
  23.  */
  24.  
  25.  
  26. #define ModuleRsrcID -0x8000
  27.  
  28. #define OurModuleID  0x70000000  // Unique module ID; replace with a value
  29.                                            // obtained from Common Knowledge.
  30. #define baseCmdCode  OurModuleID
  31.  
  32. #define aboutCmdCode (baseCmdCode + 0)
  33.  
  34.  
  35. class Plugin
  36.     {
  37. public:
  38.     Plugin(const ArrangeCallbackTbl* theCalls);
  39.     ~Plugin();
  40.     
  41.     arHookResult ClickNotify( arClickLocation loc, Point where, Short modifiers,
  42.                                       Short clickCount, arNoteID note, arFieldID field,
  43.                                       arPathID path );
  44.     arHookResult KeyNotify  ( Short theChar, Short key, Short modifiers );
  45.     arHookResult MenuNotify ( Integer commandCode, Integer commandParam,
  46.                                       Short modifiers );
  47.     arHookResult FieldNotify( arNoteID note, arFieldID field, arFieldAction action,
  48.                                       const char* choiceText );
  49.     void         TopicNotify( arTopicID newTopic, arWindowID newWindow,
  50.                                       arTopicAction action );
  51.     void             TickNotify (  );
  52.     arHookResult FileNotify ( arFileAction action );
  53.     arHookResult QuitNotify (  );
  54.     void         ATMNotify  (  );
  55.     
  56. private:
  57.     const ArrangeCallbackTbl* calls; // callback table
  58.     }; // Plugin
  59.  
  60.  
  61. /*************************************************************************/
  62. /**************************** Main entry point ***************************/
  63. /*************************************************************************/
  64.  
  65. /* Root entry point for the module - must be the first function in the
  66.  * file, so that the linker will place it first in the code segment.
  67.  * This is the routine which Arrange calls at application startup time
  68.  * (and again at quit time).
  69.  * 
  70.  * Most plug-ins will not need to modify this routine or the Hook functions
  71.  * immediately following.  All customization can be done in the "Plugin"
  72.  * section (below).
  73.  */
  74. extern "C" Integer OurModuleRoot( ModuleParamBlock *pb, ModuleRootAction action,
  75.                                             Integer /*p1*/ )
  76.     {
  77.     /* Extract the callback table from our parameter block, and coerce it
  78.      * to the extended Arrange table.
  79.      */
  80.     ArrangeCallbackTbl* calls = (ArrangeCallbackTbl*)(pb->calls);
  81.     
  82.     switch (action)
  83.         {
  84.         case mrLoad:
  85.             {
  86.             // Allocate memory and create a new Plugin object.
  87.             void* storage = calls->mem->AllocMem( sizeof(Plugin),
  88.                                                               amFreeStore | amErrIfNoMem );
  89.             pb->moduleRefcon = uInteger(new(storage) Plugin(calls));
  90.             return 1;
  91.             }
  92.         
  93.         case mrUnload:
  94.             {
  95.             /* Dispose of the Plugin object and release the memory
  96.              * it occupies.
  97.              */
  98.             delete (Plugin*)(pb->moduleRefcon);
  99.             calls->mem->DeallocMem((void*)(pb->moduleRefcon), amFreeStore);
  100.             return 0;
  101.             }
  102.         
  103.         case mrFindEntry:
  104.         default:
  105.             {
  106.             /* This module contains no extended entry points, so we always
  107.              * return 0 for the mrFindEntry message.  Most plug-ins will not
  108.              * use extended entry points.
  109.              */
  110.             return 0;
  111.             }
  112.         
  113.         } // switch (action)
  114.     
  115.     } // OurModuleRoot
  116.  
  117.  
  118. /* These hook functions simply pass control to the appropriate function
  119.  * in the Plugin object.
  120.  */
  121. static arHookResult OurClickHook( ModuleParamBlock* pb, arClickLocation loc,
  122.                                              Point where, pShort modifiers, pShort clickCount,
  123.                                              arNoteID note, arFieldID field,
  124.                                              arPathID path ENDP )
  125.     {
  126.     return ((Plugin*)(pb->moduleRefcon))->ClickNotify( loc, where, modifiers,
  127.                                                                         clickCount, note, field,
  128.                                                                         path );
  129.     }
  130.  
  131.  
  132. static arHookResult OurKeyHook( ModuleParamBlock* pb, pShort theChar, pShort key,
  133.                                           pShort modifiers ENDP )
  134.     {
  135.     return ((Plugin*)(pb->moduleRefcon))->KeyNotify(theChar, key, modifiers);
  136.     }
  137.  
  138.  
  139. static arHookResult OurMenuHook( ModuleParamBlock* pb, Integer commandCode,
  140.                                             Integer commandParam, pShort modifiers ENDP )
  141.     {
  142.     return ((Plugin*)(pb->moduleRefcon))->MenuNotify( commandCode, commandParam,
  143.                                                                      modifiers );
  144.     }
  145.  
  146.  
  147. static arHookResult OurFieldHook( ModuleParamBlock* pb, arNoteID note,
  148.                                              arFieldID field, arFieldAction action,
  149.                                              const char* choiceText ENDP )
  150.     {
  151.     return ((Plugin*)(pb->moduleRefcon))->FieldNotify( note, field, action,
  152.                                                                         choiceText );
  153.     }
  154.  
  155.  
  156. static void OurTopicHook( ModuleParamBlock* pb, arTopicID newTopic,
  157.                                   arWindowID newWindow, arTopicAction action ENDP )
  158.     {
  159.     ((Plugin*)(pb->moduleRefcon))->TopicNotify(newTopic, newWindow, action);
  160.     }
  161.  
  162.  
  163. static void OurTickHook(ModuleParamBlock* pb ENDP)
  164.     {
  165.     ((Plugin*)(pb->moduleRefcon))->TickNotify();
  166.     }
  167.  
  168.  
  169. static arHookResult OurFileHook(ModuleParamBlock* pb, arFileAction action ENDP)
  170.     {
  171.     return ((Plugin*)(pb->moduleRefcon))->FileNotify(action);
  172.     }
  173.  
  174.  
  175. static arHookResult OurQuitHook(ModuleParamBlock* pb ENDP)
  176.     {
  177.     return ((Plugin*)(pb->moduleRefcon))->QuitNotify();
  178.     }
  179.  
  180.  
  181. static void OurATMHook(ModuleParamBlock* pb ENDP)
  182.     {
  183.     ((Plugin*)(pb->moduleRefcon))->ATMNotify();
  184.     }
  185.  
  186.  
  187. /*************************************************************************/
  188. /********************************* Plugin ********************************/
  189. /*************************************************************************/
  190.  
  191. /* Construct a Plugin object.  This is called once, from the OurModuleRoot
  192.  * function, when the module is initialized (i.e. at application startup time).
  193.  */
  194. Plugin::Plugin(const ArrangeCallbackTbl* theCalls)
  195.     {
  196.     // Record the callback table for future use.
  197.     calls = theCalls;
  198.     
  199.     /* These commands, if un-commented-out, register this plugin to be called
  200.      * by Arrange when various events occur.  For example, if you un-comment-out
  201.      * the call to SetClickHook, then Plugin::ClickNotify will be called
  202.      * whenever the user clicks in any of the locations described in the
  203.      * arClickLocation enum.
  204.      */
  205.     // calls->ui->SetClickHook(OurClickHook, 0, true);
  206.     // calls->ui->SetKeyHook  (OurKeyHook,   0, true, charFilter, keyFilter, modFilter);
  207.     // calls->ui->SetMenuHook (OurMenuHook,  0, true, whichCommand);
  208.     // calls->ui->SetFieldHook(OurFieldHook, 0, true, whichField);
  209.     // calls->ui->SetTopicHook(OurTopicHook, 0, true);
  210.     // calls->ui->SetTickHook (OurTickHook,  0, true);
  211.     // calls->ui->SetFileHook (OurFileHook,  0, true);
  212.     // calls->ui->SetQuitHook (OurQuitHook,  0, true);
  213.     // calls->ui->SetATMHook  (OurATMHook,   0, true);
  214.     
  215.     // Add an item to the About Plugins menu for this plugin.
  216.     calls->ui->AddMenuItem(mPluginAbout, "About Generic Plugin", 0, aboutCmdCode, 0);
  217.     
  218.     // Register ourselves to be called when our About command is chosen.
  219.     calls->ui->SetMenuHook(OurMenuHook, 0, true, aboutCmdCode);
  220.     } // Plugin constructor
  221.  
  222.  
  223. /* Dispose of a Plugin object.  This is called when Arrange terminates.  You
  224.  * should free up any data structures which you allocation in the Plugin
  225.  * constructor (above).
  226.  */
  227. Plugin::~Plugin()
  228.     {
  229.     } // ~Plugin
  230.  
  231.  
  232. /* This function is called whenever the user clicks in an "interesting place"
  233.  * in a document window.  It should return true if we handle the click, false
  234.  * (the normal case) when the click should be passed along to other plug-ins
  235.  * or to Arrange's normal event processing.  See the documentation for
  236.  * SetClickHook for more details.
  237.  */
  238. arHookResult Plugin::ClickNotify( arClickLocation loc, Point where,
  239.                                              Short modifiers, Short clickCount,
  240.                                              arNoteID note, arFieldID field,
  241.                                              arPathID path )
  242.     {
  243.     return false; // Let Arrange handle the event
  244.     } // ClickNotify
  245.  
  246.  
  247. /* This function is called whenever the user types a key which matches the
  248.  * filters we pass to SetKeyHook in Plugin's constructor.  It should return
  249.  * true if we handle the event, false (the normal case) when the event
  250.  * should be passed along to other plug-ins or to Arrange's normal event
  251.  * processing.  See the documentation for SetKeyHook for more details.
  252.  */
  253. arHookResult Plugin::KeyNotify(Short theChar, Short key, Short modifiers)
  254.     {
  255.     return false; // Let Arrange handle the event
  256.     } // KeyNotify
  257.  
  258.  
  259. /* This function is called whenever the user chooses a menu item for which
  260.  * we have registered (via the SetMenuHook function).  It should return true
  261.  * if we handle the command, false (the normal case) when the command should
  262.  * be passed along to other plug-ins or to Arrange's normal event processing.
  263.  * See the documentation for SetMenuHook for more details.
  264.  */
  265. arHookResult Plugin::MenuNotify( Integer commandCode, Integer commandParam,
  266.                                             Short modifiers )
  267.     {
  268.     /* If this is our About menu item, display our about-box dialog and return
  269.      * true to indicate we handled the command.
  270.      */
  271.     if (commandCode == aboutCmdCode)
  272.         {
  273.         Alert(ModuleRsrcID, nil);
  274.         return true;
  275.         }
  276.     else
  277.         return false; // Let Arrange handle the event
  278.     
  279.     } // MenuNotify
  280.  
  281.  
  282. /* If we register to recieve events for a field by calling SetFieldHook, this
  283.  * function will be called for any events in that field.  It should return
  284.  * false in almost all cases.  See the documentation for SetFieldHook for
  285.  * more details.
  286.  */
  287. arHookResult Plugin::FieldNotify( arNoteID note, arFieldID field,
  288.                                              arFieldAction action, const char* choiceText )
  289.     {
  290.     return false;
  291.     } // FieldNotify
  292.  
  293.  
  294. /* This function is called whenever the user switches windows or changes
  295.  * the current folder/topic/view in the front window.  See the documentation
  296.  * for SetTopicHook for more details.
  297.  */
  298. void Plugin::TopicNotify( arTopicID newTopic, arWindowID newWindow,
  299.                                   arTopicAction action )
  300.     {
  301.     } // TopicNotify
  302.  
  303.  
  304. /* This function is called periodically, whenever Arrange recieves a null
  305.  * event from the Event Manager.
  306.  */
  307. void Plugin::TickNotify()
  308.     {
  309.     } // TickNotify
  310.  
  311.  
  312. /* This function is called whenever various file-level events occur.  It
  313.  * should return true in almost all cases.  See the documentation for
  314.  * SetFileHook for more details.
  315.  */
  316. arHookResult Plugin::FileNotify(arFileAction action)
  317.     {
  318.     return true;
  319.     } // FileNotify
  320.  
  321.  
  322. /* This function is called if the user voluntarily quits Arrange.  It should
  323.  * return true to allow the user to quit, false to prevent it.  See the
  324.  * documentation for SetQuitHook for more details.
  325.  */
  326. arHookResult Plugin::QuitNotify()
  327.     {
  328.     return true;
  329.     } // QuitNotify
  330.  
  331.  
  332. /* This function is called whenever the user clicks in the menu bar or types
  333.  * a command key, just before processing the event.  It should do any fixing
  334.  * up of menus which might be necessary based on the current state of affairs.
  335.  * See the documentation for SetATMHook for more details.
  336.  */
  337. void Plugin::ATMNotify()
  338.     {
  339.     } // ATMNotify
  340.