[JVCL-Checkins] CVS: dev/help JvPlugin.dtx,NONE,1.1 JvPluginMan.dtx,NONE,1.1

[Marcel B. <jed...@us...>]

Update of /cvsroot/jvcl/dev/help
In directory sc8-pr-cvs1:/tmp/cvs-serv4540/dev/help

Added Files:
	JvPlugin.dtx JvPluginMan.dtx 
Log Message:
Copying/rewriting the plugins help from the original help file.

--- NEW FILE: JvPlugin.dtx ---
@@JvPlugin.pas
<GROUP $JVCL.FileRef>
Summary
  Contains all code for writing plugins.
<INCLUDE JVCL.UnitText.dtx>
Author
  Tim Sullivan
----------------------------------------------------------------------------------------------------
@@TJvPlugin
----------------------------------------------------------------------------------------------------
##JVCL:Class
<GROUP $JVCL.FormsAndApp.Application.Plugins>
Summary
  Plugin data module.
Description
  TJvPlugin is the base class for new plugins.

  TJvPlugin is not a component but a data module, and as such can contain non-visual components
  (such as TTable, TQuery and TImageList).

  Because it's not a component you can not find it on the component palette. Instead you should use
  File|New..., click on the 'Projects" tab and click on the 'JEDI Plugin Wizard'. This will generate
  a new project with a single unit containing a TJvPlugin data module.

  In addition a number of properties are provided to specify the identity of the plugin (ID,
  full name, version, author, copyright), commands added by the plugin, the number of instances
  of this plugin that are generated, reference to the host application and the plugin manager.

  For more information on writing plugins and make applications plugin enabled, take a look at
  Plugins.
## !!! TODO: link to the forthcoming plugins writing tutorial.
----------------------------------------------------------------------------------------------------
@@TJvPlugin.Author
Summary
  \Author of the plugin.
Description
  The \Author property contains the name of the author of this plugin.

  As a plugin writer you should set this to your name, your company name or both.

  The host application may read this property to provide additional information about a loaded
  plugin.
See Also
  Copyright
----------------------------------------------------------------------------------------------------
@@TJvPlugin.Commands
Summary
  Commands provided by the plugin.
Description
  The Commands property is a collection of commands provided by the plugin. A single plugin can
  provide zero or more commands.

  For each command you can specify a bitmap (the icon for the menu or button), it's caption, hint,
  custom data and the handler to execute when the command is requested by the host application.
See Also
  TJvPluginCommand
----------------------------------------------------------------------------------------------------
@@TJvPlugin.Copyright
Summary
  Copyright for the plugin.
Description
  The Copyright property contains the copyright notice for the plugin.

  As a plugin writer you may set this to any text you want (eg. 'Copyright © 2003 Project JEDI').

  The host application may read this property to provide additional information about a loaded
  plugin.
See Also
  Author
----------------------------------------------------------------------------------------------------
@@TJvPlugin.Description
Summary
  \Description of the plugin.
Description
  The \Description property contains the description of the plugin.

  As a plugin writer you should set this to a short (1 or 2 sentences) description of what 
  functionality the plugin provides.

  The host application may read this property to provide additional information about a loaded
  plugin.
----------------------------------------------------------------------------------------------------
@@TJvPlugin.PluginID
Summary
  Identification (name) of the plugin.
Description
  The PluginID property contains the ID (or name) of the plugin.
  
  As a plugin writer you must set this property to the name (it's not required to set this to the
  Name property or even to a valid Delphi identifier, i.e. spaces and other symbols are allowed) of
  the plugin. Make sure the identification will be unique. A recommended way of doing this would be
  to use an identification string in the form of 
  \<<I>company name or abbreviation</I>\><B>.</B>\<<I>plugin name</I>\>.

  The host application uses this property to display and identify which plugin(s) is/are loaded.
See Also
  PluginVersion
----------------------------------------------------------------------------------------------------
@@TJvPlugin.PluginVersion
Summary
  Version of the plugin.
Description
  The PluginVersion property contains the version of the plugin.

  As a plugin writer you should set this property to a string containing the version number. You are
  free to determine how you format the version number (e.g. \<<I>Major</I>\><B>.</B>\<<I>Minor</I>\>
  or \<<I>Major</I>\><B>.</B>\<<I>Minor</I>\><B>.</B>\<<I>Release</I>\>).

  The host application may use this property to display the version of the plugin.
----------------------------------------------------------------------------------------------------
@@TJvPlugin.OnConfigure
Summary
  Event called when the host requests to configure the plugin.
