Help:Contents

Adding Discussion Page Comments

You must log in to edit the Discussion page.

See http://www.mediawiki.org/wiki/Help:Contents for help with wiki editing syntax.

Adding a New Code Example

For permission to edit the main pages and add examples, contact documentation@embarcadero.com. You must be logged into the wiki and have permission to save a page in the examples wiki.

1. Here is the basic outline for a code example, using System.SysUtils.TrySystemTimeToDateTime for illustrative purposes.

Copy (Ctrl-V) this outline:

=Description=
This is your description
=Code=
<source lang=delphi>
This is where your code goes.
</source>
=Uses=
* [[lib_en:System.SysUtils.TrySystemTimeToDateTime|System.SysUtils.TrySystemTimeToDateTime]] ''(  [[lib_fr:System.SysUtils.TrySystemTimeToDateTime|FR]] | [[lib_de:System.SysUtils.TrySystemTimeToDateTime|DE]] | [[lib_ja:System.SysUtils.TrySystemTimeToDateTime|JP]]  )''

=See Also=
* [[rad_en:Object Inspector|Object Inspector]]

[[Category: Delphi]]
[[Category:XE4]]

2. Create a new page:

1. Open any page in the examples wiki.
2. In the URL in your browser, replace the example name with the name of your new example.
3. For example, replace "TrySystemTimeToDateTime" in http://docwiki.embarcadero.com/CodeExamples/Alexandria/en/TrySystemTimeToDateTime_(Delphi) with MyNewCodeExampleName:

   http://docwiki.embarcadero.com/CodeExamples/{{Version}}/en/MyNewCodeExampleName_(Delphi)

4. For C++ examples, replace (Delphi) with (C++). Don't forget the space before the open-parenthesis.
5. Click "Go" next to the URL field. The wiki will tell you that the page does not exist and asks if you want to create it.
6. Create the page and copy the clipboard to it using CTRL+V.

You now have your new example wiki page in the correct format, but with an empty outline.

3. Replace the Description, the code section, and the 'See Also' list with specific information for your new example.

4. Hyperlinking:

• To create a hyperlink from your example to a page in the Libraries wiki, add the lib_en: prefix.
• For the other languages, use lib_de, lib_fr, and lib_ja.
• Specify the display title using a | to eliminate the prefix from the link:

[[lib_en:Vcl.Forms.TForm|Vcl.Forms.TForm]] = Vcl.Forms.TForm

• To link from an example to the Topics, use the rad_en: prefix in the same way as the lib prefix:

[[rad_en:Object Inspector|Object Inspector]] = Object Inspector

• To link to a code example from the Topics or Libraries wiki, use the samp_en: prefix:

[[samp_en:TrySystemTimeToDateTime (Delphi)|TrySystemTimeToDateTime (Delphi)]] = TrySystemTimeToDateTime (Delphi)

• Finally, a link to the outside world looks like this:

