http://www.yahoogroups.com/group/JEDI-VCL

This document is "inherited" from similar work done by the members of CompuServe Nantucket Forum (NANFORUM) for Clipper, and we would like to acknowledge it gratefully here.

When Project JEDI ("Joint Endeavor of Delphi Innovators) was formed in 1997 to translate API headers into Delphi, it was envisaged that component writing - especially wrappers for the API calls that are surfaced to Delphi through the translations - would eventually become a project activity. In our recent reassertion of the project's goals we confirmed that intention and expanded it to encompass the general world of free components. Project JEDI intends to work with Borland R & D and its Code Central repository project, as well as other developers and collectors of freeware components, to bring this work into easy reach of all Delphi developers.

1.2 Trademarks

Delphi is a registered trademark of Inprise Corporation. Inprise Corporation will be referred to as Borland throughout this document.

1.3 Relationship to Borland and third party

JEDI-VCL is a project independent of any third party developer or Borland. There is no official "sanction" or "seal of approval" from Borland. Any decision to accept and include a component into the JEDI-VCL components will be made without regard to the existence of components performing similar functions in any commercial or non-commercial third party or Borland product, provided no copyright or patent restrictions are violated.

The intention is not that JEDI-VCL should compete with third party products but, rather, that it fill in the holes in Borland Delphi's standard VCL library. Since overlaps of functionality already occur between other third-party libraries, it is considered impracticable to try to avoid them in our own considerations.

Developers submitting JEDI-VCL components may be corporate developers, third party developers, independent consultant/programmers, hobbyists or any other people developing in Delphi. Perhaps even Borland employees will contribute. No individual is precluded from contributing on the basis of a particular affiliation.

If Borland employees submit components, they would do so as individuals, with no implication made nor inference drawn that Borland was either involved in the project or is committed to supporting the public domain library.

Borland is permitted and encouraged to include free of charge any of the JEDI-VCL components in future releases of Delphi.

1.4 Borland Delphi versions supported

JEDI-VCL components will be designed to work with the version of Borland Delphi which is current at the time of release, as well as the previous one if that is technically possible. For example, at the time of this writing (September 1999) Delphi 5 (current) and Delphi 4 (previous) would be supported. Many of the components will be compatible with earlier versions of Borland Delphi. However, ensuring compatibility will be the responsibility of the user. A user wanting a component to work with other versions of Borland Delphi will have to make the necessary modifications to the source code. Nevertheless, a component's developer may choose to include compiler switches to provide compatibility with earlier versions, at his/her discretion. If support for prior versions is claimed, it will be tested and validated by Project JEDI.

Components published in the JEDI-VCL should work in the current retail release of Delphi. In cases where a component author does not have access to the current product release, Project JEDI will try to assist by arranging for testing by other members who have the current product release.

Project JEDI will provide on the Web an overview showing what product versions a published component was explicitly tested with. When a new Delphi version is released, this overview will be updated as the components are tested and verified against the new release.

Code needs periodic maintenance to stay "current" - it may still compile five versions later, but may not have kept up with evolving UI or coding style.

1.5 Queries from new users

Queries from new users interested in finding out about the JEDI-VCL should be handled in a uniform and courteous way. An information page will be created on this web site to explain what the JEDI-VCL is and how to contact the people currently maintaining it. A text message can be sent in response to any query.

JEDI-VCL, its source code, and documentation will be open source software. It is not for sale and shall not be sold. Project JEDI shall require no fee or contribution of any kind from anyone wanting to download the software from the Project JEDI web site. A procedure will be developed for submitting components through the web site.

2.2 Grouping Components into Packages

JEDI-VCL will be provided in separate functional packages. To ensure future compatibility, users of these packages will be required to distribute only the official JEDI released packages. This does not preclude developers from building their own packages from the individual components.

Currently we envisage following packages:

2.3.1 Contents

The deliverables that make up the official posting on Project JEDI Web site shall be:

2.3.1.1    JV-TMP.ZIP

Contains templates of the file and documentation header blocks, including samples for prospective authors (JV-TMP.HLP, JV-TMP.PAS)

2.3.1.2    JEDI-VCL100.ZIP

Main JEDI-VCL Library Release 1.0. It will contain all the packages, all components, and all documentation/Help files. Also included will be a short information file used as a response to new user queries (see paragraph 1.5)

2.3.1.3    JEDI XXX Library n for Delphi v.ZIP

This is the individual zipped package (see 2.2) Release <n.> for Delphi Release <v>. As stated in 1.4 the supported Delphi release will be the current and the previous one.

For example, a Zip file containing Release 1.0 of Internet components for Delphi 5 would be called:

"JEDI Internet Library 1.00 for Delphi 5.zip"

and would support Delphi 4 and Delphi 5.

2.3.1.4    JV_XXX.ZIP

Individual components, available for download separately from their respective packages. (e.g. JvWinSock.ZIP, normally part of the Internet package "JEDI Internet library 1.00 for Delphi 5.zip"). Developers may use them individually in their private packages.

2.3.1.5    Patch X for JEDI XXX Library n for Delphi v.ZIP

Patch files (e.g. "Patch 2 for JEDI Internet library 1.00 for Delphi 5.zip"- see 4.5.1).

If a need for a new component has been identified, Project JEDI will place a RFP on the Web site, and send email to JEDI members. In cases where a member identifies a need and submits a ready component, its files shall be included in the RFP as a "Proof of Concept".

3.2 "Best Component"

In the event that more than one developer submits components or packages that perform substantially the same services, referees will evaluate the alternatives according to their power, functionality, flexibility, and ease of use and choose the one to be included. Because of the cooperative, non-commercial nature of the library, no contributor should feel offended when duplicate components need to be excluded.

When benefit is perceived from merging two substantially similar components or packages to enhance functionality, the referees (see paragraph 6.3) may exercise their prerogative to do so. The authors would be closely involved in the process and the referees may choose to a Request for Comments (RFC) to gain additional information from the community and ensure a better design.

3.3 Legal License

Each author submitting source code must include as part of that code a statement that the work is original and that he or she is placing the code into the public domain, or releasing it under the MPL (see 5.1.1 and 5.1.2). The librarian (see paragraph 7.1) and referees should make a reasonable effort to ensure that no copyright source code, such as that supplied with some third party libraries, finds its way into the JEDI-VCL. However, under no circumstances will the librarian, referees, or any other party other than the submitter be responsible for copyright code that appears in the library accidentally.

3.4 Source code

The author must provide full source code for every routine to be included in JEDI-VCL. No routine will be considered for inclusion in the library if only compiled code (DCU/BPL) is submitted.

3.5 Proper submission

Librarians and referees shall not be expected to repair inconsistencies in documentation format, component naming, and other requirements. Source code which does not arrive in proper format will not be considered.

The expected files are:

• XXX.PAS (Main source file(s))
• XXX.DCR (Resource file(s))
• XXX_reg.PAS (Registration Unit for each individual component)
• XXX_Mreg.PAS (Multi registration unit - for use by packages, if they are included)
• XXX.HLP (Help file)
• XXX_Demo.ZIP (Demo project)
• XXX_D50.DPK (Design package)
• XXX_R50.DPK (RunTime Package)

Please note: we need separate registration units for individual components, as well as for packages, to allow users the choice of using the package provided by Project JEDI, or incorporating individual components into their private packages.

3.6 Quality and perceived usefulness

In a cooperative effort like this, it will be difficult to enforce some standard of quality and/or usefulness. For example, a component to handle the military's "Zulu time" may be very useful to some, and unnecessary to others.

By virtue of its origins, the JEDI-VCL will be a mixture of some components of very high quality and others perhaps not as fine. It is up to the users to improve it. It will be complete in some areas and quite sparse in others. It is up to the users to fill in the holes.

We shall err on the side of including "questionable" components, provided they seem to work. Debates on the quality of the library's source code will be encouraged and will take place in the proper message section of the JEDI-VCL Mailing list.

Source code will be submitted to the librarian, the documenter (see paragraph 7.2), or one of the referees. Code will be added after it is reviewed and approved by at least one, but preferably two, referees.

Code not meeting the documentation or source code formatting standards will usually be returned to the author with instructions.

Referees will test the submitted code. When the referees have finished evaluating a submission, they will report their approval or disapproval to the librarian, with comments.

4.2 Update interval

As new components are submitted and added to the library, the documentation will be updated. Because of the voluntary nature of this project and the complexity involved in coordinating testing, documentation, and delivery, there will be no fixed interval for updates. Once the process is well under control we will aim to do monthly updates.

4.3 Version control

JEDI-VCL packages will use a numeric version number as follows:

The major version will be numeric, corresponding to current Delphi release, starting from 4 (the previous (supported) Delphi release – see 1.4).  This will change with each Delphi release. The minor version will change with each update of the JEDI-VCL library package.

Typical version numbers might be 4.01, 4.11, 5.05, etc.

Each component that doesn’t descent from JvComponent should implement published property “AboutJVCL” as it is implemented in “JvComponent.pas”. This will enable the component to display its version at the design time.

4.4 Announcing updates

As the library and associated documentation are updated, simple announcements will be posted on the Project JEDI home page, Delphi newsgroups and the JEDI mailing list. These are the only places where updates will be announced. An update announcement indicates that it is immediately available for downloading from ftp://delphi-jedi.org and through links on the JEDI Web site.

4.5 Bug reports and fixes

The librarian will correlate and verify all bug reports, with the help of the referees. If the referees believe a bug to be serious, they will arrange to have it fixed and the librarian will release a maintenance upgrade immediately it is ready. If they consider it a minor bug, it will be fixed but not installed for release until the next scheduled upgrade. Such bug fixes may be released as "patches."

4.5.1 Patches

A "patch" is simply an ASCII text file containing instructions for editing the source code to a misbehaving component or group of components.

Patches may appear on the JEDI Web site before a maintenance release or quarterly upgrade. A patch file will be named according to this scheme: Patch X for JEDI XXX Library n for Delphi v.ZIP

where <X> is a number starting from 1. Patches will be numbered sequentially. Patches will be deleted every time a new version of JEDI-VCL package goes on-line.

4.6 Technical Support

Technical support will work just as any technical subject on the JEDI Web site works. Users will post questions and suggestions to a particular mailing list, and anyone who knows the answer should respond. No one is obliged to answer, but it is considered good form to respond with something, even if one doesn't know the answer.

Support will include help on recompiling the components or modifying the source.

4.7 C++ Builder Compatibility

In order to assist users of Borland C++Builder, JEDI-VCL may need to be tested with the current release of C++Builder, and modified as needed. This should be done by a dedicated team with C++Builder knowledge before any release of JEDI-VCL.

However, it is extremely important that anyone submitting code attach the proper headers and documentation and fill them out correctly. This will make it much easier for code to be added to the library.

In general, we will follow the Delphi Style Guide, as published by Charlie Calvert on the Borland Techvoyage site.

5.1 Required sections for each component

5.1.1 Header (author name/etc, version control info)

Figure 1 shows a header that must be included at the top of every piece of source code submitted to the library. This header will work with both Borland Delphi and C++Builder code..

The "Initial Developer" field should have the author's full name, and email address. An email address is important, as this will make bug fixing and other correspondence easier.

5.1.2 Mozilla License disclaimer

Authors shall use only the standard header as in 5.1.1. Files without the disclaimer will not be accepted.

The exception would be where the original code was placed in the Public Domain. In this case please replace the Mozilla License notice with the following statement:

Authors should also clearly document each procedures and function, with appropriate indentation:

We recommend following guidelines for dealing with Prefixes:

It is a good coding technique to include Assertions within your source code (short pre-condition and post-condition routines with your component procedures/functions), which will be useful to end users to understand the assumptions of the component's author. They will be invoked only during an execution from within Delphi IDE, but not compiled into the final version, so there is no penalty in using them.

5.2 Component names

All JEDI-VCL components will use the standard 'TJv' prefix to distinguish them from other components (Please note: "J" is capitalized). TJv has been registered to Project JEDI in the Delphi Prefix Registry ('DPR') at http://www.delphiprefixregistry.net/ 

5.3 Librarian's authority to change component names

Some components will be submitted bearing either (1) a similar name to another component in the library or (2) an inappropriate name or prefix. For example, a component called TJvPrint that writes a character to the screen could be said to be named inappropriately, as it implies some relationship to a printer. The librarian shall have the responsibility to rename submitted components to improve clarity or permit uniqueness.

5.3.1 Changing a component name after it has been released

Once a particular component is included in a library release, its name should be frozen. To allow renaming would probably raise problems for users who had used the previous name and were not tracking the changes to the library.

5.4 Source code formatting

Borland Delphi code shall be formatted in accordance with standard currently defined by Borland for the Delphi VCL. As stated above, at present we will follow the Delphi Style Guide, as published by Charlie Calvert.

The general goal is to provide a consistent format that is recognized by all Borland Delphi developers.

Deviations should be avoided.

You can use following tools to assist you with code formatting:

http://jedicodeformat.sourceforge.net/
http://www.dow.wau.nl/aew/DelForExp.html

5.5 Comments in Code

• Preferably maximum of ONE line to describe the purpose of a method.
• Comments should describe the code, not how to use it.
• Within a method, include comments only for code that needs explaining,
  NOT
  

      Form1.Show // Shows Form

• As a guide, keep to the ratio of 10 lines of code to 1 line of comment.

5.6 Other considerations

• Space characters: place one space after a comma or colon symbol and place one space each side of an operator symbol ( +, -, *, /, := , = , <, >, etc.)

• No more than one command or variable declaration on one source line.

• If there is no method description then at least a separating line (e.g. //------ to a width of 80 characters) should be placed between methods. Often it is unnecessary to include an individual description for each method, e.g. a method named CountErrors would not require a description.

• Use parentheses to increase readability of complex Boolean or mathematical expressions, even where the rules of precedence for evaluation would permit them to be optionally omitted.

• Minimize the use of functions in Boolean expressions or other situations where side effects might be difficult to trace.
  
• Explicit dereferencing (like in MyDynamicArray^[0]) is no longer necessary and should be avoided wherever possible.

• Structure function implementations so that they end at only one point (its end keyword) and are not terminated by Exit (if possible).

• Labels with absolute jumps are considered bad programming style (exception: assembler).

6.1.1 Inheritance vs. Composition

We encourage use of Composition by utilizing Interfaces and delegating tasks to other objects. Inheritance should be used mainly for extending properties and methods in a "Is-a-Kind-of" relationships.

6.1.2 Inheritance

The final component (TJvMyComponent) should descend from at least one custom component (TJvMyCustomComponent).

6.1.3 Method Scope

Protected and Virtual methods are preferred for JEDI components. Defining a method as Private is discouraged, unless consciously applied for a reason.

6.1.4 Private Fields/Variables

All 'Private' Fields/Variables should have associated Get and (where it makes sense) Set 'Protected' methods. This allows easy access to them in descendants, if required.

6.1.5 ASM

Assembler routines (ASM) are acceptable only for machine-level glue logic that cannot be performed by high-level Pascal source code. We will require source code comments to explain why machine-level glue logic is required at all. Any author considering submitting ASM code should seek advice on the mailing list/newsgroups for an Object Pascal solution, before committing to writing ASM code.

ASM for the sole purpose of performance is prohibited except in extreme cases, and even then should be accompanied by functionally equivalent Pascal source in comments. See math.pas for examples.

6.1.6 Reference to Design-time Units in RunTime Code

Please DO NOT refer in your RunTime code to DsgnIntf, LibIntf, or any other design-time code. Starting with Delphi 6 separation of design time code from runtime code became mandatory. 

6.1.7 Usage of $IFDEF Conditional Compiler Directives

Since we will be supporting only two consecutive releases of Delphi, there should be no need to use $IFDEF directives. They make code maintenance and readability difficult. Please DO NOT use them, unless you can make a case to demonstrate that they are absolutely required.

Project JEDI will provide a standard file containing conditional directives.

6.1.8 Calls to Component Events

Events should be fired via overrideable methods, and the component's implementation should call through such methods exclusively (don't fire the event property directly). All calls to component events should be directed via a virtual/dynamic method. If the method is not expected to be overridden frequently by descendents, the method should be declared dynamic to save on VMT space. The performance difference between dynamic and virtual is negligible for user-initiated events.

Instead of
 

procedure TMyComp.WMLButtonDown(...) begin   :   if Assigned(FOnMouseDown) then ...   : end;

use:
 
 

procedure TMyComp.WMLButtonDown(...) begin   :   DoMouseDown(...) // DoMouseDown is a virtual method                                     : end;

6.2 Packages

6.2.1 Registration Units

To enable use of packages, as well as building "private" packages from individual components, we will need a registration unit for each component, as well as multi-registering unit for the whole package.

6.2.2 Organization into .PASs and .DPKs

Since many different people will be submitting components, it will be generally desirable to house all components that belong together in the same .PAS, or at least to group their units in the same .DPK file. If there is some reason to split the .PAS, the referees and the librarian will handle that as part of library organization.

6.2.3 Package Versioning

A clear and consistent versioning system is required, to avoid any conflicts between packages. The JEDI-VCL will follow the model established by the TurboPower® scheme:

PNNNMKVV.*
||  |||
||  ||+------ VV  VCL version (30=Delphi 3, 35=C++Builder 3,40=Delphi 4)
||  |+------- K   Kind of package (R=runtime, D=designtime, T-trialrun)
||  +-------- M   Product specific modifier (Underscore=default)
|+----------- NNN Product version number (e.g., 201=version 2.01)
+------------ P   Package name

For example, an Internet design package Version 1.0 for Delphi 5 would be:

   JvInternet100_D50.BPL

The same package, but a Runtime version, would be:

   JvInternet100_R50.BPL  

Below you can see a typical structure of JEDI-VCL packages:

Please use this structure, so we can achieve a consistency across JVCL components and simplify maintenance. We will just add your Registration/Resource units, and your RunTime package to the JVCL Design package, and we are in business :)