Description
  Write an OnConfigure event handler to provide a means of configuring the plugin. The host
  application will call the Configure method of the plugin, which in turn will trigger this event.
See Also
  Configure, OnInitialize
----------------------------------------------------------------------------------------------------
@@TJvPlugin.OnInitialize
Summary
  Event called when the host initializes the plugin.
Description
  Write an OnInitialize event handler to perform any additional setup steps. When this event is
  called, the HostApplication, Manager and FileName properties are already initialized and can thus
  be used by the event.

  The event is called in response to a call to Initialize, which is usually done by the host
  application as soon as the plugin is loaded.
See Also
  Initialize, OnConfigure
----------------------------------------------------------------------------------------------------
@@TJvPlugin.OnPluginMessage
Summary
  Event called when the host application sent a message.
Description
  Write an OnPluginMessage event handler to respond to message sent by the host application.
  Although you are free to determine to meaning of each message ID, the host application usually
  defines these message IDs.

  The host application has two means of sending a message:

  * <LINK TJvPluginManager.SendMessage, send a message to all loaded plugins>.
  * <LINK TJvPlugin.SendPluginMessage, send a message to a specific plugin>.
----------------------------------------------------------------------------------------------------
@@TJvPlugin.Configure
Summary
  Configures the plugin.
Description
  Configure is called by the host application to configure the plugin. As a plugin developer you
  could override this method, but it's better to just assign a handler to the OnConfigure event.
See Also
  OnConfigure
----------------------------------------------------------------------------------------------------
@@TJvPlugin.Initialize
Summary
  Initializes the plugin.
Description
  Initialize is called by the host application to initialize the plugin.

  As a plugin developer you could override this method, but it's better to just assign a handler to
  the OnInitialize event.

  As a host application developer you will generally not call this method yourself. Initialize is
  called automatically when the plugin manager loads the plugin.
----------------------------------------------------------------------------------------------------
@@TJvPlugin.SendPluginMessage
Summary
  Sends a message to this plugin.
Description
  SendPluginMessage is called by the host application to send a message to the plugin.

  As a plugin developer you should respond to the OnPluginMessage, rather than overriding this
  method. The meaning of the various message IDs are specified by the host application (check it's
  documentation to see which message you could receive and what the meaning of the second parameter
  is).

  As a host application developer you can either call this method for a specific plugin or you could
  <LINK TJvPluginManager.SendMessage, broadcast> the message to all loaded plugins. You are
  responsible of defining and documenting the meaning of the various message IDs you support.
See Also
  OnPluginMessage
----------------------------------------------------------------------------------------------------
@@TJvPlugin.HostApplication
Summary
  Reference to the TApplication object of the host.
Description
  HostApplication is a reference to the TApplication object of the host. You can both read and write
  to properties (including the MainForm) as well as call methods on this object.

  If you write a plugin to store an MDI child for the host application, you should assing the value
  of this property to your own Application variable and restore your Application variable before you
  destroy the plugin.
----------------------------------------------------------------------------------------------------
@@TJvPlugin.Manager
Summary
  Reference to the host's plugin manager.
Description
  Manager is a reference to the plugin manager of the host. You must typecast it as
  TJvPluginManager.
See Also
  TJvPluginManager
----------------------------------------------------------------------------------------------------
@@TJvPlugin.Filename
Summary
  Holds the filename of the plugin.
Description
  Filename holds the filename of the plugin after it is loaded. This can be usefull to check if the
  plugin hasn't been renamed.
----------------------------------------------------------------------------------------------------
@@TJvPluginCommand
----------------------------------------------------------------------------------------------------
Summary
  A single plugin command.
Description
  TJvPluginCommand is single plugin command. Each plugin stores zero or more of the objects in their
  <LINK TJvPlgin.Commands, Commands> property.

  Generally speaking, each plugin usually represents a menu item, a button or both. Because both
  menu items as well as buttons can have a bitmap, a plugin commands can specify a bitmap in
  addition to a caption and a hint text.

  A plugin is not required to have a command (a host may just send messages to the plugin), but
  usually it has at least one.
----------------------------------------------------------------------------------------------------
@@TJvPluginCommand.Bitmap
Summary
  The bitmap to show next to the caption.
Description
  Bitmap contains the bitmap to display next to the caption of the menu item or button. If the
  command has no bitmap associated with it, Bitmap may be set to <B>nil</B>.
See Also
  Caption, Hint
----------------------------------------------------------------------------------------------------
@@TJvPluginCommand.Caption
Summary
  The caption of the command.
