Difference between revisions of "Extending the IDE/de"

From Lazarus wiki
Jump to navigationJump to search
(→‎Config files: translated)
Line 189: Line 189:
 
Hinweis: siehe propedits.pp für Beispiele
 
Hinweis: siehe propedits.pp für Beispiele
  
== Register event handlers ==
+
= Ereignis-Handlers =
  
 
There are several events in the IDE, for which plugins can add their own handlers.  
 
There are several events in the IDE, for which plugins can add their own handlers.  
  
=== Designerereignisse ===
+
== Designerereignisse ==
  
 
In propedits.pp there is a "GlobalDesignHook" object, which maintains several events for designing. Each event calls a list of handlers. The default handlers are added by the IDE. You can add your own handlers with the AddHandlerXXX and RemoveHandlerXXX methods. They will be called before the default handlers.
 
In propedits.pp there is a "GlobalDesignHook" object, which maintains several events for designing. Each event calls a list of handlers. The default handlers are added by the IDE. You can add your own handlers with the AddHandlerXXX and RemoveHandlerXXX methods. They will be called before the default handlers.
Line 248: Line 248:
 
   RefreshPropertyValues
 
   RefreshPropertyValues
  
=== Projektereignisse ===
+
== Projektereignisse ==
  
 
Diese Ereignisse sind definiert in der Unit LazIDEIntf.
 
Diese Ereignisse sind definiert in der Unit LazIDEIntf.
Line 257: Line 257:
 
   LazarusIDE.AddHandlerOnSavingAll
 
   LazarusIDE.AddHandlerOnSavingAll
  
 +
= Projekt =
 
== Aktuelles Projekt ==
 
== Aktuelles Projekt ==
  
Line 309: Line 310:
 
</Delphi>
 
</Delphi>
  
== The executable / target file name of a project ==
+
== Der Name der ausführbaren / Ziel-Datei eines Projekts ==
  
 
Es gibt ein Makro $(TargetFile), welches in Pfaden und externen Werkzeugen verwendet werden kann.
 
Es gibt ein Makro $(TargetFile), welches in Pfaden und externen Werkzeugen verwendet werden kann.
Line 324: Line 325:
 
end;
 
end;
 
</Delphi>
 
</Delphi>
 +
 +
== Add your own project type ==
 +
todo
  
 
== Add your own file type ==
 
== Add your own file type ==
Line 500: Line 504:
 
   RefreshPropertyValues
 
   RefreshPropertyValues
  
== Hilfe ==
+
= Hilfe =
  
=== Hilfe für die Quellen hinzufügen ===
+
== Hilfe für die Quellen hinzufügen ==
  
 
Erzeugen sie zuerst eine THelpDatabase:
 
Erzeugen sie zuerst eine THelpDatabase:
Line 520: Line 524:
 
</delphi>
 
</delphi>
  
=== Zeilen zum Nachrichtenfenster hinzufügen ===
+
== Zeilen zum Nachrichtenfenster hinzufügen ==
  
 
<Delphi>
 
<Delphi>

Revision as of 21:11, 24 January 2011

Deutsch (de) English (en) español (es) français (fr) 日本語 (ja) русский (ru) slovenčina (sk) 中文(中国大陆)‎ (zh_CN)

Erweitern der IDE

Einleitung

Die IDE unterstützt verschiedene Erweiterungen:

Komponenten
Komponenten werden in der Palette installiert. Z.B. TButton erzeugt Buttons.
Komponenten-Editoren
Komponenteneditoren werden benutzt, wenn Sie auf eine Komponente im Designer doppelklicken oder um einige extra Items im Popupmenü des Designers hinzuzufügen, indem man auf eine Komponente rechtsklickt.
Eigenschafts-Editoren
Stellen die Editierfähigkeiten im Objektinspektor zur Verfügung.
Experten
Das sind alle anderen Typen von Editoren. Sie registrieren neue Menüpunkte, Tatenkürzel oder erweitern andere Merkmale der IDE.


