Difference between revisions of "Adding an About dialog as a property to a custom component"

From Free Pascal wiki
Jump to navigationJump to search
m (minor additions)
(Rewrite to reflect newer code)
Line 17: Line 17:
 
[[File:Screenshot_MyCustomComponent_LGPL_LicenseScreen.png]]
 
[[File:Screenshot_MyCustomComponent_LGPL_LicenseScreen.png]]
 
==Download example code==
 
==Download example code==
−
You can download the full source for an example component as described in this article [http://www.charcodelvalle.com/aboutdialog/aboutdialog_component_code.zip here]
+
You can download the full source as described in this article [http://www.charcodelvalle.com/taboutcomponent/taboutcomponent.zip here]
−
 
+
==Adding an About property to your new or existing component==
−
===Installation of example code===
+
#Add the files aboutcomponentunit.pas and license.lrs to your component directory
−
#Open customcomponent.lpk in the Lazarus IDE
+
#Rename aboutcomponentunit.pas to about<yourcomponentname>unit.pas
−
#In the Package dialog:
+
#In the pas file rename the Unit to match (1)
−
##Click 'Compile'
+
#Open the renamed pas file and do Search/Replace to change all instances of "TAboutComponent" to TAbout<yourcomponentname>
−
##Click 'Use/Install'
+
#In the line TAboutComponent = Class(TComponent), change the ancestor to your component's ancestor (if it's not TComponent)
−
#When Lazarus askes you whether you want to recompile the IDE, click 'Yes'
+
#Add the edited pas file to your component's package
−
 
+
#In your component's class declaration, change it's ancestor to TAbout<yourcomponentname> (from step 3)
−
The package 'aboutdialog.lpk' should automatically install as DesignTime only
+
#Compile, install and see the new clickable 'About' property in your component!
−
 
+
===Configuring the About property dialog===
−
===How to use example code===
+
*In your component's Constructor Create() set some, all or none of the following properties:
−
#Open a new Application project
+
**AboutBoxComponentName (string)
−
#Drop a 'MyCustomComponent' from the 'Additional' component palette onto the form
+
**AboutBoxWidth (integer)
−
#Highlight the component, and check the Object Inspector
+
**AboutBoxHeight (integer)
−
#Click the 'About' property ellipsis [...]
+
**AboutBoxDescription (string - can contain LineEndings)
−
==Making this work in your own custom component==
+
**AboutBoxBackgroundColor (TColor, like clWhite)
−
===Adding aboutdialog as a requirement===
+
**AboutBoxFontName (string)
−
*Make sure the subcomponent package 'aboutdialog' and its files are available in the same folder as your new component.
+
**AboutBoxFontSize (integer)
−
Opening the package 'aboutdialog' looks like this:
+
**AboutBoxVersion (string)
−
 
+
**AboutBoxAuthorname (string)
−
[[File:Screenshot_aboutdialog_Packagedialog.png]]
+
**AboutBoxOrganisation (string)
−
*In your custom component package, add 'aboutdialog' as a dependency.  Like this:
+
**AboutBoxAuthorEmail (string)
−
[[File:Screenshot_MyCustomComponent_Packagedialog_addrequirement.png]]
+
**AboutBoxLicenseType (string e.g. 'GPL', ModifiedGPL' etc)
−
*This will ensure that it will always compile with your component.
+
*You will have to recompile and reinstall your component to see the results.
−
*Your component package will now look like this:
+
==Example==
−
[[File:Screenshot_MyCustomComponent_Packagedialog.png]]
+
*Using the component TScrollText (available [http://www.charcodelvalle.com/scrollingtext/scrollingtext_component.zip here])
−
----
+
**I have already renamed the AboutComponentunit to AboutScrolltextunit
−
===Adding the code 'by hand' to your custom component code===
+
*TScrolltext is dereived from TGraphicControl so in the AboutScrollText unit I alter:
−
*This looks like a lot, but it only takes 5 minutes using copy/paste
+
TAboutScrollText = class(TComponent)  
−
*The easier route is to use the example component source as a template for your component
+
to
−
 
+
TAboutScrollText = class(TGraphicControl)
−
*Add to your Uses clause
+
*Then in my scrolltext unit, I change
−
ExtCtrls, AboutboxUnit, PropEdits;
+
TScrollingText = class(TGraphicControl)  
−
*Add to the private section of your component class declaration
+
to
−
  TMyCustomComponent = class(TComponent)
+
TScrollingText = class(TAboutScrollText)  
−
  private
+
*Now the Scrolltext component has an 'About' property, but with default values.
−
    { Private declarations }
+
*So in my TScrollingText constructor, I now set my own values:
−
    fAboutBox: tAboutBox;
+
  constructor TScrollingText.Create(AOwner: TComponent);
−
*Add a published property
 
−
    property About: tAboutBox read fAboutBox write fAboutBox;
 
−
*In the Type block (before the Register declaration) add:
 
−
  TAboutPropertyEditor = class(TClassPropertyEditor)
 
−
  public
 
−
    procedure Edit; override;
 
−
    function GetAttributes: TPropertyAttributes; override;
 
−
  end;
 
−
*In your Register procedure add (where 'TMyCustomComponent' is the name of your component)
 
−
  RegisterPropertyEditor(TypeInfo(TAboutbox),
 
−
    TMyCustomComponent, 'About', TAboutPropertyEditor);
 
−
*After the Register procedure add the following:
 
−
  procedure TAboutPropertyEditor.Edit;
 
−
// Communicate with the component properties
 
−
Var
 
−
    AAboutBox:TAboutBox;
 
 
  begin
 
  begin
−
     AAboutBox:=TAboutBox(GetObjectValue(TAboutBox));
+
  inherited Create(AOwner); 
−
    AABoutBox.ShowDialog;
+
..other constructor code..
−
end;        
+
     // About dialog
−
function TAboutPropertyEditor.GetAttributes: TPropertyAttributes;
+
  AboutBoxComponentName:='ScrollingText component';
−
   // Show the ellipsis
+
  AboutBoxWidth:=400;
−
begin
+
  // AboutBoxHeight (integer)
−
  Result := [paDialog, paReadOnly];
+
  AboutBoxDescription:='Component that shows a scrolling window.' + LineEnding +
 +
  'Use Lines property to set text and Active=True' + LineEnding +
 +
  'to use the component';
 +
  AboutBoxBackgroundColor:=clWindow;
 +
  AboutBoxFontName:='Arial';
 +
  AboutBoxFontSize:=10;
 +
  AboutBoxVersion:=C_VERSION;
 +
  AboutBoxAuthorname:='Gordon Bamber';
 +
   AboutBoxOrganisation:='Public Domain';
 +
  AboutBoxAuthorEmail:='minesadorada@charcodelvalle.com';
 +
  AboutBoxLicenseType:='LGPL';
 
  end;
 
  end;
−
*In your Constructor procedure (Create) add this Var:
+
*I then compile and install the scroller component to the IDE palette, and the 'About' property is part of the component.
−
var
 
−
  TempImage: TPicture;
 
−
*In your Constructor Create() add this code.
 
−
*This is where you set the About properties to suit your Component
 
−
  inherited Create(AOwner); // For your component
 
−
 
 
−
  fAboutBox := tAboutBox.Create(nil);
 
−
  with fAboutBox do
 
−
  begin
 
−
    SetSubComponent(True);  // Tell the IDE to store the modified properties
 
−
 
 
−
    // Set properties of your Component About Dialog here
 
−
    // All are optional
 
−
    ComponentName := 'My Custom Component';
 
−
    Title := 'About ' + ComponentName;
 
−
    Description.Add('This is a test case to demonstrate'); //TStrings
 
−
    Description.Add('the use of TAboutBox as a subcomponent'); //TStrings
 
−
    Width := 320; //Integer
 
−
    Height := 280; //Integer
 
−
    // Set any Font properties or subproperties here
 
−
    Font.Name := 'Arial';
 
−
    Font.Color := clNavy;
 
−
    // BackGroundColor shows if no BackGround image is set
 
−
    BackGroundColor := clSkyBlue;
 
−
    Version := '1.0.0.0';
 
−
    AuthorName := 'Gordon Bamber';
 
−
    AuthorEmail := 'minesadorada@charcodelvalle.com';
 
−
    Organisation := 'Public Domain';
 
−
 
 
−
    //Types available: abNone, abGPL, abLGPL, abMIT, abModifiedGPL, abProprietry
 
−
    LicenseType := abLGPL;
 
−
 
 
−
    // BackGround image is optional
 
−
    //== How to set a background image to your About dialog --
 
−
    // The BackGround property is a TBitmap
 
−
    // Use a Temporary TPicture to load a JPG  (NOT a PNG) etc.
 
−
    TempImage := TPicture.Create;
 
−
    // .lrs file containing 'brushedsteel' PNG is in the initialization section
 
−
    TempImage.LoadFromLazarusResource('brushedsteel');
 
−
    BackGround.Assign(TempImage.Bitmap);
 
−
    TempImage.Free;
 
−
    StretchBackground := True; //Boolean
 
−
  end;
 
−
*In your component Destructor procedure add:
 
−
  FreeAndNil(fAboutBox);
 
−
  inherited Destroy; // for your component
 
−
*To load a background image, add it as a resource here
 
−
*The resource name is referenced in the LoadFromLazarusResource call
 
−
initialization
 
−
{$I backgroundimage.lrs}
 
−
 
 
−
*Note all the above code is cut+paste from the example code in the download link
 
−
 
 
−
*Once all that 'About' property code is in place, then start adding your component code as normal..
 
−
 
 
 
==See Also==
 
==See Also==
 
[[Lazarus_Nongraphical_Visual_Component_Example_Code]]
 
[[Lazarus_Nongraphical_Visual_Component_Example_Code]]
 +
[[ScrollText]]
  
 
[[Category:Components]]
 
[[Category:Components]]

Revision as of 15:33, 15 June 2014

Summary

This article is for writers of Lazarus visual components (descended from TComponent or descendants)

  • With the addition of a few lines of code to your component, it can display an 'About' property with an ellipsis button in the IDE Object Inspector
  • When the application programmer using your component clicks the button in the Object Inspector, a customised modal 'About' dialog is displayed with your info on it.
  • As well as an 'OK' button, the dialog can also display a 'License' button
    • When clicked, this displays one of the standard licenses (GPL, LGPL etc) in a modal window

This is what the application programmer would see when he drops your component onto a form:

Object Inspector example screenshot

Screenshot MyCustomComponent ObjectInspector.png

About dialog example screenshot

  • Clicking the ellipse button shows this:

Screenshot MyCustomComponent AboutBox.png

License screen example screenshot

  • Clicking the License button shows this:

Screenshot MyCustomComponent LGPL LicenseScreen.png

Download example code

You can download the full source as described in this article here

Adding an About property to your new or existing component

  1. Add the files aboutcomponentunit.pas and license.lrs to your component directory
  2. Rename aboutcomponentunit.pas to about<yourcomponentname>unit.pas
  3. In the pas file rename the Unit to match (1)
  4. Open the renamed pas file and do Search/Replace to change all instances of "TAboutComponent" to TAbout<yourcomponentname>
  5. In the line TAboutComponent = Class(TComponent), change the ancestor to your component's ancestor (if it's not TComponent)
  6. Add the edited pas file to your component's package
  7. In your component's class declaration, change it's ancestor to TAbout<yourcomponentname> (from step 3)
  8. Compile, install and see the new clickable 'About' property in your component!

Configuring the About property dialog

  • In your component's Constructor Create() set some, all or none of the following properties:
    • AboutBoxComponentName (string)
    • AboutBoxWidth (integer)
    • AboutBoxHeight (integer)
    • AboutBoxDescription (string - can contain LineEndings)
    • AboutBoxBackgroundColor (TColor, like clWhite)
    • AboutBoxFontName (string)
    • AboutBoxFontSize (integer)
    • AboutBoxVersion (string)
    • AboutBoxAuthorname (string)
    • AboutBoxOrganisation (string)
    • AboutBoxAuthorEmail (string)
    • AboutBoxLicenseType (string e.g. 'GPL', ModifiedGPL' etc)
  • You will have to recompile and reinstall your component to see the results.

Example

  • Using the component TScrollText (available here)
    • I have already renamed the AboutComponentunit to AboutScrolltextunit
  • TScrolltext is dereived from TGraphicControl so in the AboutScrollText unit I alter:
TAboutScrollText = class(TComponent)

to 

TAboutScrollText = class(TGraphicControl)
  • Then in my scrolltext unit, I change
TScrollingText = class(TGraphicControl)

to 

TScrollingText = class(TAboutScrollText)
  • Now the Scrolltext component has an 'About' property, but with default values.
  • So in my TScrollingText constructor, I now set my own values:
constructor TScrollingText.Create(AOwner: TComponent);
begin
 inherited Create(AOwner);  
..other constructor code..
   // About dialog
 AboutBoxComponentName:='ScrollingText component';
 AboutBoxWidth:=400;
 // AboutBoxHeight (integer)
 AboutBoxDescription:='Component that shows a scrolling window.' + LineEnding +
 'Use Lines property to set text and Active=True' + LineEnding +
 'to use the component';
 AboutBoxBackgroundColor:=clWindow;
 AboutBoxFontName:='Arial';
 AboutBoxFontSize:=10;
 AboutBoxVersion:=C_VERSION;
 AboutBoxAuthorname:='Gordon Bamber';
 AboutBoxOrganisation:='Public Domain';
 AboutBoxAuthorEmail:='minesadorada@charcodelvalle.com';
 AboutBoxLicenseType:='LGPL';
end;
  • I then compile and install the scroller component to the IDE palette, and the 'About' property is part of the component.

See Also

Lazarus_Nongraphical_Visual_Component_Example_Code ScrollText

Retrieved from "http://wiki.freepascal.org/index.php?title=Adding_an_About_dialog_as_a_property_to_a_custom_component&oldid=81048"