home *** CD-ROM | disk | FTP | other *** search
/ OpenStep 4.2J (Developer) / os42jdev.iso / NextLibrary / Frameworks / ProjectBuilder.framework / Versions / A / Headers / PBBundleHost.h < prev    next >
Encoding:
C/C++ Source or Header  |  1997-02-14  |  11.2 KB  |  240 lines
  1. // PBBundleHost.h - Functionality available to ProjectBuilder extension bundles
  2. //
  3. // Copyright 1995-1997 Apple Computer, Inc. (unpublished)
  4. // All rights reserved.
  5.  
  6. #import <Foundation/Foundation.h>
  7. #import "PBSystem.h"
  8.  
  9. #if defined(WIN32) || defined(__MACH__)
  10.  
  11. #import <AppKit/AppKit.h>
  12.  
  13. // PB Bundle Loading
  14. //    At launch time, a single PBBundleHost inside ProjectBuilder attempts to
  15. //    load all bundle wrappers specified in the user's preferences 
  16. //    (ProjectBuilder's "BundlesLoadedAtLaunch" preference).  Further, a set 
  17. //    of projectTypes are loaded from various locations.  Each projectType
  18. //    wrapper may contain a bundle executable that will be loaded at launch
  19. //    time.  Functionality in these bundles can be registered with the
  20. //    application via calls made from bundle initialization - the preferred
  21. //    method is +initialize on the bundle's principal class,
  22.  since +load can
  23. //    be fired too early before NSBundle methods are guaranteed to work.
  24. //    These calls should be made to the PBBundleHost, which is accessible as
  25. //    NSApp.
  26.  
  27.  
  28. // PB SCM Integration
  29. // The PBBundleHost can host bundles of any sort.  However, it is especially useful
  30. // for loading interfaces to Software Configuration Management systems.
  31. // The PBBundleHost interface was explicitly designed with this capability in mind.
  32. // To register an implementer of the PBConfigManager protocol, call
  33. // registerConfigManager: on the PBBundleHost.  Bundles providing a ConfigManager
  34. // are encouraged to also register a series of project- and file-specific
  35. // operations in PB's menus and provide an inspector panel.  Preferences specific
  36. // to the integration can be managed with a preferences panel registered with the
  37. // PBBundleHost.
  38.  
  39. @protocol PBConfigManager <NSObject>
  40. - (BOOL) managesPath: (NSString *) path;
  41.      // Should return YES iff this bundle can grant the user write permission to
  42.      // path under normal circumstances.  Should be a cheap call to just check
  43.      // if calling the following more expensive method has a chance in succeeding.
  44.  
  45. - (BOOL) makePathWritable: (NSString *) path;
  46.      // This actually requests the per-file "check out" from the SCM system.
  47.      // Called when a file transitions from saved to unsaved (dirty) state and
  48.      // the associated file is read only. Should return YES if file was made
  49.      // writable to PB.
  50. @end
  51.  
  52. // PB Panel Controllers
  53. // The PBBundleHost will inform controllers of inspector and preference views that
  54. // they are in need of refreshing their contents.  This might happen on initial
  55. // exposure of the panel or if relevant data affecting the browser changes
  56. // (e.g. the selected file/project, in the case of the inspector).
  57.  
  58. @interface PBInspectorController : NSObject
  59. {
  60.     NSWindow *window;
  61.     NSView *contentView;
  62.     id tool;
  63. }
  64. - (NSString *) inspectorName;
  65.      // Name that will appear on pop-up to select this panel.
  66. - (NSView *)contentView;
  67.    // Lazily called to provide panel as needed.
  68. - (void)revert;
  69.    // Called when panel displayed or relevant data changes (e.g. selectedFile)
  70. @end
  71.  
  72. // Preferences specific to the operation of a PB Bundle can be managed
  73. // and storing preferences as a sub-dictionary of PB's preferences, such as:
  74. //   [[NSUserDefaults standardUserDefaults] persistentDomainForName: @"MyConfigMgr"]
  75.  
  76. @interface PBPreferenceController : NSObject
  77. {
  78.     NSWindow *window;
  79.     NSView *contentView;
  80.     id prefController;
  81. }
  82. - (NSString *) viewName;
  83. - (NSView *)contentView;
  84. - (void)revert;
  85. @end
  86.  
  87.  
  88. @protocol PBBundleHost
  89. // Register bundle functionality
  90. - (BOOL) registerConfigManager: (id<PBConfigManager>) configManager;
  91. - (BOOL) registerProjectSubmenu: (NSMenu *) menu;
  92. - (BOOL) registerFileSubmenu: (NSMenu *) menu;
  93. - (BOOL) registerToolsSubmenu: (NSMenu *) menu;
  94. #ifdef NOT_IMPLEMENTED
  95. - (BOOL) registerInspectorController: (PBInspectorController *) inspector;
  96. - (BOOL) registerPreferenceController: (PBPreferenceController*) prefPanel;
  97. #endif
  98.  
  99. // Query app's state:
  100. - (NSString*) selectedProjectName;
  101.      // Returns name (as set in inspector panel) of the active project
  102. - (NSString*) selectedProject;
  103.      // Returns path to currently active project or nil if none.
  104. - (NSString*) currentlyActiveFile;
  105.      // Returns path to currently active file or nil if none.  This is the file
  106.      // that would receive key events from the user typing.
  107. - (NSArray*) selectedFiles;
  108.      // Returns array of paths for all currently selected files or nil if none.
  109. - (NSArray*) dirtiedFiles;
  110.      // Returns array of paths of files (including PB.project files)
  111.      // that are "unsaved".  Returns nil if none.
  112.  
  113. // Change app's state:
  114. - (BOOL) openFileOrProject: (NSString *) path;
  115.      // equivalent to using Cmd-D and typing in path
  116. - (BOOL) revertPath: (NSString *) path;
  117.      // Revert file or all files under directory named by path.
  118.      // If files have been modified releative to a loaded buffer, the user
  119.      // will be prompted to have the files re-loaded into PB.
  120.      // Returns YES on successful reload.
  121. - (BOOL) queryDirtiedFiles;
  122.      // Prompts user to save all files and projects with dirtied buffers.
  123.      // Returns YES if any files were saved.
  124. - (NSTextView*) viewForFile: (NSString *) path;
  125.      // Calls openFileOrProject: on path if not already loaded.
  126.      // Returns nil if file could not be loaded as text.  This
  127.      // allows access to the underlying file contents, the selection, and
  128.      // the associated NSTextStorage.  Files can be edited programmatically
  129.      // this way.
  130.  
  131. // Project editing:
  132. - (BOOL) addFileWithPath: (NSString *) filePath
  133.                toProject: (NSString *) projectPath;
  134. - (BOOL) removeFileFromProject: (NSString *) filePath;
  135. @end
  136.  
  137. #endif
  138.  
  139. // PB Notifications
  140. // The following notifications can be observed by PB Bundles from the
  141. // [NSNotificationCenter defaultCenter].  The following notification names
  142. // may be used.  The object provided in the subscription to the notification
  143. // should be nil to get all notifications or an NSString containing the path
  144. // to the file or "PB.project" project file in which the observer is specifically
  145. // interested.  The object of the notifications is an NSString containing the
  146. // path of the referenced file or project.
  147.  
  148. // Top-level Project Notifications:
  149. // The following four notifications are only sent for top-level projects.  
  150. // The top-level project represents the document that is openned and closed
  151. //  in PB and these notifications are document-oriented.  The object of these
  152. // notifications is the instance of PBProject corresponding to the top-level PB.project.
  153. // NOTE: only one PBProject object can exist for a given PB.project file.
  154. PB_EXTERN NSString * PBProjectWillOpenNotification; 
  155. PB_EXTERN NSString * PBProjectDidOpenNotification;
  156.  
  157. PB_EXTERN NSString * PBProjectWillCloseNotification;
  158. PB_EXTERN NSString * PBProjectDidCloseNotification;
  159.  
  160. // Project Upgrade Notifications:
  161. // PB.project files prior to 4.1 get automatically upgraded in-memory upon being
  162. // opened in ProjectBuilder.  This does not trigger an auto-save of the file as a
  163. // normal modification would, but these notifications are sent.   The object of these
  164. // notifications is the instance of PBProject corresponding to the upgraded PB.project.
  165. PB_EXTERN NSString * PBProjectWillUpgradeNotification;
  166. PB_EXTERN NSString * PBProjectDidUpgradeNotification;
  167.  
  168. // Project Change Notifications:
  169. // When the ProjectBuilder user modifies a project definition (e.g. adds a file,
  170. // changes a build flag, marks a resource as localizable), the project document
  171. // gets dirtied and PBProjectDidChangeNotification is sent.  An auto-save is normally
  172. // then scheduled, eventually resulting in PBProjectWillSaveNotification and culimnates
  173. // in either a PBProjectDidSaveNotification or PBProjectSaveDidFailNotification.
  174. // The object of these notifications is the instance of PBProject corresponding to the 
  175. // PB.project file.
  176. PB_EXTERN NSString * PBProjectDidChangeNotification;
  177. PB_EXTERN NSString * PBProjectWillSaveNotification;
  178. PB_EXTERN NSString * PBProjectDidSaveNotification;
  179. PB_EXTERN NSString * PBProjectSaveDidFailNotification;
  180.  
  181. // Project FileSet Change Notifications
  182. // Because adding and removing files from a project are significant events with respect
  183. // to integrating an SCM system, these special notifications are sent out in addition to
  184. // the normal PBProjectDidChangeNotification.  The object of these notifications is the
  185. // instance of PBProject corresponding to the PB.project file.  Additionally, a "userInfo"
  186. // dictionary is attached with: 
  187. //   {"file" = name of file added/deleted, 
  188. //    "key" = the category of the file in the project 
  189. //                   (i.e. one of the Project File Keys declared in PBProject.h)
  190. //   }.
  191. PB_EXTERN NSString * PBFileAddedToProjectNotification;
  192. PB_EXTERN NSString * PBFileRemovedFromProjectNotification;
  193.  
  194. // File Viewing Notifications:
  195. // As files are loaded and unloaded from buffers in PB, the following notifications are sent,
  196. // with the object of the notification a string containing the path of the file.
  197. PB_EXTERN NSString * PBFileWillOpenNotification;
  198. PB_EXTERN NSString * PBFileDidOpenNotification;
  199. PB_EXTERN NSString * PBFileWillCloseNotification;
  200. PB_EXTERN NSString * PBFileDidCloseNotification;
  201.  
  202. // File Editing/Saving Notifications:
  203. // These notifications are sent as files are transitioned into an unsaved or dirtied state
  204. // (PBFileDidChangeNotification) and saved by the user (PBFileWillSaveNotification
  205. // before and either PBFileDidSaveNotification or PBFileSaveDidFailNotification
  206. // afterwards).  Files can be reverted back to their saved copy (PBFileWillRevertNotification
  207. // and PBFileDidRevertNotification) as well.
  208. PB_EXTERN NSString * PBFileDidChangeNotification;  // buffer dirtied
  209. PB_EXTERN NSString * PBFileWillSaveNotification;
  210. PB_EXTERN NSString * PBFileDidSaveNotification;
  211. PB_EXTERN NSString * PBFileSaveDidFailNotification;
  212. PB_EXTERN NSString * PBFileWillRevertNotification;
  213. PB_EXTERN NSString * PBFileDidRevertNotification;
  214.  
  215. // File Delete/Move Notifications:
  216. // After a file is removd from disk or renamed, the following notifications are sent. As
  217. // above the object of the notification a string containing the path of the file.  In the case,
  218. // of rename, a userInfo dictionary is attached containing: { "NewFilePath" = <new path>; }.
  219. PB_EXTERN NSString * PBFileDeletedNotification;
  220. PB_EXTERN NSString * PBFileRenamedNotification;
  221.  
  222. // Project Build Notifications:
  223. // As builds are accomplished from within PB, notifications are sent alerting
  224. // subscribers of status changes to this operation.  The object is the string containing
  225. // the project path.
  226. PB_EXTERN NSString * PBProjectBuildWillBeginNotification;
  227. PB_EXTERN NSString * PBProjectBuildDidBeginNotification;
  228. PB_EXTERN NSString * PBProjectBuildDidSucceedNotification;
  229. PB_EXTERN NSString * PBProjectBuildDidFailNotification;
  230. PB_EXTERN NSString * PBProjectBuildDidStopNotification;
  231.  
  232. // File Browser Notifications
  233. // As the user navigates around the project and file hierarchy in the project 
  234. // window browser, the following notifications are sent so that open panels can
  235. // track the selection in the browser.  As a new project is clicked into, 
  236. // PBSelectedProjectDidChangeNotification is sent with the path of the project or
  237. // subproject.  As a new file is selected, the PBSelectedFileDidChangeNotification
  238. // object denotes the path of the selected file.
  239. PB_EXTERN NSString * PBSelectedProjectDidChangeNotification;
  240. PB_EXTERN NSString * PBSelectedFileDidChangeNotification;
  241.  
  242.