[http://msdn.microsoft.com/en-us/library/ms776446.aspx CodePage Identifiers (MSDN)] = CodePage Identifiers (MSDN)

5. Add the Category tags. Each example should be tagged either Delphi or C++ or both:

Delphi Only:

[[Category: Delphi]]

C++ Only:

[[Category: C++]]

Both:

[[Category: C++]][[Category: Delphi]]

Each example should have a Category tag for the version in which the example first appeared, or the version in which the example was updated and retested against the newer version: XE4, XE5, and so forth.

XE4:

[[Category:XE4]]

Multiple:

[[Category:XE3]][[Category:XE4]]

Additional categories pertain to the technology, here are some suggestions:

FireMonkey framework:

[[Category:FMX]] 

RTTI library:

[[Category:RTTI]] 

Now you are done! Your example will automatically be added to the following pages:

• Code Examples Index:

http://docwiki.embarcadero.com/CodeExamples/en/Code_Examples_Index

• Code Examples by Functionality (that is, by units used):

http://docwiki.embarcadero.com/CodeExamples/en/Code_Examples_by_Functionality

Note: There is only one code examples wiki, and it is available in English only, but it provides links to localized Libraries pages.

Task for Internal Contributors Only

Commit and maintain a current version of your complete code example in our old doc repository section for examples: ... documentation/delphi-xbuilder/trunk/en/Admin/FulcrumDelphiExamples and FulcrumCPPExamples

That way we can easily share your code example and apply consistent changes to all examples as we revise our standard. Please make a folder for each example in the repository and name it the same as the example name on the wiki. Example: TPerlRegExOnReplace (Delphi) is stored in Admin/FulcrumDelphiExamples/TPerlRegExOnReplace. Name your examples "ClassMember", so that we can get an idea of the use from the name. This also makes the name unique. See #7 below.

Name your PAS or CPP file a unique name. Keep in mind that whatever you name it is references as a unit in your code. For instance, if you call your code module Controls.pas and you import the Controls unit in you code, using TControl.Caption will get you a "TControl is not a member of Controls" because TControl is not a member of your Controls.pas. You have now overwritten TControl, unless you reference it as Controls.TControl. Remember, your pas file is a unit, just like Forms, Controls or System.

Coding Standards for Examples

1. Remember to mention in the beginning comment the API members that you are featuring in your code example. When referencing them, mention the unit and class they belong to. Users are looking at these examples without a debugger, and declarations of these objects may be up in the TForm declaration and not appear in your snippet. Remember that your running code project is pulling methods and unit functions from the Uses clause (or unit1.h for C++). Without a debugger, these may be hard to locate.

2. Put the featured API members at the bottom of the example in a Uses clause. As you can see above, I put SysUtils.TrySystemTimeToDateTime and SysUitls.SystemTimeToDateTime in the Uses clause for the TrySystemTimeToDateTime example.

3. Then add links to your featured API member pages in the Uses clause (#3 above) and corresponding links in those API pages back to your example:

==Code Examples==
*[[samp_en:TrySystemTimeToDateTime (Delphi)|TrySystemTimeToDateTime (Delphi)]]
*[[samp_en:TrySystemTimeToDateTime (C++)|TrySystemTimeToDateTime (C++)]]

4. Encourage users to use the visual components to demonstrate how the code works. Visual feedback is not only tutorial, but allows users to write and experiment with the full functionality of the API. This is not a QA test. You are not validating that the software works, just displaying the results. For example: the TPerlRegExOnReplace example assigns the TPerlRegEx.Subject and TPerlRegEx.RegEx from text fields. That way the user can try lots of different formats for a regular expression, and there are a lot.

Try the old DelphiCodeExamples/FormatFloat example. It features a big table of different formats and numbers to execute those formats on. The user is then free to edit those fields to experiment.

5. Design work. With an example of code on a wiki page, the user cannot see the components you have placed on your form or the properties you have set on those components in the Project Manager. Do as much of that work dynamically in FormCreate (Delphi) or the form creation proc (C++):

C++:
__fastcall TForm1::TForm1(TComponent* Owner)
	: TForm(Owner)
{
}

Delphi:
procedure TForm1.FormCreate(Sender: TObject);
begin
  ScrollBar1:= MyScrollBar.Create(self);
  ScrollBar1.Parent:= Form1;
  ScrollBar1.Visible:= TRUE;
  ScrollBar1.Top:= 48;
  ScrollBar1.Left:= 250;
  ScrollBar1.Name:= 'Ricksbar';
end;

Describe what components to add to the form in the initial comment. If you are using complicated constructs, like an ImageList, refer to documentation on how to construct one. If your TForm1 declaration is complicated or you have edited it by hand, include it in the example in the code example wiki. Here's an example: http://docwiki.embarcadero.com/CodeExamples/en/ComponentToString_(Delphi)

6. Initialization. FormCreate is a good place to initialize global variable, but keep in mind that while the form exists, components in it, added during design time, may not be initialized yet. You may need to do some of your work in a Paint routine. If you create class instances dynamically using:

var myButton: TButton;
myButton:= TButton.Create(self);

Self here is the form and is now the owner of myButton. Since the form is a component created at design time, it's children don't need to be freed. By making the form the owner of myButton, form will also free myButton. Many objects, like TLists, don't take an owner as a parameter to their constuctors. They need to be freed explicitly by calling:

myButton.Free //Delphi
delete myButton; //C++

Also, to insure that freeing happens after a create, wrap the creation in a "try" and the cleanup in a "finally":

var myButton: TButton;
try
myButton:= TButton.Create(self);
// your code here (may throw an exception)
finally
  myButton.Free
end;

7. If your example uses text strings, confirm that it works with Unicode strings. The AddChildObjectFirst example uses L"New ઝદ૪ Item", as an argument. The "L" designates a wide string. The ExtractFileName example puts special characters in a StringGrid cell. Even if you don't use wide chars in the code you are putting on the examples wiki, you should try wide chars in the string properties in your components. You can generate wide character string with this tool: Programs » Accessories » System Tools » Character Map

8. Do not create TCustomXXX instances. Even if the method you want to use is in TCustomActionManager, create a TActionManager. You may have to link to the TCustomActionManager in the Uses section, but applicaton code should never use "worker" class instances.