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 Examples

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.

Here are instructions to enter a code example into the code example wiki:

1. Go to the following page in the example wiki and put the page in edit mode:

http://docwiki.embarcadero.com/CodeExamples/en/TrySystemTimeToDateTime_(Delphi)

Copy the entire contents of the page into the clipboard by using CNTL C. Go "back" in the browser to the non-edit mode of this wiki page.

2. In the URL field in your browser, replace "TrySystemTimeToDateTime" with the name of your new example. For C++ examples, replace (Delphi) with (C++). Don't forget the space before the open-parenthesis. 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. Create the page and copy the clipboard to it using CNTL V.

3. You now have your new example wiki page in the correct format, but with content from the copied example. The basic format is:

=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]]</nowiki> = [[rad_en:Object Inspector|Object Inspector]]

[[Category: Delphi]]
[[Category:XE]]

Replace the description, code section and hyper-links for your new example.

4. To create a hyperlink from an example to the VCL, add the 'vcl_en:' prefix. For other languages, use vcl_de, _fr, and _ja. Specify the 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 VCL prefix:

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

To link back to a code sample from the Topics or VCL, 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 be tagged for the version in which it first appeared, or was updated and retested against the newer version: 2010, XE, XE2, etc:

[[Category: XE2]]

2010:

[[Category:2010]]

Multiple:

[[Category:XE]][[Category:2010]]

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

FireMonkey library:

[[Category:FMX]] 

RTTI library:

[[Category:RTTI]] 

6. Edit this page to place your example in the Code Sample Index:

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

7. Go to that page and you can see that the entry for my TrySystemTimeToDateTime example is:

=== [[TrySystemTimeToDateTime (Delphi)]] ===
Uses:
*[[lib_en:System.SysUtils.TrySystemTimeToDateTime|System.SysUtils.TrySystemTimeToDateTime]]
*[[lib_en:System.SysUtils.SystemTimeToDateTime|System.SysUtils.SystemTimeToDateTime]]

Create an entry for your code example using the TrySystemTimeToDateTime entry as a model. Keep the examples in alphabetical order by name. The C++ section isfarther down the page; the "Jump to C++ Examples" link at the top takes you there.

8. Edit this page to place your example in the Code Samples by Function index:

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

9. Go to that page and you can see that the entry for my TrySystemTimeToDateTime example is:

[[lib_en:System.SysUtils.SystemTimeToDateTime|System.SysUtils.SystemTimeToDateTime]] is used in
* [[TrySystemTimeToDateTime (Delphi)]]
* [[TrySystemTimeToDateTime (C++)]]
[[lib_en:System.SysUtils.TrySystemTimeToDateTime|System.SysUtils.TrySystemTimeToDateTime]] is used in
* [[TrySystemTimeToDateTime (Delphi)]]

Keep the examples in alphabetical order by unit, class and member name.

There is only one code examples wiki, and it is available in English only, but 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 Samples==
*[[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 a sample of code on a wiki page, the user can't see what components you have placed in 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 sample 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.