home *** CD-ROM | disk | FTP | other *** search
/ Chip 1997 April / Chip_1997-04_cd.bin / prezent / cb / data.z / TOOLINTF.PAS < prev    next >
Pascal/Delphi Source File  |  1997-01-16  |  23KB  |  467 lines
  1.  
  2. {*******************************************************}
  3. {                                                       }
  4. {       Delphi Visual Component Library                 }
  5. {                                                       }
  6. {       Copyright (c) 1995,1996 Borland International   }
  7. {                                                       }
  8. {*******************************************************}
  9.  
  10. unit ToolIntf;
  11.  
  12. interface
  13.  
  14. uses Windows, Classes, VirtIntf, EditIntf, FileIntf;
  15.  
  16. type
  17.   TIMenuItemIntf = class;
  18.  
  19.   TIMenuFlag = (mfInvalid, mfEnabled, mfVisible, mfChecked, mfBreak, mfBarBreak,
  20.     mfRadioItem);
  21.   TIMenuFlags = set of TIMenuFlag;
  22.  
  23.   TIMenuClickEvent = procedure (Sender: TIMenuItemIntf) of object;
  24.  
  25.   { The TIMenuItemIntf class is created by Delphi.  This is simply a virtual
  26.     interface to an actual menu item found in the IDE. It is the responsibility
  27.     of the client to destroy *all* menu items which it created.  Failure to
  28.     properly clean-up will result in unpredictable behaviour.
  29.  
  30.     NOTE: Using functions that returns a TIMenuItemIntf should be done with
  31.           care. Unless created by a particular add-in tool, do not hold these
  32.           interfaces for long as the underlying actual VCL TMenuItem may be
  33.           destroyed without any notification.  In practice, this only pertains
  34.           to Delphi created menus or menus created by other add-in tools.
  35.           It is also the responsibility of the user to free these interfaces
  36.           when finished. Any attempt to modify a menu item that was created
  37.           by Delphi will fail.
  38.  
  39.     DestroyMenuItem  - If this menu was created by through the interface, use
  40.                        this function to destroy the associated menu item.  This
  41.                        function will *not* allow any Delphi created menus to
  42.                        be destroyed.
  43.  
  44.     GetItemCount
  45.     GetItem          - Use these functions to iterate through the menu tree.
  46.                        All TIMenuItemIntfs must be freed by the caller.
  47.  
  48.     GetName          - Returns the menu item name associated with the VCL menu
  49.                        object. (Including internal Delphi menu names).
  50.  
  51.     GetParent        - Returns an interface to the parent menu item.
  52.  
  53.     GetCaption
  54.     SetCaption       - Methods to get/set the caption of the menu item.
  55.  
  56.     GetShortCut
  57.     SetShortCut      - Methods to get/set the short cut of the menu item.
  58.  
  59.     GetFlags
  60.     SetFlags         - Use GetFlags and SetFlags to query and set the state of
  61.                        the menu item.  For SetFlags, a mask indicating which
  62.                        items to affect must be passed along with the actual
  63.                        value of the flag.
  64.  
  65.     GetGroupIndex
  66.     SetGroupIndex    - Methods to get/set the GroupIndex property of a
  67.                        TMenuItem. This is useful for specifying values for
  68.                        grouped radio menus.
  69.     GetHint
  70.     SetHint          - Methods to get/set the Hint proeprty of a TMenuItem.
  71.                        NOTE: The IDE currently ignores this property.
  72.  
  73.     GetContext
  74.     SetContext       - Methods to get/set the help context ID of a TMenuItem.
  75.  
  76.     GetOnClick
  77.     SetOnClick       - Methods to get/set the OnClick property if the TMenuItem.
  78.  
  79.     InsertItem       - Creates and inserts a new sub menu item into the menu.
  80.                        If (Index < 0) or (Index >= ItemCount) then the
  81.                        operation is an append.
  82.   }
  83.  
  84.   TIMenuItemIntf = class(TInterface)
  85.   public
  86.     function DestroyMenuItem: Boolean; virtual; stdcall; abstract;
  87.     function GetIndex: Integer; virtual; stdcall; abstract;
  88.     function GetItemCount: Integer; virtual; stdcall; abstract;
  89.     function GetItem(Index: Integer): TIMenuItemIntf; virtual; stdcall; abstract;
  90.     function GetName: string; virtual; stdcall; abstract;
  91.     function GetParent: TIMenuItemIntf; virtual; stdcall; abstract;
  92.     function GetCaption: string; virtual; stdcall; abstract;
  93.     function SetCaption(const Caption: string): Boolean; virtual; stdcall; abstract;
  94.     function GetShortCut: Integer; virtual; stdcall; abstract;
  95.     function SetShortCut(ShortCut: Integer): Boolean; virtual; stdcall; abstract;
  96.     function GetFlags: TIMenuFlags; virtual; stdcall; abstract;
  97.     function SetFlags(Mask, Flags: TIMenuFlags): Boolean; virtual; stdcall; abstract;
  98.     function GetGroupIndex: Integer; virtual; stdcall; abstract;
  99.     function SetGroupIndex(GroupIndex: Integer): Boolean; virtual; stdcall; abstract;
  100.     function GetHint: string; virtual; stdcall; abstract;
  101.     function SetHint(Hint: string): Boolean; virtual; stdcall; abstract;
  102.     function GetContext: Integer; virtual; stdcall; abstract;
  103.     function SetContext(Context: Integer): Boolean; virtual; stdcall; abstract;
  104.     function GetOnClick: TIMenuClickEvent; virtual; stdcall; abstract;
  105.     function SetOnClick(Click: TIMenuClickEvent): Boolean; virtual; stdcall; abstract;
  106.     function InsertItem(Index: Integer; Caption, Name, Hint: string;
  107.       ShortCut, Context, GroupIndex: Integer; Flags: TIMenuFlags;
  108.       EventHandler: TIMenuClickEvent): TIMenuItemIntf; virtual; stdcall; abstract;
  109.   end;
  110.  
  111.   { The TIMainMenuIntf class represents the Delphi main menu.
  112.  
  113.     GetMenuItems     - Returns the menu representing the top level menus.
  114.  
  115.     FinMenuItem      - Given the VCL component name, returns the corresponding
  116.                        TIMenuItemIntf.
  117.   }
  118.  
  119.   TIMainMenuIntf = class(TInterface)
  120.   public
  121.     function GetMenuItems: TIMenuItemIntf; virtual; stdcall; abstract;
  122.     function FindMenuItem(const Name: string): TIMenuItemIntf; virtual; stdcall; abstract;
  123.   end;
  124.  
  125.   { The TIAddInNotifier allows an add-in tool to register a descendant of this
  126.     type with Delphi in order to receive notifications about certian events
  127.     within Delphi.  It is the resposibility of the add-in tool to unregister
  128.     and free this class when shutting down.
  129.  
  130.     FileNotification   - Called whenever an operation is performed from the
  131.                          FileMenu (or through the TIToolInterface).
  132.       fnFileOpening    - The given filename is about to be opened. Set
  133.                          Cancel to True to prevent the operation.
  134.       fnFileOpened     - The given file has been successfully opened.
  135.                          Modifications to Cancel have no effect.
  136.       fnFileClosing    - The given file is about to be closed.  Set Cancel
  137.                          to True to prevent the file from closing.
  138.       fnProjectOpening - The given project is about to be opened.  Set
  139.                          Cancel to True to prevent the operation.
  140.       fnProjectOpened  - The given project has been successfully opened.
  141.                          Modifications to Cancel have no effect.
  142.       fnProjectClosing - The given project is about to be closed.  Set
  143.                          Cancel to True to prevent the project from closing.
  144.       fnAddedToProject - The given file was added to the project.
  145.       fnRemovedFromProject - The given file was removed from the project.
  146.       fnDefaultDesktopSave
  147.       fnDefaultDekstopLoad
  148.       fnProjectDesktopSave
  149.       fnProjectDesktopLoad - The given filename represents a desktop is
  150.                              being loaded or saved.  The desktop file is
  151.                              in standard .INI file format. Add in written
  152.                              using Delphi can use the TIniFile component
  153.                              to add and retrieve information from this file.
  154.                              Modifying Cancel has no effect;
  155.  
  156.       NOTE: Modifying Cancel should be done with care.  Multiple notifiers
  157.             could interact, yielding unpredictable results.  Notifiers are
  158.             called in the reverse order in which they are registered.  There
  159.             is also no way to guarantee the registration order of the
  160.             notifiers.
  161.   }
  162.  
  163.   TFileNotification = (fnFileOpening, fnFileOpened, fnFileClosing,
  164.     fnProjectOpening, fnProjectOpened, fnProjectClosing, fnAddedToProject,
  165.     fnRemovedFromProject, fnDefaultDesktopLoad, fnDefaultDesktopSave,
  166.     fnProjectDesktopLoad, fnprojectDesktopSave);
  167.  
  168.   TIAddInNotifier = class(TInterface)
  169.   public
  170.     procedure FileNotification(NotifyCode: TFileNotification;
  171.       const FileName: string; var Cancel: Boolean); virtual; stdcall; abstract;
  172.   end;
  173.  
  174.   { The Tool services object is created on the application side, and is
  175.     passed to the VCS/Expert Manager DLL during initialization.  Note that
  176.     the application is responsible for creating and freeing the interface
  177.     object, and the client should never free the interface.
  178.  
  179.     The following functions are available to the client:
  180.  
  181.     ( Actions )
  182.  
  183.     CloseProject     - returns True if no project open, or if the currently
  184.                        open project can be closed.
  185.  
  186.     OpenProject      - returns True if the named project can be opened.  Pass an
  187.                        empty string to create a new project and main form.
  188.  
  189.     OpenProjectInfo  - returns True if the named project file can be opened.
  190.                        This routine bypasses all the normal project load
  191.                        features (such as loading a desktop file, showing
  192.                        the source code, etc), and simply opens the .DPR and
  193.                        .DOF files.
  194.  
  195.     SaveProject      - returns True if the project is unmodified, if there
  196.                        is no project open, or if the open project can be saved.
  197.  
  198.     CloseFile        - returns True if the specified file is not currently
  199.                        open, or if it can be closed.
  200.  
  201.     OpenFile         - returns True if the specified file is already open
  202.                        or can be opened.
  203.  
  204.     ReloadFile       - returns True if the file is already open and was
  205.                        reloaded from disk.  (NOTE: This will not perform any
  206.                        checking of the current editor state).
  207.  
  208.     ModalDialogBox   - used by non-VCL DLL's to present a dialog box which is
  209.                        modal.  Note that DLLs written using VCL can simply call
  210.                        a form's ShowModal function.
  211.  
  212.     CreateModule     - Will create new module from memory images of the source
  213.                        and, optionally, the form file.  The TCreateModuleFlags are:
  214.       cmAddToProject - Add the new module to the currently open project.
  215.       cmShowSource   - Show the source file in the top-most editor window.
  216.       cmShowForm     - If a form is created, show it above the source.
  217.       cmUnNamed      - Will mark the module as unnamed which will cause the
  218.                        SaveAs dialog to show the first time the user attempts to
  219.                        save the file.
  220.       cmNewUnit      - Creates a new unit and adds it to the current project.
  221.                        NOTE: all other parameters are ignored.
  222.       cmNewForm      - Creates a new form and adds it to the current project.
  223.                        NOTE: all other parameters are ignored.
  224.       cmNewModel     - Creates a new Data Model and adds it to the current
  225.                        project. NOTE: all other parameters are ignored.
  226.       cmMainForm     - If the module includes a form, make it the main form of
  227.                        the currently open project. Only valid with the
  228.                        cmAddToProject option.
  229.       cmMarkModified - Will insure that the new module is marked as modified.
  230.       cmExisting     - Will Create a module from an existing file on disk
  231.  
  232.     CreateModuleEx   - New extended form of CreateModule.  This will return a
  233.                        TIModuleInterface. All CreateModes from CreateModule are
  234.                        supported with only the following differences:
  235.       cmExisting     - Will create an existing module from the given file
  236.                        system.
  237.       AncestorClass  - This must specify an existing base class in the project.
  238.                        (use the cmAddToProject flag to add a module to the
  239.                         project first).
  240.      CreateCppModule - same as CreateModuleEx but uses an additional 
  241.                        HdrSource module for the .pas or .h hdr file
  242.  
  243.  
  244.               NOTES:   Pass an empty string for the file system parameter in
  245.                        order to use the default file system.  The file system
  246.                        parameter *must* be a valid file system previously
  247.                        registered through the RegisiterFilesystem API.
  248.  
  249.     ( Informational )
  250.  
  251.     GetParentHandle  - returns a HWND, which should be used as the parent for
  252.                        any windows created by the client.
  253.  
  254.     GetProjectName   - returns a fully qualified path name of the currently
  255.                        open project file, or an empty string if no project is
  256.                        open.
  257.  
  258.     GetUnitCount     - returns the current number of units belonging to the
  259.                        project.
  260.  
  261.     GetUnitName      - returns a fully qualified name of the specified unit.
  262.  
  263.     GetVcsCount      - returns the current number of files in project that
  264.                        should be added to a vcs system
  265.  
  266.     GetVcsList       - returns a full list of files in project that should
  267.                        be added to vcs
  268.  
  269.     GetVcsName       - returns a fully qualified name of the specified unit.
  270.  
  271.     EnumProjectUnits - Calls EnumProc once for each unit in the project.
  272.  
  273.     GetFormCount     - returns the current number of forms belonging to the
  274.                        project.
  275.  
  276.     GetFormName      - returns a fully qualified name of the specified form
  277.                        file.
  278.  
  279.     GetCurrentFile   - returns a fully qualified name of the current file,
  280.                        which could either be a form or unit (.PAS).
  281.                        Returns a blank string if no file is currently selected.
  282.  
  283.     IsFileOpen       - returns True if the named file is currently open.
  284.  
  285.     GetNewModuleName - Automatically generates a valid Filename and Unit
  286.                        identifier.  Uses the same mechanism as used by the IDE.
  287.  
  288.     ( Component library interface )
  289.  
  290.     GetModuleCount   - Returns the number of currently installed modules in the
  291.                        component library.
  292.  
  293.     GetModuleName    - Returns then name of the module given its index.
  294.  
  295.     GetComponentCount- Returns the number of components installed in a particular
  296.                        module.
  297.  
  298.     GetComponentName - Returns the name of the component given its module index
  299.                        and index in that mnodule.
  300.  
  301.     ( Virtual file system interface )
  302.  
  303.     RegisterFileSystem   - Registers an externally defined file system.
  304.     UnRegisterFileSystem - UnRegisters an externally defined file system.
  305.  
  306.     ( Module Interfaces )
  307.  
  308.     GetModuleInterface - Return an module interface associated with the given
  309.                          file.  NOTE: This function returns the same interface
  310.                          instance for a given module, only the reference count
  311.                          is adjusted.  The user of this interface owns it and
  312.                          must call release when finished.
  313.  
  314.     GetFormModuleInterface - Return an module interface associated with the
  315.                             given form.  NOTE: See GetModuleInterface.
  316.  
  317.     ( Menu Interface )
  318.  
  319.     GetMainMenu        - Returns an interface to the IDE's main menu.
  320.                          See TIMainMenuIntf for details.
  321.  
  322.     ( Notification registration )
  323.  
  324.     AddNotifier        - Registers an instance of a descendant to TIAddIn-
  325.                          Notifier.
  326.     RemoveNotifier     - Removes a registered instance of a TIAddInNotifier.
  327.  
  328.     ( Pascal string handling functions )
  329.  
  330.     NOTE: These functions are provided for IDE add-in writers to use a language
  331.           other than Pascal. (C++, for example).  Add-in writers using Delphi
  332.           will never need to use these functions  (see doc about the ShareMem
  333.           unit and DELPHIMM.DLL)
  334.  
  335.     NewPascalString    - Allocates and returns a pascal long string from the
  336.                          provided PChar (char *, in C parlance).  Passing an
  337.                          empty string or nil for the PChar will return nil for
  338.                          the string (Pascal's equivilant of an empty string).
  339.  
  340.     FreePascalString   - Attempts to free the given Pascal string by
  341.                          decrementing the internal reference count and
  342.                          releasing the memory if the count returns to zero.
  343.  
  344.     ReferencePascalString - Increments the reference count of the given Pascal
  345.                             string.  This allows the calling function to
  346.                             manually extend the lifetime of the string.  NOTE:
  347.                             a corresponding call to FreePascalString must be
  348.                             made in order to actually release the string's
  349.                             memory.
  350.  
  351.     AssignPascalString - Assigns one Pascal string to another.  NOTE: NEVER
  352.                          directly assign Pascal strings to each other.  Doing
  353.                          so will orphan memory and cause a memory leak.  The
  354.                          destination may be referencing another string, so
  355.                          the reference count of that string must be decremented.
  356.                          Likewise, the reference count of the source string
  357.                          must be incremented.
  358.  
  359.     ( Error handling )
  360.  
  361.     RaiseException   - This will cause an Exception to be raised with the IDE
  362.                        with the string passed to this function.  ***NOTE: This
  363.                        will cause the stack to unwind and control will **NOT**
  364.                        return to this point.  It is the resposibility of the
  365.                        Library to be sure it has correctly handled the error
  366.                        condition before calling this procedure.
  367.  
  368.     ( Configuration Access )
  369.  
  370.     GetBaseRegistryKey - returns a string representing the full path to
  371.                          Delphi's base registry key.  This key is relative
  372.                          to HKEY_CURRENT_USER.
  373.   }
  374.  
  375.   TCreateModuleFlag = (cmAddToProject, cmShowSource, cmShowForm,
  376.     cmUnNamed, cmNewUnit, cmNewForm, cmMainForm, cmMarkModified,
  377.     cmNewFile, cmExisting);
  378.   TCreateModuleFlags = set of TCreateModuleFlag;
  379.   TProjectEnumProc = function (Param: Pointer; const FileName, UnitName,
  380.     FormName: string): Boolean stdcall;
  381.  
  382.   TIToolServices = class(TInterface)
  383.   public
  384.     { Action interfaces }
  385.     function CloseProject: Boolean; virtual; stdcall; abstract;
  386.     function OpenProject(const ProjName: string): Boolean; virtual; stdcall; abstract;
  387.     function OpenProjectInfo(const ProjName: string): Boolean; virtual; stdcall; abstract;
  388.     function SaveProject: Boolean; virtual; stdcall; abstract;
  389.     function CloseFile(const FileName: string): Boolean; virtual; stdcall; abstract;
  390.     function SaveFile(const FileName: string): Boolean; virtual; stdcall; abstract;
  391.     function OpenFile(const FileName: string): Boolean; virtual; stdcall; abstract;
  392.     function ReloadFile(const FileName: string): Boolean; virtual; stdcall; abstract;
  393.     function ModalDialogBox(Instance: THandle; TemplateName: PChar;  WndParent: HWnd;
  394.       DialogFunc: TFarProc; InitParam: LongInt): Integer; virtual; stdcall; abstract;
  395.     function CreateModule(const ModuleName: string;
  396.       Source, Form: TIStream; CreateFlags: TCreateModuleFlags): Boolean;
  397.       virtual; stdcall; abstract;
  398.     function CreateModuleEx(const ModuleName, FormName, AncestorClass,
  399.       FileSystem: string; Source, Form: TIStream;
  400.       CreateFlags: TCreateModuleFlags): TIModuleInterface; virtual; stdcall; abstract;
  401.  
  402.     { Project/UI information }
  403.     function GetParentHandle: HWND; virtual; stdcall; abstract;
  404.     function GetProjectName: string; virtual; stdcall; abstract;
  405.     function GetUnitCount: Integer; virtual; stdcall; abstract;
  406.     function GetUnitName(Index: Integer): string; virtual; stdcall; abstract;
  407.     function EnumProjectUnits(EnumProc: TProjectEnumProc; Param: Pointer): Boolean;
  408.       virtual; stdcall; abstract;
  409.     function GetFormCount: Integer; virtual; stdcall; abstract;
  410.     function GetFormName(Index: Integer): string; virtual; stdcall; abstract;
  411.     function GetCurrentFile: string; virtual; stdcall; abstract;
  412.     function IsFileOpen(const FileName: string): Boolean; virtual; stdcall; abstract;
  413.     function GetNewModuleName(var UnitIdent, FileName: string): Boolean; virtual; stdcall; abstract;
  414.  
  415.     { Component Library interface }
  416.     function GetModuleCount: Integer; virtual; stdcall; abstract;
  417.     function GetModuleName(Index: Integer): string; virtual; stdcall; abstract;
  418.     function GetComponentCount(ModIndex: Integer): Integer; virtual; stdcall; abstract;
  419.     function GetComponentName(ModIndex, CompIndex: Integer): string; virtual; stdcall; abstract;
  420.     {function InstallModule(const ModuleName: string): Boolean; virtual; stdcall; abstract;
  421.     function CompileLibrary: Boolean; virtual; stdcall; abstract;}
  422.  
  423.     { Virtual File system interfaces }
  424.     function RegisterFileSystem(AVirtualFileSystem: TIVirtualFileSystem): Boolean; virtual; stdcall; abstract;
  425.     function UnRegisterFileSystem(const Ident: string): Boolean; virtual; stdcall; abstract;
  426.     function GetFileSystem(const Ident: string): TIVirtualFileSystem; virtual; stdcall; abstract;
  427.  
  428.     { Editor Interfaces }
  429.     function GetModuleInterface(const FileName: string): TIModuleInterface;
  430.       virtual; stdcall; abstract;
  431.     function GetFormModuleInterface(const FormName: string): TIModuleInterface;
  432.       virtual; stdcall; abstract;
  433.  
  434.     { Menu Interfaces }
  435.     function GetMainMenu: TIMainMenuIntf; virtual; stdcall; abstract;
  436.  
  437.     { Notification registration }
  438.     function AddNotifier(AddInNotifier: TIAddInNotifier): Boolean;
  439.       virtual; stdcall; abstract;
  440.     function RemoveNotifier(AddInNotifier: TIAddInNotifier): Boolean;
  441.       virtual; stdcall; abstract;
  442.  
  443.     { Pascal string handling functions }
  444.     function NewPascalString(Str: PChar): Pointer; virtual; stdcall; abstract;
  445.     procedure FreePascalString(var Str: Pointer); virtual; stdcall; abstract;
  446.     procedure ReferencePascalString(var Str: Pointer); virtual; stdcall; abstract;
  447.     procedure AssignPascalString(var Dest, Src: Pointer); virtual; stdcall; abstract;
  448.  
  449.     { Error handling }
  450.     procedure RaiseException(const Message: string); virtual; stdcall; abstract;
  451.  
  452.     { Configuration Access }
  453.     function GetBaseRegistryKey: string; virtual; stdcall; abstract;
  454. {$IFDEF PRONTO}
  455.     function CreateCppModule(const ModuleName, FormName, AncestorClass,
  456.       FileSystem: string; HdrSource, Source, Form: TIStream;
  457.       CreateFlags: TCreateModuleFlags): TIModuleInterface; virtual; stdcall; abstract;
  458.     function GetVcsCount: Integer; virtual; stdcall; abstract;
  459.     procedure GetVcsList(List: TStringList); virtual; stdcall; abstract;
  460.     function GetVcsName(Index: Integer): string; virtual; stdcall; abstract;
  461. {$ENDIF}
  462.   end;
  463.  
  464. implementation
  465.  
  466. end.
  467.