Source code of Windows XP (NT5)
You can not select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.

655 lines
17 KiB

  1. /**********************************************************************/
  2. /** Microsoft Windows NT **/
  3. /** Copyright(c) Microsoft Corp., 1992 **/
  4. /**********************************************************************/
  5. /*
  6. uix.hxx
  7. This file contains the class declarations for the classes related
  8. to NETUI Application Extension management.
  9. There are three categories of objects used to manipulate application
  10. extensions:
  11. Objects derived from UI_EXT represent the actual extensions.
  12. There is one such object for each extension loaded into the
  13. application. All extension manipulation (activate, refresh,
  14. unload, etc) occur through these objects.
  15. Objects derived from UI_EXT_MGR represent extension managers.
  16. There is at most one extension manager "active" at any given
  17. time. The extension manager is responsible for maintaining
  18. the list of extension objects and sending any "broadcast"
  19. notifications to each object.
  20. Objects derived from UI_EXT_MGR_IF represent extension manager
  21. interfaces. These objects act as an interface between the
  22. extension manager and the application. Whenever the extension
  23. manager needs to interact with the application (such as retrieving
  24. the list of available extensions) it is done through the interface
  25. object.
  26. The class hierarchy is structured as follows:
  27. BASE
  28. |
  29. +---UI_EXT
  30. | |
  31. | +---UI_BUTTON_EXT
  32. | |
  33. | +---UI_MENU_EXT
  34. | |
  35. | \---UI_TOOLBAR_EXT
  36. |
  37. +---UI_EXT_MGR
  38. | |
  39. | +---UI_BUTTON_EXT_MGR
  40. | |
  41. | +---UI_MENU_EXT_MGR
  42. | |
  43. | \---UI_TOOLBAR_EXT_MGR
  44. |
  45. \---UI_EXT_MGR_IF
  46. NOTE: At the time this module was written (19-Oct-1992) only the
  47. MENU derivitives of UI_EXT and UI_EXT_MGR were implemented.
  48. The BUTTON and TOOLBAR class are shown in the above hierarchy
  49. for illustration purposes only.
  50. To integrate extension support into an application:
  51. 0. Subclass one of the UI_*_EXT classes (such as UI_MENU_EXT)
  52. to create an extension class for the particular application.
  53. For example, the Server Manager subclasses UI_MENU_EXT into
  54. SM_MENU_EXT.
  55. The class constructor is responsible for loading the DLL,
  56. validating the entrypoints, and negotiating the version
  57. number.
  58. The class destructor is responsible for sending any unload
  59. notifications to the extension.
  60. Override all of the pure virtuals in the parent class, such
  61. as Refresh() and Activate().
  62. 1. Subclass UI_EXT_MGR_IF to create an interface for the
  63. particular application. For example, the NetUI Admin App
  64. "framework" subclasses UI_EXT_MGR_IF into AAPP_EXT_MGR_IF.
  65. Override all of the pure virtuals in the parent class. For
  66. example, AAPP_EXT_MGR_IF "thunks" these virtuals over to
  67. corresponding ADMIN_APP virtuals.
  68. 2. At an appropriate time in the application, create a new
  69. *_EXT_MGR_IF object, then create a new UI_*_EXT_MGR object,
  70. giving it the address of the interface object. The two are
  71. now bound together.
  72. 3. Invoke UI_*_EXT_MGR::LoadExtensions(). The extensions will
  73. be loaded.
  74. 4. At an appropriate time in the application, invoke the
  75. UI_*_EXT_MGR::ActivateExtension() method. For example,
  76. ADMIN_APP does this in OnMenuCommand() if the menu ID is
  77. greater than some specific value (the initial ID delta).
  78. FILE HISTORY:
  79. KeithMo 19-Oct-1992 Created.
  80. */
  81. #ifndef _UIX_HXX_
  82. #define _UIX_HXX_
  83. #include "base.hxx"
  84. #include "slist.hxx"
  85. #include "strlst.hxx"
  86. //
  87. // Forward references.
  88. //
  89. DLL_CLASS UI_EXT; // an extension
  90. DLL_CLASS UI_EXT_MGR; // an extension manager
  91. DLL_CLASS UI_EXT_MGR_IF; // an extension manager interface
  92. DLL_CLASS UI_MENU_EXT; // a menu extension
  93. /*************************************************************************
  94. NAME: UI_EXT
  95. SYNOPSIS: This abstract class represents a single instance of an
  96. application extension. This generic class is designed
  97. to be subclassed into more specific classes, such as
  98. UI_MENU_EXT.
  99. INTERFACE: UI_EXT - Class constructor (protected).
  100. ~UI_EXT - Class destructor.
  101. QueryVersion - Returns the version number
  102. associated with this extension.
  103. QueryHandle - Returns the DLL module handle
  104. of this extension.
  105. QueryDelta - Returns the menu/control ID delta
  106. associated with this extension.
  107. Refresh - Send a refresh notification to
  108. the extension.
  109. Activate - Activate the extension.
  110. PARENT: BASE
  111. HISTORY:
  112. KeithMo 19-Oct-1992 Created.
  113. KeithMo 26-Oct-1992 Keep the DLL name, in case we need it.
  114. **************************************************************************/
  115. DLL_CLASS UI_EXT : public BASE
  116. {
  117. private:
  118. //
  119. // The version number this extension supports. This
  120. // value is negotiated between the extension and the
  121. // application at extension load time.
  122. //
  123. DWORD _dwVersion;
  124. //
  125. // The name of this extension's DLL.
  126. //
  127. NLS_STR _nlsDllName;
  128. //
  129. // The handle to this extension's DLL.
  130. //
  131. HMODULE _hDll;
  132. //
  133. // The menu/control ID delta for this extension.
  134. //
  135. DWORD _dwDelta;
  136. protected:
  137. //
  138. // Protected accessors.
  139. //
  140. VOID SetVersion( DWORD dwVersion )
  141. { _dwVersion = dwVersion; }
  142. APIERR SetDllName( const TCHAR * pszDllName )
  143. { return _nlsDllName.CopyFrom( pszDllName ); }
  144. VOID SetDllHandle( HMODULE hDll )
  145. { _hDll = hDll; }
  146. //
  147. // Since this is an abstract class, the class constructor
  148. // is protected.
  149. //
  150. // The derived subclass's constructor is responsible for
  151. // loading & validating the DLL, negotiating the version
  152. // number, and setting the appropriate private data members
  153. // in this class.
  154. //
  155. UI_EXT( const TCHAR * pszDllName,
  156. DWORD dwDelta );
  157. public:
  158. //
  159. // The class destructor.
  160. //
  161. // The derived subclass's destructor is responsible for
  162. // sending any appropriate "unload" notifications to the
  163. // extension DLL. Note that ~UI_EXT() will perform the
  164. // actual FreeLibrary() on the DLL.
  165. //
  166. virtual ~UI_EXT( VOID );
  167. //
  168. // Public accessors.
  169. //
  170. DWORD QueryVersion( VOID ) const
  171. { return _dwVersion; }
  172. const TCHAR * QueryDllName( VOID ) const
  173. { return _nlsDllName; }
  174. HMODULE QueryDllHandle( VOID ) const
  175. { return _hDll; }
  176. DWORD QueryDelta( VOID ) const
  177. { return _dwDelta; }
  178. //
  179. // These virtuals must be overridden by the derived subclass(es).
  180. //
  181. // Refresh() simply notifies the extension DLL that the user is
  182. // requesting a refresh. The extension may take this opportunity
  183. // to refresh any cached data values.
  184. //
  185. // Activate() activates the extension (duh...) which will typically
  186. // invoke a dialog.
  187. //
  188. virtual VOID Refresh( HWND hwndParent ) const = 0;
  189. virtual VOID Activate( HWND hwndParent, DWORD dwId ) const = 0;
  190. }; // class UI_EXT
  191. DECL_SLIST_OF( UI_EXT, DLL_BASED );
  192. /*************************************************************************
  193. NAME: UI_MENU_EXT
  194. SYNOPSIS: This abstract class represents a single instance of a
  195. menu extension. This must be subclasses to provide
  196. application-specific behaviour.
  197. INTERFACE: UI_MENU_EXT - Class constructor (protected).
  198. ~UI_MENU_EXT - Class destructor.
  199. Refresh - Send a refresh notification to
  200. the extension.
  201. Activate - Activate the extension.
  202. MenuInit - Sends a menu init notification
  203. to the extension.
  204. PARENT: UI_EXT
  205. HISTORY:
  206. KeithMo 19-Oct-1992 Created.
  207. **************************************************************************/
  208. DLL_CLASS UI_MENU_EXT : public UI_EXT
  209. {
  210. private:
  211. //
  212. // The name of the menu item associated with this extension.
  213. //
  214. NLS_STR _nlsMenuName;
  215. //
  216. // Menu handle of the popup menu associated with this extension.
  217. //
  218. HMENU _hMenu;
  219. //
  220. // Private worker method for BiasMenuIds.
  221. //
  222. APIERR W_BiasMenuIds( HMENU hMenu,
  223. DWORD dwDelta );
  224. protected:
  225. //
  226. // Since this is an abstract class, the class constructor
  227. // is protected.
  228. //
  229. // The derived subclass's constructor is responsible for
  230. // loading & validating the DLL, negotiating the version
  231. // number, and setting the appropriate private data members
  232. // in this class.
  233. //
  234. UI_MENU_EXT( const TCHAR * pszDllName,
  235. DWORD dwDelta );
  236. //
  237. // Protected accessors.
  238. //
  239. APIERR SetMenuName( const TCHAR * pszMenuName )
  240. { return _nlsMenuName.CopyFrom( pszMenuName ); }
  241. VOID SetMenuHandle( HMENU hMenu )
  242. { _hMenu = hMenu; }
  243. //
  244. // This method recursively applies the specified delta (bias)
  245. // to all menu ids in _hMenu.
  246. //
  247. APIERR BiasMenuIds( DWORD dwDelta );
  248. public:
  249. //
  250. // The class destructor.
  251. //
  252. // The derived subclass's destructor is responsible for
  253. // sending any appropriate "unload" notifications to the
  254. // extension DLL. Note that ~UI_EXT() will perform the
  255. // actual FreeLibrary() on the DLL.
  256. //
  257. virtual ~UI_MENU_EXT( VOID );
  258. //
  259. // These virtuals must be overridden by the derived subclass(es).
  260. //
  261. // Refresh() simply notifies the extension DLL that the user is
  262. // requesting a refresh. The extension may take this opportunity
  263. // to refresh any cached data values.
  264. //
  265. // Activate() activates the extension (duh...) which will typically
  266. // invoke a dialog.
  267. //
  268. // MenuInit() notifies the extension that the app's menu is being
  269. // initialized. The extension will typically use this opportunity
  270. // to manipulate the extension's menu items.
  271. //
  272. virtual VOID Refresh( HWND hwndParent ) const = 0;
  273. virtual VOID Activate( HWND hwndParent, DWORD dwId ) const = 0;
  274. virtual VOID MenuInit( VOID ) const = 0;
  275. //
  276. // Public accessors.
  277. //
  278. const TCHAR * QueryMenuName( VOID ) const
  279. { return _nlsMenuName.QueryPch(); }
  280. HMENU QueryMenuHandle( VOID ) const
  281. { return _hMenu; }
  282. }; // class UI_MENU_EXT
  283. /*************************************************************************
  284. NAME: UI_EXT_MGR
  285. SYNOPSIS: This class represents an extension manager. It is used
  286. to manipulate application extension objects derived from
  287. UI_EXT.
  288. INTERFACE: UI_EXT_MGR - Class constructor.
  289. ~UI_EXT_MGR - Class destructor.
  290. QueryDelta - Returns the menu/control ID delta
  291. to be used for the *next* extension.
  292. QueryDeltaDelta - Returns the "inter-delta offset".
  293. LoadExtensions - Load all extensions.
  294. UnloadExtensions - Unload all extensions.
  295. RefreshExtensions - Refresh all extensions.
  296. ActiveExtension - Activate an extension by ID.
  297. PARENT: BASE
  298. HISTORY:
  299. KeithMo 19-Oct-1992 Created.
  300. **************************************************************************/
  301. DLL_CLASS UI_EXT_MGR : public BASE
  302. {
  303. private:
  304. //
  305. // This SLIST contains all of the currently loaded extensions.
  306. //
  307. SLIST_OF( UI_EXT ) _slExtensions;
  308. //
  309. // The interface between the manager & the application.
  310. //
  311. UI_EXT_MGR_IF * _pExtMgrIf;
  312. //
  313. // The current menu/control ID delta.
  314. //
  315. DWORD _dwDelta;
  316. //
  317. // This value is added to _dwDelta after each extension
  318. // is loaded. This is basically the offset "between" deltas.
  319. //
  320. DWORD _dwDeltaDelta;
  321. protected:
  322. //
  323. // This worker function will load a single extension by name.
  324. //
  325. virtual UI_EXT * W_LoadExtension( const TCHAR * pszExtensionDll,
  326. DWORD dwDelta );
  327. //
  328. // Protected accessors.
  329. //
  330. VOID SetDelta( DWORD dwDelta )
  331. { _dwDelta = dwDelta; }
  332. VOID SetDeltaDelta( DWORD dwDeltaDelta )
  333. { _dwDeltaDelta = dwDeltaDelta; }
  334. //
  335. // Subclasses need access to this so that they can iterate extensions
  336. //
  337. UI_EXT_MGR_IF * QueryExtMgrIf( VOID )
  338. { return _pExtMgrIf; }
  339. public:
  340. //
  341. // Usual constructor/destructor goodies.
  342. //
  343. UI_EXT_MGR( UI_EXT_MGR_IF * pExtMgrIf,
  344. DWORD dwInitialDelta,
  345. DWORD dwDeltaDelta );
  346. ~UI_EXT_MGR( VOID );
  347. //
  348. // Public accessors.
  349. //
  350. SLIST_OF( UI_EXT ) * QueryExtensions( VOID )
  351. { return &_slExtensions; }
  352. DWORD QueryDelta( VOID ) const
  353. { return _dwDelta; }
  354. DWORD QueryDeltaDelta( VOID ) const
  355. { return _dwDeltaDelta; }
  356. UINT QueryCount( VOID )
  357. { return _slExtensions.QueryNumElem(); }
  358. UI_EXT * FindExtensionByName( const TCHAR * pszDllName ) ;
  359. UI_EXT * FindExtensionByDelta( DWORD dwDelta ) ;
  360. //
  361. // These virtuals manipulate the extensions.
  362. //
  363. // LoadExtensions() causes all extensions to be loaded.
  364. //
  365. // UnloadExtensions() unloads all loaded extensions.
  366. //
  367. // RefreshExtensions() sends a refresh notification to all extensions.
  368. //
  369. // ActivateExtension() activates the extension with the given id.
  370. //
  371. virtual UINT LoadExtensions( VOID );
  372. virtual VOID UnloadExtensions( VOID );
  373. virtual VOID RefreshExtensions( HWND hwndParent );
  374. virtual VOID ActivateExtension( HWND hwndParent, DWORD dwId );
  375. }; // class UI_EXT_MGR
  376. /*************************************************************************
  377. NAME: UI_MENU_EXT_MGR
  378. SYNOPSIS: This class respresents a manager of menu extensions.
  379. It is used to manipulate application extension objects
  380. derived from UI_MENU_EXT.
  381. INTERFACE: UI_MENU_EXT_MGR - Class constructor.
  382. ~UI_MENU_EXT_MGR - Class destructor.
  383. MenuInitExtensions - Sends a menu init notification
  384. to all loaded extensions.
  385. PARENT: UI_EXT_MGR
  386. HISTORY:
  387. KeithMo 19-Oct-1992 Created.
  388. **************************************************************************/
  389. DLL_CLASS UI_MENU_EXT_MGR : public UI_EXT_MGR
  390. {
  391. private:
  392. protected:
  393. public:
  394. //
  395. // Usual constructor/destructor goodies.
  396. //
  397. UI_MENU_EXT_MGR( UI_EXT_MGR_IF * pExtMgrIf,
  398. DWORD dwInitialDelta,
  399. DWORD dwDeltaDelta );
  400. virtual ~UI_MENU_EXT_MGR( VOID );
  401. //
  402. // This virtual manipulates the extensions.
  403. //
  404. // MenuInitExtensions() sends a menu initialization notifications to
  405. // all extensions.
  406. //
  407. virtual VOID MenuInitExtensions( VOID );
  408. }; // class UI_MENU_EXT_MGR
  409. /*************************************************************************
  410. NAME: UI_EXT_MGR_IF
  411. SYNOPSIS: This abstract class represents an interface between an
  412. extension manager and the "owning" appliation.
  413. INTERFACE: UI_EXT_MGR_IF - Class constructor (protected).
  414. ~UI_EXT_MGR_IF - Class destructor.
  415. LoadExtension - Load a single extension by
  416. name.
  417. GetExtensionList - Returns the list of extension
  418. DLLs.
  419. PARENT: BASE
  420. HISTORY:
  421. KeithMo 19-Oct-1992 Created.
  422. **************************************************************************/
  423. DLL_CLASS UI_EXT_MGR_IF : public BASE
  424. {
  425. private:
  426. protected:
  427. //
  428. // Since this is an abstract class, the constructor is protected.
  429. //
  430. UI_EXT_MGR_IF( VOID );
  431. public:
  432. //
  433. // Class destructor.
  434. //
  435. ~UI_EXT_MGR_IF( VOID );
  436. //
  437. // Load a single extension.
  438. //
  439. virtual UI_EXT * LoadExtension( const TCHAR * pszExtensionDll,
  440. DWORD dwDelta ) = 0;
  441. //
  442. // Get the list of extension DLLs for this application.
  443. //
  444. virtual STRLIST * GetExtensionList( VOID ) = 0;
  445. //
  446. // Activate an extension.
  447. //
  448. virtual VOID ActivateExtension( HWND hwndParent,
  449. UI_EXT * pExt,
  450. DWORD dwId ) = 0;
  451. }; // class UI_EXT_MGR_IF
  452. #endif // _UIX_HXX_