Es gibt 2 Möglichkeiten, Ihre eigenen Plugins in Lazarus zu integrieren:

  1. Erstellen Sie ein Package, installieren Sie es und registrieren Sie das Plugin mit der Prozedur 'Register' in einer Unit.
  2. Erweitern Sie den Lazarus Code und senden Sie Ihr SVN diff an die Lazarus-Mailing-Liste.

Menüpunkte

Sie können neue Menüpunkte anfügen, bestehende Menüpunkte verstecken oder verschieben und Untermenüs oder Abschnitte hinzufügen. Für Ihre eigenen Formulare können Sie das TMainMenu/TPopupMenu registrieren, sodass andere Packages darauf zugreifen und Ihr Formular erweitern können. Die Unit MenuIntf des IDEIntf-Packages enthält die gesamte Registrierung für Menüs und viele Standard-Menüpunkte der IDE selbst.

Einen Menüpunkt hinzufügen

Ein einzelner Menüpunkt wie 'View Object Inspector' wird TIDEMenuCommand genannt. Sie können einen erzeugen mit dem Befehl RegisterIDEMenuCommand, der in zwei Formen mit Unmengen von Parametern vorkommen kann:

<Delphi>function RegisterIDEMenuCommand(Parent: TIDEMenuSection;

                               const Name, Caption: string;
                               const OnClickMethod: TNotifyEvent = nil;
                               const OnClickProc: TNotifyProcedure = nil;
                               const Command: TIDECommand = nil;
                               const ResourceName: String = 
                               ): TIDEMenuCommand; overload;

function RegisterIDEMenuCommand(const Path, Name, Caption: string;

                               const OnClickMethod: TNotifyEvent = nil;
                               const OnClickProc: TNotifyProcedure = nil;
                               const Command: TIDECommand = nil;
                               const ResourceName: String = 
                               ): TIDEMenuCommand; overload;</Delphi>

Der Unterschied zwischen diesen beiden Formen liegt nur darin, wie Sie die 'parent menu section' angeben. Geben Sie diesen Menüabschnitt direkt an oder oder indirekt mittels eines Pfades. Viele Standardmenüs finden Sie in der Unit MenuIntf. Zum Beispiel den Abschnitt mnuTools, der das Menü Tools aus dem IDE-Hauptmenü liefert. Es enthält einen Abschnitt itmSecondaryTools, das ist der empfohlene Abschnitt für "Third party tools".

Das folgende Beispiel registriert einen neuen Menübefehl mit dem Namen 'MyTool', der Beschriftung 'Start my tool' und führt beim Klicken die Prozedur StartMyTool aus: <Delphi>procedure StartMyTool; begin

 ...wird ausgeführt, wenn der Menüpunkt angeklickt wird...

end;

procedure Register; begin

 RegisterIDEMenuCommand(itmSecondaryTools, 'MyTool','Start my tool',nil,@StartMyTool);

end;</Delphi>

Falls Sie statt der Prozedur eine Methode aufrufen wollen, dann verwenden Sie den OnClickMethod Parameter.

Dieser Menüpunkt hat kein Tastenkürzel. Wenn Sie ein Tastenkürzel brauchen, dann erzeugen Sie einen TIDECommand und übergeben das Kürzel im Command Parameter. Zum Beispiel:

<Delphi>uses ... IDECommands, MenuIntf; ... var

 Key: TIDEShortCut;
 Cat: TIDECommandCategory;
 CmdMyTool: TIDECommand;

begin

 // register IDE shortcut and menu item
 Key := IDEShortCut(VK_UNKNOWN,[],VK_UNKNOWN,[]);
 Cat := IDECommandList.FindCategoryByName(CommandCategoryToolMenuName);
 CmdMyTool := RegisterIDECommand(Cat,'Start my tool', 'Starts my tool to do some stuff', Key, nil, @StartMyTool);
 RegisterIDEMenuCommand(itmSecondaryTools, 'MyTool', 'Start my tool', nil, nil, CmdMyTool);

end;</Delphi>

Konfigurationsdateien