6.3 Procedures for compiling components

6.3.1 Borland Delphi

Borland Delphi components will be compiled under the current and previous release of Borland Delphi, with the Delphi default compiler options:

  {$A+,B-,C+,D+,E-,F-,G+,H+,I+,J+,K-,L+,M-,N+,O+,P+,Q-,R-,S-,T-,U-,V+,W-,X+,Y+,Z1}
  

       {$MINSTACKSIZE $00004000}
       {$MAXSTACKSIZE $00100000}
       {$IMAGEBASE $00400000}
  

Any deviations must be explained in the code.

6.4 Functions requiring other libraries

JEDI-VCL can make no assumptions about the end user's capability to link in any library other than the Delphi Standard version of VCL. Therefore, no component will be added to JEDI-VCL that requires any other third party component library, unless it is freely available on the Web (e.g. RxLib). There might be, however, subsections of JEDI-VCL requiring Pro and C/S versions of Delphi VCL.

Our general preferences are:

1) Don't use any 3rd Party libs

2) Copy code from 3rd Party libs (with permission and by giving Credit) - this prevents future "update" incompatibles

3) Make all 3rd Party libs used in a tested version available for download on JEDI-VCL Site (they should not be included in JEDI-VCL libs)

The 3rd Party functions/components should be placed in a separate package.