Description
  The Caption property contains the string to use as the caption of the menu item or button. It may
  contain an accelerator ('&').
See Also
  Bitmap, Hint
----------------------------------------------------------------------------------------------------
@@TJvPluginCommand.Data
Summary
  Custom data associated with the command.
Description
  Data contains custom data associated with the command. The meaning of this property will be
  defined by the host application. For example, a host application may require you to specify the
  full path where the menu item is to be inserted: 'Tools\Plugins\Advanced' will add the command
  to the Advanced sub menu of the Plugins submenu of the tools menu.
----------------------------------------------------------------------------------------------------
@@TJvPluginCommand.Hint
Summary
  The hint of the command.
Description
  The Hint property contains the hint text to use for the menu item or button. It's exactly the same
  as the standard Hint property for a menu item or button.
See Also
  Bitmap, Caption
----------------------------------------------------------------------------------------------------
@@TJvPluginCommand.Name
Summary
  The name of the command.
Description
  The Name property is used by the collection editor to identify the various plugins. It doesn't
  have to be a valid Delphi identifier (i.e. it may contains spaces and other symbols). It's
  generally not used by the host application.
----------------------------------------------------------------------------------------------------
@@TJvPluginCommand.OnExecute
Summary
  Event called when the command needs to be executed.
Description
  Write an OnExecute event hander to perform the command the user selects the menu item or button in
  the host application.
----------------------------------------------------------------------------------------------------
@@TJvPluginCommands
----------------------------------------------------------------------------------------------------
Summary
  Collection of plugin commands.
Description
  TJvPluginCommands a simple derivative of TCollection and holds a collection of TJvPluginCommand
  items. You can access this collection through the <LINK TJvPlugin.Commands, Commands> property of
  the <LINK TJvPlugin, plugin>.
See Also
  TJvPlugin, TJvPluginCommand, TJvPlugin.Commands

--- NEW FILE: JvPluginMan.dtx ---
@@JvPluginMan.pas
<GROUP $JVCL.FileRef>
Summary
  Contains all code to make an application plugin enabled.
<INCLUDE JVCL.UnitText.dtx>
Author
  Tim Sullivan
----------------------------------------------------------------------------------------------------
@@TJvPluginManager
----------------------------------------------------------------------------------------------------
##JVCL:Component
<GROUP $JVCL.FormsAndApp.Application.Plugins>
Summary
  Plugin manager.
Description
  TJvPluginManager is the plugin manager for an application. It's the core of a plugin enabled (or
  host) application.

  The component takes care of all the housekeeping involved in loading/unloading plugins and
  provides several properties and methods to load or unload plugins, configuring a plugin, sending
  messages to one plugin or all plugins or executing a command.

  Loaded plugins are stored in the Plugins property. You can access individual plugins much like you
  can access individual strings in TStrings object, e.g. Plugins[0].Configure.

  For more information on writing plugins and make applications plugin enabled, take a look at
  Plugins.
## !!! TODO: link to the forthcoming plugins writing tutorial.
----------------------------------------------------------------------------------------------------
@@TJvPluginManager.PluginFolder
Summary
  Folder to scan for plugins.
Description
  LoadPlugins reads this property to determine in which folder to scan for plugins.

  If this property is left blank, LoadPlugins will search in the folder where the application's
  executable is located, otherwise it will use whatever folder is put in this property.
See Also
  LoadPlugins, Extension
----------------------------------------------------------------------------------------------------
@@TJvPluginManager.Extension
Summary
  Extension of plugins to find.
Description
  LoadPlugins reads this property to determine the extension to use while scanning for plugins.
  
  By default this extension will be set to the extension belonging to the current type of plugins,
  as set by the PluginKind property. Changing \PluginKind will change the Extension property as
  well, provided it contains the extension belonging the previous PluginKind.
  
  If you change Extension to another extension you should not specify the dot. The extension will
  not change when you change the \PluginKind property.
----------------------------------------------------------------------------------------------------
@@TJvPluginManager.PluginKind
Summary
  Type of plugins to use when loading plugins.
Description
  LoadPlugins reads this property to determine the type of plugin to specify when loading the
  plugins that were found.
  
  When you change the value of this property and the Extension property contains the default
  extension for the old value, the \Extension will be changed to the default extension for the new
  plugin type.
See Also
  Extension, PluginFolder, LoadPlugins
----------------------------------------------------------------------------------------------------
@@TJvPluginManager.OnBeforeLoad
Summary
  Event called just before a plugin is loaded.