Laden/Speichern von Einstellungen

Alle Konfigurationsdateien der IDE werden in einem einzigen Verzeichnis als xml-Dateien gespeichert. Auch Packages können dort ihre eigenen Dateien ablegen. Das primäre Konfigurationsverzeichnis kann ermittelt werden mit:

<Delphi>uses LazIDEIntf; ...

 Directory := LazarusIDE.GetPrimaryConfigPath;</Delphi>

Packages erzeugen ihre eigenen xml-Dateien mit:

<Delphi>uses

 ..., LCLProc, BaseIDEIntf, LazConfigStorage;

const

 Version = 1;

var

 Config: TConfigStorage;
 SomeValue: String;
 SomeInteger: Integer;
 SomeBoolean: Boolean;
 FileVersion: LongInt;

begin

 SomeValue:='Default';
 SomeInteger:=3;
 SomeBoolean:=true;
 // speichere die Einstellungen
 try
   Config:=GetIDEConfigStorage('mysettings.xml',false);
   try
     // store the version number so future extensions can handle old config files
     Config.SetDeleteValue('Path/To/The/Version',Version,0);
     // store string variable "SomeValue"
     // if SomeValue has the default value the entry is not stored,
     // so only the differences to the default are stored.
     // This way the xml is kept short and defaults may change in future.
     Config.SetDeleteValue('Path/To/Some/Value',SomeValue,'Default');
     Config.SetDeleteValue('Path/To/Some/Integer',SomeInteger,3);
     Config.SetDeleteValue('Path/To/Some/Boolean',SomeBoolean,true);
     // there are more overloads for SetDeleteValue, find out with Ctrl+Space
   finally
     Config.Free;
   end;
 except
   on E: Exception do begin
     DebugLn(['Saving mysettings.xml failed: ',E.Message]);
   end;
 end;
 // lade die Einstellungen
 try
   Config:=GetIDEConfigStorage('mysettings.xml',true);
   try
     // read the version of the config
     FileVersion:=Config.GetValue('Path/To/The/Version',0);
     // read a string variable "SomeValue". If the entry does not exist, use
     // the Default
     SomeValue:=Config.GetValue('Path/To/Some/Value','Default');
     SomeInteger:=Config.GetValue('Path/To/Some/Integer',3);
     SomeBoolean:=Config.GetValue('Path/To/Some/Boolean',true);
   finally
     Config.Free;
   end;
 except
   on E: Exception do begin
     DebugLn(['Loading mysettings.xml failed: ',E.Message]);
   end;
 end;

end;</Delphi>

Komponenten

Komponenten schreiben

Sie können mit dem Lazarus Package-Editor eine neue, eigene Komponente erstellen. Sie erreichen den Editor über die Menüführung "Datei --> Neu --> Package, Standard Package". Es öffnet sich ein Fenster mit dem Datei- und Komponentenbaum Ihres Packages. Über die dort angezeigten Schaltflächen können Sie Ihr Package einrichten:

  • Speichern: Hier können Sie Ihre Komponente oder Ihr Package unter einen Namen Ihrer Wahl speichern.
  • Hinzufügen: Hier erscheint ein Fenster mit mehreren Tabs. Die wichtisten im Überblick: Im Tab Neue Datei können Sie zum Beispiel Units und Formulardateien für Ihr Projekt erstellen. Eine bereits vorhandene Unit können Sie im Reiter Neue Unit einbinden. Wenn Sie Ihre Komponente auf eine bereits existierende Komponente aufbauen wollen, können Sie diese im Tab Neue Komponente auswählen.
  • Einstellungen: In diesem Dialog können Sie neben der Berschreibung Ihrer Komponente und ihrer Versionierung auch den Package-Typ einstellen sowie Sprachregelungen treffen.
  • Installieren: Wenn Ihre Komponente fertig erstellt ist, können Sie sie über diesen Knopf in die IDE einbinden.
  • Compilereinstellungen: Hier lässt sich festlegen, mit welchen Optionen und Compiler-Argumenten Ihr Package kompiliert werden soll.

