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