Description
  Write an OnBeforeLoad event handler to take additional action before a plugin is loaded. The
  Filename parameter contains the filename of the plugin about to be loaded. Set AllowLoad to False
  to prevent the plugin from being loaded (in which case the OnAfterLoad will not be triggered).
  
  The OnBeforeLoad event will only occur when LoadPlugins is used to scan for and load all plugins
  in a folder.
See Also
  OnAfterLoad, OnErrorLoading, OnNewCommand, LoadPlugins
----------------------------------------------------------------------------------------------------
@@TJvPluginManager.OnAfterLoad
Summary
  Event called when a plugin has loaded.
Description
  Write an OnAfterLoad event handler to take additional action when a plugin has been loaded. The S
  parameter will contain the filename of the loaded plugin.
  
  The OnAfterLoad event will only occur when LoadPlugins is used and if the loading of the plugin
  wasn't blocked by the OnBeforeLoad event.
See Also
  OnBeforeLoad, OnErrorLoading, OnNewCommand, LoadPlugins
----------------------------------------------------------------------------------------------------
@@TJvPluginManager.OnErrorLoading
Summary
  Event called when an exception has occured while loading a plugin.
Description
  Write an OnErrorLoading event handler to responds to exceptions while loading a plugin. The S
  parameter will contain the message of the exception.

  The OnErrorLoading event will only occur when an exception occurs while loading a plugin found by
  a call to LoadPlugins.
See Also
  OnAfterLoad, OnBeforeLoad, OnNewCommand, LoadPlugins
----------------------------------------------------------------------------------------------------
@@TJvPluginManager.OnNewCommand
Summary
  Event called for each command of a loaded plugin.
Description
  Write an OnNewCommand event handler to register a command in a loaded plugin. The event will be
  called for each command in each loaded plugin. The parameters contain the values of their
  respective properties in the command.
Parameters
  Sender -    Reference to the plugin manager component.
  ACaption -  The value of the command's <LINK TJvPluginCommand.Caption, Caption> property.
  AHint -     The value of the command's <LINK TJvPluginCommand.Hint, Hint> property.
  AData -     The value of the command's <LINK TJvPluginCommand.Data, Data> property.
  ABitmap -   The value of the command's <LINK TJvPluginCommand.Bitmap, Bitmap> property.
  AEvent -    The value of the command's <LINK TJvPluginCommand.OnExecute, OnExecute> event.
See Also
  OnAfterLoad, OnBeforeLoad, OnErrorLoading, LoadPlugins
----------------------------------------------------------------------------------------------------
@@TJvPluginManager.LoadPlugin
Summary
  Loads a plugin.
Description
  LoadPlugin will load the specified filename and treat it as the specified plugin type. If the file
  is not a valid plugin or an error occurs during loading and/or initializing, an exception will be
  raised.
  
  For each command the plugin provides, the OnNewCommand event is called.
See Also
  Plugins, LoadPlugins
----------------------------------------------------------------------------------------------------
@@TJvPluginManager.LoadPlugins
Summary
  Scans a folder for and loads plugins.
Description
  LoadPlugins will scan a folder for plugin files and attempts to load them.

  The PluginFolder property is read to determine the folder to scan. If the PluginFolder
  property is empty, the executable's folder will be used instead.
  
  The Extensions property is read to determine the file extensions to consider as a plugin.
  
  For each file found the following steps will take place:

  * The OnBeforeLoad event is called.
  * If \OnBeforeLoad has not disallowed the file to be loaded, LoadPlugin is called to load the
    plugin (specifying PluginKind as the plugin type). This method will call the OnNewCommand event
    for each provided command.
  * The OnAfterLoad event is called.

  If an exception occured during the steps above, the OnLoadingError event will be called. Any
  additional files will still be loaded.
See Also
  OnAfterLoad, OnBeforeLoad, OnErrorLoading, OnNewCommand, LoadPlugin, Extension, PluginFolder,
  PluginKind
----------------------------------------------------------------------------------------------------
@@TJvPluginManager.UnloadPlugin
Summary
  Unloads the specified plugin.
Description
  UnloadPlugin will unload the plugin at the specified index.
See Also
  LoadPlugin, Plugins, PluginCount
----------------------------------------------------------------------------------------------------
@@TJvPluginManager.GetLoadedPlugins
Summary
  Fills the specified string list with the names of the loaded plugins.
Description
  GetLoadedPlugins will fill the specified string list with the names of all loaded plugins. The
  specified string list must be provided by the caller. On entry the list will be cleared.