Hinweis: Detailierte Informationen zum Package-Editor finden Sie hier.

Beispiel: Eine von TButton abgeleitete Komponente erstellen:

  1. Öffnen Sie den Package-Editor wie oben geschrieben
  2. Klicken Sie auf "Hinzufügen --> Neue Komponente"
  3. Wählen Sie als Basisklasse "TButton", und füllen die Felder wie folgt aus: Neuer Klassenname: TMeinButton, Palettenseite: Misc, Unit Dateiname: meinbutton.pas (diese Datei wird erstellt), Unit Name: MeinButton
  4. Klicken Sie auf Ok - und schon können Sie in der Unit meinbutton.pas den TButton an Ihre Bedürfnisse anpassen.

Einer neuen Komponente ein Icon für die Komponentenpalette verpassen

Zum Beispiel wollen wir TMyButton ein Icon verpassen. Erzeugen sie eine Bilddatei in den Formaten .bmp, .xpm oder .png mit dem selben Namen wie die Komponentenklasse, z.B. tmybutton.png und speichern sie diese im Package-Quelltextverzeichnis. The image can be created by any graphic program (e.g. gimp) and should be no bigger than 24x24 pixel. Then convert the image to a .lrs file with the lazres tool, which can be found in the lazarus/tools directory:

 ~/lazarus/tools/lazres mybutton.lrs tmybutton.png

This creates an pascal include file, which is used in the initialization section of mybutton.pas:

 initialization
   {$I mybutton.lrs}

Installieren sie das Package.

Komponenten-Editoren schreiben

ToDo Hinweis: siehe componenteditors.pas für Beispiele

Eigenschafts-Editoren schreiben

ToDo Hinweis: siehe propedits.pp für Beispiele

Ereignis-Handlers

There are several events in the IDE, for which plugins can add their own handlers.

Designerereignisse

In propedits.pp there is a "GlobalDesignHook" object, which maintains several events for designing. Each event calls a list of handlers. The default handlers are added by the IDE. You can add your own handlers with the AddHandlerXXX and RemoveHandlerXXX methods. They will be called before the default handlers.

Examples:

 Adding your handler (this is normally done in the constructor of your object):
   GlobalDesignHook.AddHandlerComponentAdded(@YourOnComponentAdded);
Removing your handler: GlobalDesignHook.RemoveHandlerComponentAdded(@YourOnComponentAdded);
You can remove all handlers at once. For example, it is a good idea to add this line in the destructor of object: GlobalDesignHook.RemoveAllHandlersForObject(Self);

The handlers of GlobalDesignHook:

 // lookup root
 ChangeLookupRoot
   Called when the "LookupRoot" changed.
   The "LookupRoot" is the owner object of the currently selected components.
   Normally this is a TForm.
// methods CreateMethod GetMethodName GetMethods MethodExists RenameMethod ShowMethod Called MethodFromAncestor ChainCall
// components GetComponent GetComponentName GetComponentNames GetRootClassName ComponentRenamed Called when a component was renamed ComponentAdded Called when a new component was added to the LookupRoot ComponentDeleting Called before a component is freed. DeleteComponent Called by the IDE to delete a component. GetSelectedComponents Get the current selection of components.
// persistent objects GetObject GetObjectName GetObjectNames
// modifing Modified Revert RefreshPropertyValues

Projektereignisse

Diese Ereignisse sind definiert in der Unit LazIDEIntf.

 LazarusIDE.AddHandlerOnProjectClose
 LazarusIDE.AddHandlerOnProjectOpened
 LazarusIDE.AddHandlerOnSavedAll
 LazarusIDE.AddHandlerOnSavingAll

Projekt

Aktuelles Projekt

The current main project can be obtained by LazarusIDE.ActiveProject. (unit LazIDEIntf)

Alle Units des aktuellen Projekts

To iterate through all pascal units of the current main project of the IDE you can use for example:

<Delphi> uses LCLProc, FileUtil, LazIDEIntf, ProjectIntf;