JEDI will attempt to record accurately and associate the version/build data of 3rd party libs with specific builds of the TJv's that use them. It is essential that authors include this information when submitting their source code.

6.5 Demo Project

While a Demo Project is an optional part of the submitted component, the author is encouraged to include a short Demo with the code. Authors should seriously consider adding it, as it may become a requirement in a future version of the JEDI-VCL.

6.6 Help File

We strongly encourage providing a detailed Help file with each component in a text format. This will help to keep the comments in code to a needed minimum. Specifically:

• All details on how to use the component should be in a help file

• Each method should be documented together with a “what it does” description.

We are using “Doc-O-Matic” Help creation tool donated to JEDI by ToolsFactory (http://www.toolsfactory.com).  In order to make it easy to include your file in the overall Help system, the file should have description for the all classes, and for all major fields, properties, events, and methods, following the format below (example for JvPanel). The elements to be filled are in bold. Please also note the required “@@” in the front of each of the elements:  

6.7 Package Installation

Packages will be provided with an installation program, which will install them for the selected Delphi version. It will also back up all old files being replaced. The installation program should create the following subdirectory structure for each package (supporting Delphi 5 and Delphi 6):

 

Subdirectory	Purpose
\bin	for bpl files
\demo	for any demos/examples related to components
\help	help files, plus additional help documents for merging into final help
\lib5	for dcu and dcp files for delphi 5
\lib6	for dcu and dcp files for delphi 6
\packages	Package files for Delphi 5 and Delphi 6
\source	all source files (incl. delphi units, packages, resource files)
\bitmaps	bitmaps, rc files, batch files

6.8 Resources/Graphics

We need consistently looking bitmaps for Delphi IDE component palette Icons. The current design contains little blue box with "J":

In the attachment, you will find following templates:

• Design Package
• RunTime Package
• Registration Unit
• Resource Unit
• JVCL Bitmap
• Delphi Component Unit

Peter Mugaas recommended to use the Borland resource-compiler (BRCC32) which is included in Borland Delphi. The .RC file is a resource script containing information about the bitmaps (see example below):

/* JVCL components */
TJVMYCOMPONENTA BITMAP " TJVMYCOMPONENTA.BMP"
TJVMYCOMPONENTB BITMAP " TJVMYCOMPONENTB.BMP"

Notice the links to the BMP files. These should be in the same directory as the .RC file (i.e. \Source\Resource). Please use the attached batch file to compile the script into a DCR file. Here is the MakeDCR.Bat which you can use with JVCL, after you (it is in the same directory as the .RC and .BMP files):

brc32 JvMyComponentReg.rc -r -foJvMyComponentReg.dcr

The librarian will be the person who rebuilds the library from the sources and uploads the resulting deliverables to the proper JEDI library on JEDI Web site. The librarian generally does not test code or edit source code to repair formatting errors.

7.2 Documentor (Help Team)

The documentor is responsible for maintaining the Help files and keeping them in sync with each new release. Documentation should be written in the same style and flavor as the Borland material, if possible. Refer to the Borland Delphi documentation for more detail and numerous examples.

7.3 Referees

Referees are volunteers who read source code, clean it up, compile it, look for problems like potentially problematic Object Pascal code, decide on which component is best, consolidate common functions, etc. They make sure the header and documentation blocks are present. There is no election or term for refereeship. One simply volunteers for the task, performs it as long as one can and bows out when necessary.

7.4 Transitions

Not everyone will be able to stay around forever to keep working on this project. Therefore, it is the responsibility of each referee, documenter, or librarian to announce as far in advance as possible his or her intention to leave, in order to give everyone a chance to nominate a suitable replacement.

Don't let it die!

q       Components created using “TJv” prefix, and inherited from TJvComponent;

q       If a component is not a descendent of JvComponent, it implements a published property “AboutJVCL”
as it is implemented in “JvComponent.pas”.

q       MPL license notice added

q       Compiler switches added

q       JEDI.inc file added (if needed)

q       Code is formatted using JVCL formatting standards

q       Components saved in a file with “Jv” Prefix

q       Component’s “Register” methods moved to Registration Unit

q       Separate RunTime  Package created

q       Separate DesignTime Package created (containing the Registration Unit, and requiring the RunTime Package

q       Any Property/Component Editors added (if needed)

q       Bitmap files for IDE icons created

q       DRC file containing the bitmaps compiled

q       Demo project(s) included (recommended, but optional)

q       Help file included (recommended, but optional)

Improvement suggestions submitted by:

• Allan G. Lloyd
• Marcel van Brakel
• Pavel Císar
• Robert Love
• Helen Borrie
• Phil Shrimpton
• Francois Piette
• Danny Thorpe
• Rodney Delanty
• Shiv Kumar
• Mike Lischke
• Alec Bergamini