procedure ListProjectUnits; var

 LazProject: TLazProject;
 i: Integer;
 LazFile: TLazProjectFile;

begin

 LazProject:=LazarusIDE.ActiveProject;
 if LazProject<>nil then
   for i:=0 to LazProject.FileCount-1 do
   begin
     LazFile:=LazProject.Files[i];
     if LazFile.IsPartOfProject
     and FilenameIsPascalUnit(LazFile.Filename)
     then
       debugln(LazFile.Filename);
   end;

end; </Delphi>

Die .lpr, .lpi und .lps Datei eines Projekts

<Delphi> uses LCLProc, FileUtil, ProjectIntf, LazIDEIntf; var

 LazProject: TLazProject;

begin

 LazProject:=LazarusIDE.ActiveProject;
 // jedes Projekt hat eine .lpi Datei:
 DebugLn(['Project lpi file: ',LazProject.ProjectInfoFile]);
 // if the project session information is stored in a separate .lps file:
 if LazProject.SessionStorage<>pssNone then
   DebugLn(['Project lps file: ',LazProject.ProjectSessionFile]);
 // If the project has a .lpr file it is the main source file:
 if (LazProject.MainFile<>nil)
 and (CompareFileExt(LazProject.MainFile.Filename,'lpr')=0) then
   DebugLn(['Project has lpr file: ',LazProject.MainFile.Filename]);

end; </Delphi>

Der Name der ausführbaren / Ziel-Datei eines Projekts

Es gibt ein Makro $(TargetFile), welches in Pfaden und externen Werkzeugen verwendet werden kann. You can query the macro in code:

<Delphi> uses MacroIntf;

function MyGetProjectTargetFile: string; begin

 Result:='$(TargetFile)';
 if not IDEMacros.SubstituteMacros(Result) then
   raise Exception.Create('unable to retrieve target file of project');

end; </Delphi>

Add your own project type

todo

Add your own file type

Sie können Einträge hinzufügen zum 'Neu ...' Dialog:

  • See the unit ProjectIntf of the package IDEIntf.
  • Choose a base class TFileDescPascalUnit for normal units or TFileDescPascalUnitWithResource for a new form/datamodule.

Add a new file type

Dieses Beispiel entstammt der ide/mainintf.pas Datei und registriert eine einfache Textdatei:

<Delphi> uses ProjectIntf; ...

 { TFileDescText }
 TFileDescText = class(TProjectFileDescriptor)
 public
   constructor Create; override;
   function GetLocalizedName: string; override;
   function GetLocalizedDescription: string; override;
 end;

... { TFileDescText }

constructor TFileDescText.Create; begin

 inherited Create;
 Name:=FileDescNameText;
 DefaultFilename:='text.txt';
 AddToProject:=false;

end;

function TFileDescText.GetLocalizedName: string; begin

 Result:='Text';

end;

function TFileDescText.GetLocalizedDescription: string; begin

 Result:=lisNewDlgCreateANewEmptyTextFile;

end; </Delphi>

Add a new form type

This example is from the ide/mainintf.pas and registers the normal form:

<Delphi> uses ProjectIntf;

...

 TFileDescPascalUnitWithForm = class(TFileDescPascalUnitWithResource)
 public
   constructor Create; override;
   function GetInterfaceUsesSection: string; override;
   function GetLocalizedName: string; override;
   function GetLocalizedDescription: string; override;
 end;

...

{ TFileDescPascalUnitWithForm }

constructor TFileDescPascalUnitWithForm.Create; begin

 inherited Create;
 Name:=FileDescNameLCLForm;
 ResourceClass:=TForm;
 UseCreateFormStatements:=true;

end;

function TFileDescPascalUnitWithForm.GetInterfaceUsesSection: string; begin

 Result:='Classes, SysUtils, FileUtil, LResources, Forms, Controls, Graphics, Dialogs';

end;

function TFileDescPascalUnitWithForm.GetLocalizedName: string; begin

 Result:='Form';

end;

function TFileDescPascalUnitWithForm.GetLocalizedDescription: string; begin

 Result:=lisNewDlgCreateANewUnitWithALCLForm;

end; </Delphi>

CodeTools in der IDE

Before using the codetools you should commit the current changes of the source editor to the codetool buffers:

<Delphi> uses LazIDEIntf; ...

 // save changes in source editor to codetools
 LazarusIDE.SaveSourceEditorChangesToCodeCache(-1); // -1: commit all source editors

</Delphi>

Hinzufügen einer resource Direktive zu einer Datei

Dies fügt eine {$R example.res} Direktive zu einer Pascal Unit hinzu:

<Delphi> procedure AddResourceDirectiveToPascalSource(const Filename: string); var

 ExpandedFilename: String;
 CodeBuf: TCodeBuffer;

begin

 // make sure the filename is trimmed and contains a full path
 ExpandedFilename:=CleanAndExpandFilename(Filename);
 
 // save changes in source editor to codetools
 LazarusIDE.SaveSourceEditorChangesToCodeCache(-1);
 // die Datei laden
 CodeBuf:=CodeToolBoss.LoadFile(ExpandedFilename,true,false);
 // die resource Direktive hinzufügen
 if not CodeToolBoss.AddResourceDirective(CodeBuf,'example.res') then
   LazarusIDE.DoJumpToCodeToolBossError;

end; </Delphi>

The codetools provides also functions like FindResourceDirective and RemoveDirective.


 Adding your handler (this is normally done in the constructor of your object):
   GlobalDesignHook.AddHandlerComponentAdded(@YourOnComponentAdded);
Removing your handler: GlobalDesignHook.RemoveHandlerComponentAdded(@YourOnComponentAdded);
You can remove all handlers at once. For example, it is a good idea to add this line in the destructor of object: GlobalDesignHook.RemoveAllHandlersForObject(Self);

Die Handlers des GlobalDesignHook:

 // lookup root
 ChangeLookupRoot
   Called when the "LookupRoot" changed.
   The "LookupRoot" is the owner object of the currently selected components.
   Normally this is a TForm.
// Methoden CreateMethod GetMethodName GetMethods MethodExists RenameMethod ShowMethod Called MethodFromAncestor ChainCall
// Komponenten GetComponent GetComponentName GetComponentNames GetRootClassName ComponentRenamed Called when a component was renamed ComponentAdded Called when a new component was added to the LookupRoot ComponentDeleting Called before a component is freed. DeleteComponent Called by the IDE to delete a component. GetSelectedComponents Get the current selection of components.
// persistente Objekte GetObject GetObjectName GetObjectNames
// modifing Modified Revert RefreshPropertyValues

Hilfe

Hilfe für die Quellen hinzufügen

Erzeugen sie zuerst eine THelpDatabase: <delphi>

 HelpDB:=TFPDocHTMLHelpDatabase(
    HelpDatabases.CreateHelpDatabase('EinNameIhrerWahlFürDieDatenbank',
                                            TFPDocHTMLHelpDatabase,true));
 HelpDB.DefaultBaseURL:='http://ihre.hilfe.org/';
 FPDocNode:=THelpNode.CreateURL(HelpDB,
                  'Package1 - A new package',
                  'file://index.html');
 HelpDB.TOCNode:=THelpNode.Create(HelpDB,FPDocNode);// einmal als Inhaltsverzeichnis
 DirectoryItem:=THelpDBISourceDirectory.Create(FPDocNode,'$(PkgDir)/lcl',
                                 '*.pp;*.pas',false);// und einmal als normale Seite
 HelpDB.RegisterItem(DirectoryItem);

</delphi>

Zeilen zum Nachrichtenfenster hinzufügen

<Delphi> unit IDEMsgIntf; ... var Dir: String; begin

 Dir:=GetCurrentDir;
 IDEMessagesWindow.BeginBlock;
 IDEMessagesWindow.AddMsg('unit1.pas(30,4) Error: Identifier not found "a"',Dir,0);
 IDEMessagesWindow.EndBlock;

end; </Delphi>