Extending the IDE/es: what changed
Revision 2 to 3. Removed lines have a minus sign; added lines have a plus sign.
| Old | New | Line | |
|---|---|---|---|
| 1 | - | ||
| 2 | - | ||
| 3 | - | ||
| 4 | - | ||
| 5 | - | ||
| 6 | - | ||
| 7 | - | ||
| 8 | - | ||
| 9 | - | ||
| 10 | - | ||
| 11 | - | ||
| 12 | - | ||
| 13 | - | ||
| 14 | - | ||
| 15 | - | ||
| 16 | - | ||
| 17 | - | ||
| 18 | - | ||
| 19 | - | ||
| 20 | - | ||
| 21 | - | ||
| 22 | - | ||
| 23 | - | ||
| 24 | - | ||
| 25 | - | ||
| 26 | - | ||
| 27 | - | ||
| 28 | - | ||
| 29 | - | ||
| 30 | - | ||
| 31 | - | ||
| 32 | - | ||
| 33 | - | ||
| 34 | - | ||
| 35 | - | ||
| 36 | - | ||
| 37 | - | ||
| 38 | - | ||
| 39 | - | ||
| 40 | - | ||
| 41 | - | ||
| 42 | - | ||
| 43 | - | ||
| 44 | - | ||
| 45 | - | ||
| 46 | - | ||
| 47 | - | ||
| 48 | - | ||
| 49 | - | ||
| 50 | - | ||
| 51 | - | ||
| 52 | - | ||
| 53 | - | ||
| 54 | - | ||
| 55 | - | ||
| 56 | - | ||
| 57 | - | ||
| 58 | - | ||
| 59 | - | ||
| 60 | - | ||
| 61 | - | ||
| 62 | - | ||
| 63 | - | ||
| 64 | - | ||
| 65 | - | ||
| 66 | - | ||
| 67 | - | ||
| 68 | - | ||
| 69 | - | ||
| 70 | - | ||
| 71 | - | ||
| 72 | - | ||
| 73 | 1 | # Extendiendo el IDE | |
| 74 | 2 | ||
| 75 | 3 | ## Visión general | |
| 76 | 4 | ||
| 77 | - | ||
| 5 | + | El IDE de Lazarus soporta varios tipos de plugins: | |
| 78 | 6 | ||
| 79 | - | ||
| 80 | - | ||
| 7 | + | Componentes | |
| 8 | + | Estos son los elementos que se encuentrar en la Paleta de Componentes. Por ejemplo, TButton (que se encuentra en la solapa Standard) que se utiliza para crear Buttons. | |
| 81 | 9 | ||
| 82 | - | ||
| 83 | - | ||
| 10 | + | Component Editors | |
| 11 | + | Cuando haces doble click sobre un componente en el Diseñador, se invoka un editor de componente. El editor de componente puede además añadir un elemento extra al menú emergente (accedido cuando haces click en el pulsador derecho en un componente dentro del Diseñador). | |
| 84 | 12 | ||
| 85 | - | ||
| 86 | - | ||
| 13 | + | Property Editors | |
| 14 | + | Cada fila en la sección de la rejilla (grid) del Inspector de Objetos utiliza un editor de propiedades que permite establecer o alterar el valor de su propiedad. | |
| 87 | 15 | ||
| 88 | - | ||
| 89 | - | ||
| 16 | + | Experts | |
| 17 | + | Experts abarca todos los demás tipos de plugin. Pueden registrar nuevos elementos de menú, registrar atajos (short cuts), o extender otras características del IDE. | |
| 90 | 18 | ||
| 91 | - | ||
| 19 | + | Hay dos maneras posibles de añadir tus propios plugins al IDE de Lazarus: | |
| 92 | 20 | ||
| 93 | - | ||
| 94 | - | ||
| 21 | + | 1. Escribir un paquete, instalarlo y registrar tu plugin(s) en el procedimiento 'Register' procedure de una unit. | |
| 22 | + | 2. Extender el cógigo de Lazarus, y enviar tu svn diff a la lista de correo de Lazarus. | |
| 95 | 23 | ||
| 96 | 24 | ## Paquetes y Dependencias MakeFile | |
| 97 | 25 | ||
| 98 | - | ||
| 26 | + | Los siguientes pasos son necesarios para añadir nuevas dependencias de paquete. | |
| 99 | 27 | ||
| 100 | - | ||
| 101 | - | ||
| 28 | + | - Crear/Actualizar el MakeFile para el paquete vía Editor de Paquete / Más ... / Crear Makefile. | |
| 29 | + | - Corregir todas las dependencias. Ver tools/updatemakefiles.lpi | |
| 102 | 30 | ||
| 103 | 31 | # Elementos del Menú | |
| 104 | 32 | ||
| 105 | - | ||
| 33 | + | Puedes añadir nuevos elementos al menú, ocultar o mover los existentes y añadir sub menús y secciones. Puedes registrar TMainMenu/TPopupMenu para tus propios formularios de forma que otros paquetes puedan extender más tu formulario. La unidad **MenuIntf** del paquete IDEIntf contiene todos todos los registros para menús y algunos elementos menú estandar del propio IDE. | |
| 106 | 34 | ||
| 107 | 35 | ## Añadiendo un elemento al menú | |
| 108 | 36 | ||
| 109 | - | ||
| 110 | - | ||
| 37 | + | Un simple elemento de menú tal como 'View Object Inspector' se llama **TIDEMenuCommand**. Puedes crear uno con **RegisterIDEMenuCommand**, que tiene dos fomas con un montón de parámetros: | |
| 38 | + | ||
| 39 | + | ``` pascal | |
| 40 | + | ||
| 111 | 41 | function RegisterIDEMenuCommand(Parent: TIDEMenuSection; | |
| 112 | - | ||
| 113 | - | ||
| 114 | - | ||
| 115 | - | ||
| 116 | - | ||
| 117 | - | ||
| 118 | - | ||
| 119 | - | ||
| 120 | - | ||
| 121 | - | ||
| 122 | - | ||
| 123 | - | ||
| 42 | + | const Name, Caption: string; | |
| 43 | + | const OnClickMethod: TNotifyEvent = nil; | |
| 44 | + | const OnClickProc: TNotifyProcedure = nil; | |
| 45 | + | const Command: TIDECommand = nil; | |
| 46 | + | const ResourceName: String = '' | |
| 47 | + | ): TIDEMenuCommand; overload; | |
| 48 | + | function RegisterIDEMenuCommand(const Path, Name, Caption: string; | |
| 49 | + | const OnClickMethod: TNotifyEvent = nil; | |
| 50 | + | const OnClickProc: TNotifyProcedure = nil; | |
| 51 | + | const Command: TIDECommand = nil; | |
| 52 | + | const ResourceName: String = '' | |
| 53 | + | ): TIDEMenuCommand; overload; | |
| 124 | 54 | ``` | |
| 125 | 55 | ||
| 126 | - | ||
| 56 | + | La diferencia entre los dos consiste solamente en como se especifica la sección padre del menú. Puedes dar la sección del menú directamente o bien indirectamente a través de su trayecto. Algunas secciones estandar las puedes encontrar en la unidad *MenuIntf* Por ejemplo, la sección **mnuTools**, la cual es el menú *Tools* de la barra principal del IDE. Contiene una secciónon **itmSecondaryTools**, que es la sección recomendada para utilidades de terceros. | |
| 127 | 57 | ||
| 128 | - | ||
| 129 | - | ||
| 58 | + | Lo siguiente registra un nuevo mandato de menú con el nombre 'MyTool', el caption 'Arranca mi utilidad' y cuando es clickeada ejecuta el procedimiento *StartMyTool*: | |
| 59 | + | ||
| 60 | + | ``` pascal | |
| 130 | 61 | procedure StartMyTool; | |
| 131 | - | ||
| 132 | - | ||
| 133 | - | ||
| 134 | - | ||
| 135 | - | ||
| 136 | - | ||
| 137 | - | ||
| 138 | - | ||
| 62 | + | begin | |
| 63 | + | ...ejecutada cuando el elemento del menú es clickeado... | |
| 64 | + | end; | |
| 65 | + | ||
| 66 | + | procedure Register; | |
| 67 | + | begin | |
| 68 | + | RegisterIDEMenuCommand(itmSecondaryTools, 'MyTool','Aranca mi utilidad',nil,@StartMyTool); | |
| 69 | + | end; | |
| 139 | 70 | ``` | |
| 140 | 71 | ||
| 141 | - | ||
| 72 | + | If you want to call a method instead of a procedure use the **OnClickMethod** parameter. | |
| 142 | 73 | ||
| 143 | - | ||
| 144 | - | ||
| 74 | + | Este elemento de menú no tiene un atajo. En caso de necesitar uno debes crear un **TIDECommand** y pasarlo en el parámetro **Command**. Por ejemplo: | |
| 75 | + | ||
| 76 | + | ``` pascal | |
| 145 | 77 | uses ... IDECommands, MenuIntf; | |
| 146 | - | ||
| 147 | - | ||
| 148 | - | ||
| 149 | - | ||
| 150 | - | ||
| 151 | - | ||
| 152 | - | ||
| 153 | - | ||
| 154 | - | ||
| 155 | - | ||
| 156 | - | ||
| 157 | - | ||
| 78 | + | ... | |
| 79 | + | var | |
| 80 | + | Key: TIDEShortCut; | |
| 81 | + | Cat: TIDECommandCategory; | |
| 82 | + | CmdMyTool: TIDECommand; | |
| 83 | + | begin | |
| 84 | + | // register IDE shortcut and menu item | |
| 85 | + | Key := IDEShortCut(VK_UNKNOWN,[],VK_UNKNOWN,[]); | |
| 86 | + | Cat:=IDECommandList.FindCategoryByName(CommandCategoryToolMenuName); | |
| 87 | + | CmdMyTool := RegisterIDECommand(Cat,'Start my tool', 'Starts my tool to do some stuff', Key, nil, @StartMyTool); | |
| 88 | + | RegisterIDEMenuCommand(itmSecondaryTools, 'MyTool', 'Start my tool', nil, nil, CmdMyTool); | |
| 89 | + | end; | |
| 158 | 90 | ``` | |
| 159 | 91 | ||
| 160 | 92 | # Atajos (Shortcuts) | |
| 161 | 93 | ||
| 162 | - | ||
| 163 | - | ||
| 94 | + | Todos los atajos (teclas que invocan alguna acción) se encuentran registradas en el IDECommandList. Este es un ejemplo sobre como encontrar todos los mandatos que reaccionan a la pulsación de Ctrl-D o la combinación de teclas pulsadas que comiencen por Ctrl-D: | |
| 95 | + | ||
| 96 | + | ``` pascal | |
| 164 | 97 | uses | |
| 165 | - | ||
| 166 | - | ||
| 167 | - | ||
| 168 | - | ||
| 169 | - | ||
| 170 | - | ||
| 171 | - | ||
| 172 | - | ||
| 173 | - | ||
| 174 | - | ||
| 175 | - | ||
| 176 | - | ||
| 177 | - | ||
| 178 | - | ||
| 179 | - | ||
| 180 | - | ||
| 181 | - | ||
| 182 | - | ||
| 183 | - | ||
| 184 | - | ||
| 185 | - | ||
| 186 | - | ||
| 187 | - | ||
| 98 | + | Classes, SysUtils, LCLProc, IDECommands; | |
| 99 | + | ||
| 100 | + | procedure ListCtrlD; | |
| 101 | + | // Lista todos los idecommands con el atajo Ctrl-D | |
| 102 | + | var | |
| 103 | + | i: integer; | |
| 104 | + | Cmd: TIDECommand; | |
| 105 | + | Commands: TFPList; | |
| 106 | + | begin | |
| 107 | + | Commands:=IDECommandList.FindCommandsByShortCut(IDEShortCut(VK_D,[],VK_UNKNOWN,[])); // VK = Virtual Key | |
| 108 | + | try | |
| 109 | + | for i:=0 to Commands.Count-1 do begin | |
| 110 | + | Cmd:=TIDECommand(Commands[i]); | |
| 111 | + | writeln('Cmd: ',Cmd.Name, | |
| 112 | + | ' A=',dbgs(Cmd.ShortcutA.Shift1),'-',Cmd.ShortcutA.Key1, | |
| 113 | + | ',',dbgs(Cmd.ShortcutA.Shift2),'-',Cmd.ShortcutA.Key2, | |
| 114 | + | ' B=',dbgs(Cmd.ShortcutB.Shift1),'-',Cmd.ShortcutB.Key1, | |
| 115 | + | ',',dbgs(Cmd.ShortcutB.Shift2),'-',Cmd.ShortcutB.Key2 | |
| 116 | + | ); | |
| 188 | 117 | end; | |
| 118 | + | finally | |
| 119 | + | Commands.Free; | |
| 120 | + | end; | |
| 121 | + | end; | |
| 189 | 122 | ``` | |
| 190 | 123 | ||
| 191 | 124 | # Config files | |
| 192 | 125 | ||
| 193 | 126 | ## Cargar/Salvar configuraciones | |
| 194 | 127 | ||
| 195 | - | ||
| 196 | - | ||
| 197 | - | ||
| 128 | + | Todos los ficheros de configuración del IDE se encuentran almacenados en un directorio como ficheros xml. Los paquetes también también pueden añadir sus propios ficheros en dicho directorio. El [[pcp|primary config path]] se puede leer con: | |
| 198 | 129 | ||
| 199 | - | ||
| 130 | + | ``` pascal | |
| 200 | 131 | uses LazIDEIntf; | |
| 201 | - | ||
| 202 | - | ||
| 132 | + | ... | |
| 133 | + | Directory := LazarusIDE.GetPrimaryConfigPath; | |
| 203 | 134 | ``` | |
| 204 | 135 | ||
| 205 | - | ||
| 206 | - | ||
| 207 | - | ||
| 136 | + | Los paquetes pueden crear su propios ficheros xml con: | |
| 208 | 137 | ||
| 209 | - | ||
| 138 | + | ``` pascal | |
| 210 | 139 | uses | |
| 211 | - | ||
| 212 | - | ||
| 213 | - | ||
| 214 | - | ||
| 215 | - | ||
| 216 | - | ||
| 217 | - | ||
| 218 | - | ||
| 219 | - | ||
| 220 | - | ||
| 221 | - | ||
| 222 | - | ||
| 223 | - | ||
| 224 | - | ||
| 225 | - | ||
| 226 | - | ||
| 227 | - | ||
| 228 | - | ||
| 229 | - | ||
| 230 | - | ||
| 231 | - | ||
| 232 | - | ||
| 233 | - | ||
| 234 | - | ||
| 235 | - | ||
| 236 | - | ||
| 237 | - | ||
| 238 | - | ||
| 239 | - | ||
| 240 | - | ||
| 241 | - | ||
| 242 | - | ||
| 243 | - | ||
| 244 | - | ||
| 245 | - | ||
| 246 | - | ||
| 247 | - | ||
| 248 | - | ||
| 249 | - | ||
| 250 | - | ||
| 251 | - | ||
| 252 | - | ||
| 253 | - | ||
| 254 | - | ||
| 255 | - | ||
| 256 | - | ||
| 257 | - | ||
| 258 | - | ||
| 259 | - | ||
| 260 | - | ||
| 261 | - | ||
| 262 | - | ||
| 263 | - | ||
| 264 | - | ||
| 265 | - | ||
| 266 | - | ||
| 267 | - | ||
| 268 | - | ||
| 140 | + | ..., LCLProc, BaseIDEIntf, LazConfigStorage; | |
| 141 | + | ||
| 142 | + | const | |
| 143 | + | Version = 1; | |
| 144 | + | var | |
| 145 | + | Config: TConfigStorage; | |
| 146 | + | SomeValue: String; | |
| 147 | + | SomeInteger: Integer; | |
| 148 | + | SomeBoolean: Boolean; | |
| 149 | + | FileVersion: LongInt; | |
| 150 | + | begin | |
| 151 | + | SomeValue:='Default'; | |
| 152 | + | SomeInteger:=3; | |
| 153 | + | SomeBoolean:=true; | |
| 154 | + | ||
| 155 | + | // Salva configuraciones. | |
| 156 | + | try | |
| 157 | + | Config:=GetIDEConfigStorage('mysettings.xml',false); | |
| 158 | + | try | |
| 159 | + | // Almacena el número de versión de forma que las extensiones futuras puedan manejar ficheros de configuración antiguos. | |
| 160 | + | Config.SetDeleteValue('Path/To/The/Version',Version,0); | |
| 161 | + | // Almacena la variable de cadena "SomeValue". | |
| 162 | + | // Si SomeValue tiene el valor por defecto entonces la entrada no se almacena, | |
| 163 | + | // de forma que únicamente se almacena las diferencias al valor por defecto. | |
| 164 | + | // Así el xml se mantiene pequeño y su valor por defecto puede cambiar en el futuro. | |
| 165 | + | Config.SetDeleteValue('Path/To/Some/Value',SomeValue,'Default'); | |
| 166 | + | Config.SetDeleteValue('Path/To/Some/Integer',SomeInteger,3); | |
| 167 | + | Config.SetDeleteValue('Path/To/Some/Boolean',SomeBoolean,true); | |
| 168 | + | // there are more overloads for SetDeleteValue, find out with Ctrl+Space | |
| 169 | + | finally | |
| 170 | + | Config.Free; | |
| 269 | 171 | end; | |
| 172 | + | ||
| 173 | + | except | |
| 174 | + | on E: Exception do begin | |
| 175 | + | DebugLn(['Saving mysettings.xml failed: ',E.Message]); | |
| 176 | + | end; | |
| 177 | + | end; | |
| 178 | + | ||
| 179 | + | // load settings | |
| 180 | + | try | |
| 181 | + | Config:=GetIDEConfigStorage('mysettings.xml',true); | |
| 182 | + | try | |
| 183 | + | // read the version of the config | |
| 184 | + | FileVersion:=Config.GetValue('Path/To/The/Version',0); | |
| 185 | + | // read a string variable "SomeValue". If the entry does not exist, use | |
| 186 | + | // the Default | |
| 187 | + | SomeValue:=Config.GetValue('Path/To/Some/Value','Default'); | |
| 188 | + | SomeInteger:=Config.GetValue('Path/To/Some/Integer',3); | |
| 189 | + | SomeBoolean:=Config.GetValue('Path/To/Some/Boolean',true); | |
| 190 | + | finally | |
| 191 | + | Config.Free; | |
| 192 | + | end; | |
| 193 | + | except | |
| 194 | + | on E: Exception do begin | |
| 195 | + | DebugLn(['Loading mysettings.xml failed: ',E.Message]); | |
| 196 | + | end; | |
| 197 | + | end; | |
| 198 | + | end; | |
| 270 | 199 | ``` | |
| 271 | 200 | ||
| 272 | - | ||
| 201 | + | Notes: | |
| 273 | 202 | ||
| 274 | - | ||
| 275 | - | ||
| 276 | - | ||
| 203 | + | - Every IDE plugin should use its own config file. Especially you must not use the standard IDE option files like [[editoroptions.xml]] or [[environmentoptions.xml]]. | |
| 204 | + | - GetIDEConfigStorage when loading checks if the file exists and if not it will copy the template from the secondary config directory. | |
| 205 | + | - Since 0.9.31 you can use this function to load a file outside the primary config directory. | |
| 277 | 206 | ||
| 278 | 207 | # Components | |
| 279 | 208 | ||
| 280 | 209 | ## Extending existing components | |
| 281 | 210 | ||
| 282 | - | ||
| 211 | + | Source: [1](http://lazarus.freepascal.org/index.php/topic,17733.msg98425.html#msg98425) It is straightforward to customise existing LCL components, e.g. if you want to add properties. | |
| 283 | 212 | ||
| 284 | - | ||
| 213 | + | Add the properties you need with appropriate setter and getter methods and storage fields. | |
| 285 | 214 | ||
| 286 | - | ||
| 215 | + | Then instantiate them 'by hand', giving an owner component (to handle later destruction), and set Parent and possibly Top and Left and any other defaults your component needs when initialized. | |
| 287 | 216 | ||
| 288 | - | ||
| 217 | + | When you are satisfied that your customised component is debugged, add a RegisterComponent() call to stick it on the IDE Component Palette and save you having to do the setup code 'by hand' (look at any component's source to see how to do this). | |
| 289 | 218 | ||
| 290 | - | ||
| 291 | - | ||
| 219 | + | Here is a simple example: | |
| 220 | + | ||
| 221 | + | ``` pascal | |
| 292 | 222 | unit Unit1; | |
| 293 | - | ||
| 294 | - | ||
| 295 | - | ||
| 296 | - | ||
| 297 | - | ||
| 298 | - | ||
| 299 | - | ||
| 300 | - | ||
| 301 | - | ||
| 302 | - | ||
| 303 | - | ||
| 304 | - | ||
| 305 | - | ||
| 306 | - | ||
| 307 | - | ||
| 308 | - | ||
| 309 | - | ||
| 310 | - | ||
| 311 | - | ||
| 312 | - | ||
| 313 | - | ||
| 314 | - | ||
| 315 | - | ||
| 316 | - | ||
| 317 | - | ||
| 318 | - | ||
| 319 | - | ||
| 320 | - | ||
| 321 | - | ||
| 322 | - | ||
| 323 | - | ||
| 324 | - | ||
| 325 | - | ||
| 326 | - | ||
| 327 | - | ||
| 328 | - | ||
| 329 | - | ||
| 330 | - | ||
| 331 | - | ||
| 332 | - | ||
| 333 | - | ||
| 334 | - | ||
| 335 | - | ||
| 336 | - | ||
| 337 | - | ||
| 338 | - | ||
| 339 | - | ||
| 340 | - | ||
| 341 | - | ||
| 342 | - | ||
| 343 | - | ||
| 344 | - | ||
| 345 | - | ||
| 346 | - | ||
| 347 | - | ||
| 348 | - | ||
| 349 | - | ||
| 350 | - | ||
| 351 | - | ||
| 352 | - | ||
| 353 | - | ||
| 354 | - | ||
| 355 | - | ||
| 356 | - | ||
| 357 | - | ||
| 358 | - | ||
| 359 | - | ||
| 360 | - | ||
| 361 | - | ||
| 223 | + | ||
| 224 | + | {$mode objfpc}{$H+} | |
| 225 | + | ||
| 226 | + | interface | |
| 227 | + | ||
| 228 | + | uses | |
| 229 | + | Classes, SysUtils, Forms, StdCtrls; | |
| 230 | + | ||
| 231 | + | type | |
| 232 | + | TEdX = class(TEdit) | |
| 233 | + | private | |
| 234 | + | FNewIntProp: integer; | |
| 235 | + | FNewStrProp: string; | |
| 236 | + | procedure SetNewIntProp(AValue: integer); | |
| 237 | + | procedure SetNewStrProp(AValue: string); | |
| 238 | + | public | |
| 239 | + | constructor Create(theComponent: TComponent); override; | |
| 240 | + | property NewIntProp: integer read FNewIntProp write SetNewIntProp; | |
| 241 | + | property NewStrProp: string read FNewStrProp write SetNewStrProp; | |
| 242 | + | end; | |
| 243 | + | ||
| 244 | + | TForm1 = class(TForm) | |
| 245 | + | procedure FormCreate(Sender: TObject); | |
| 246 | + | private | |
| 247 | + | edX: TEdX; | |
| 248 | + | public | |
| 249 | + | end; | |
| 250 | + | ||
| 251 | + | var | |
| 252 | + | Form1: TForm1; | |
| 253 | + | ||
| 254 | + | implementation | |
| 255 | + | ||
| 256 | + | { TForm1 } | |
| 257 | + | ||
| 258 | + | procedure TForm1.FormCreate(Sender: TObject); | |
| 259 | + | begin | |
| 260 | + | edX:= TEdX.Create(Self); | |
| 261 | + | edX.Parent:= Self; | |
| 262 | + | edX.Caption:= IntToStr(edX.NewIntProp); | |
| 263 | + | Caption:= edX.NewStrProp; | |
| 264 | + | end; | |
| 265 | + | ||
| 266 | + | {$R *.lfm} | |
| 267 | + | ||
| 268 | + | { TEdX } | |
| 269 | + | ||
| 270 | + | procedure TEdX.SetNewIntProp(AValue: integer); | |
| 271 | + | begin | |
| 272 | + | if FNewIntProp=AValue then Exit; | |
| 273 | + | FNewIntProp:=AValue; | |
| 274 | + | // add custom code here | |
| 275 | + | end; | |
| 276 | + | ||
| 277 | + | procedure TEdX.SetNewStrProp(AValue: string); | |
| 278 | + | begin | |
| 279 | + | if FNewStrProp=AValue then Exit; | |
| 280 | + | FNewStrProp:=AValue; | |
| 281 | + | // add custom code here | |
| 282 | + | end; | |
| 283 | + | ||
| 284 | + | constructor TEdX.Create(theComponent: TComponent); | |
| 285 | + | begin | |
| 286 | + | inherited Create(theComponent); | |
| 287 | + | FNewStrProp:= 'new string property value'; | |
| 288 | + | FNewIntProp:= 99; | |
| 289 | + | end; | |
| 290 | + | ||
| 291 | + | end. | |
| 362 | 292 | ``` | |
| 363 | 293 | ||
| 364 | 294 | ## Writing components | |
| 365 | 295 | ||
| 366 | - | ||
| 296 | + | *Main article: [[How To Write Lazarus Component]]* | |
| 367 | 297 | ||
| 368 | - | ||
| 298 | + | You can create new components via the package editor. | |
| 369 | 299 | ||
| 370 | - | ||
| 300 | + | Create or open a package, click on **add**, click on **New Component**, fill in the items: Ancestor Type = TButton, New class name = TMyButton, palette page = Misc, Unit file name = mybutton.pas (this file will be created), unit name MyButton and click **ok**. | |
| 371 | 301 | ||
| 372 | 302 | ### Giving a new component an icon for the component palette | |
| 373 | 303 | ||
| 374 | - | ||
| 375 | - | ||
| 304 | + | Create an image file of the format .bmp, .xpm or .png with the same name as the component class. For example *tmybutton.png* and save it in the package source directory. 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 resource file with the lazres tool, which can be found in the lazarus/tools directory: | |
| 305 | + | ||
| 306 | + | ``` bash | |
| 376 | 307 | ~/lazarus/tools/lazres mybutton.lrs tmybutton.png | |
| 377 | - | ||
| 378 | - | ||
| 308 | + | # note: Laz trunk/1.4+? uses .res resource files instead of .lrs files: | |
| 309 | + | ~/lazarus/tools/lazres mybutton.res tmybutton.png | |
| 379 | 310 | ``` | |
| 380 | 311 | ||
| 381 | - | ||
| 382 | - | ||
| 312 | + | This creates an pascal include file, which is used in the initialization section of mybutton.pas: | |
| 313 | + | ||
| 314 | + | ``` pascal | |
| 383 | 315 | initialization | |
| 384 | - | ||
| 385 | - | ||
| 386 | - | ||
| 316 | + | {$I mybutton.lrs} | |
| 317 | + | // or in newer Lazarus version - to docheck syntax | |
| 318 | + | {$R mybutton.res} | |
| 387 | 319 | ``` | |
| 388 | 320 | ||
| 389 | - | ||
| 321 | + | Install the package. | |
| 390 | 322 | ||
| 391 | 323 | ### Hiding a component in the component palette | |
| 392 | 324 | ||
| 393 | - | ||
| 394 | - | ||
| 395 | - | ||
| 396 | - | ||
| 325 | + | Package IDEIntf, unit componentreg: | |
| 397 | 326 | ||
| 327 | + | `IDEComponentPalette.FindComponent('TButton').Visible:=false;` | |
| 328 | + | ||
| 398 | 329 | ## Writing component editors | |
| 399 | 330 | ||
| 400 | - | ||
| 331 | + | A component editor handles things like double clicking on a component in a designer or adding menu items when right clicking on a component. Writing a component editor is easy. See the unit componenteditors.pas of the package IDEIntf for lots of examples. For instance to show an editor when double clicking see TCheckListBoxComponentEditor. | |
| 401 | 332 | ||
| 402 | 333 | ## Writing property editors | |
| 403 | 334 | ||
| 404 | - | ||
| 335 | + | Each type of property (integer, string, TFont, ...) in the Object Inspector needs a property editor. If your component has a property *Password* of type string, then you can define a property editor for your specific component class, with a property named *Password* of type string. The unit propedits.pp of the package IDEIntf contains many of the standard property editors used by the IDE itself. For example the TStringPropertyEditor is the default property editor for all strings, while TComponentNamePropertyEditor is more specific and handles only TComponent.Name. See the unit for plenty of examples. | |
| 405 | 336 | ||
| 406 | 337 | ### Hiding a property in the Object Inspector | |
| 407 | 338 | ||
| 408 | - | ||
| 339 | + | There is a special property editor for hiding: | |
| 409 | 340 | ||
| 410 | - | ||
| 411 | - | ||
| 412 | - | ||
| 413 | - | ||
| 341 | + | ` RegisterPropertyEditor(TypeInfo(TAnchorSide), TControl, 'AnchorSideLeft', THiddenPropertyEditor);` | |
| 414 | 342 | ||
| 415 | - | ||
| 343 | + | # Forms | |
| 416 | 344 | ||
| 417 | - | ||
| 345 | + | The IDE allows to easily create descendants of forms and frames. These forms can have new published components and new published methods. But you when you add new published properties, they are not accessible via the Object Inspector. They work only at runtime. The methods in the IDE are fake, they can not be executed. The IDE can create the components, because their classes are registered in the component palette. Your new properties only exist in your source code. The IDE can not fake them yet. That's why you have to register the new class. That means: | |
| 418 | 346 | ||
| 419 | - | ||
| 347 | + | - create a design time package (or extend an existing one) | |
| 348 | + | - your form must be in a unit of this package | |
| 420 | 349 | ||
| 421 | - | ||
| 350 | + | ``` pascal | |
| 351 | + | ... | |
| 352 | + | interface | |
| 422 | 353 | ||
| 423 | - | ||
| 424 | - | ||
| 354 | + | uses FormEditingIntf, Forms; | |
| 425 | 355 | ||
| 426 | - | ||
| 356 | + | type | |
| 357 | + | TYourForm = class(TForm) | |
| 358 | + | private | |
| 359 | + | FYourProperty: integer; | |
| 360 | + | published | |
| 361 | + | property YourProperty: integer read FYourProperty write FYourProperty; | |
| 362 | + | end; | |
| 363 | + | ||
| 364 | + | procedure Register; | |
| 365 | + | ||
| 366 | + | implementation | |
| 367 | + | ||
| 368 | + | procedure Register; | |
| 369 | + | begin | |
| 370 | + | FormEditingHook.RegisterDesignerBaseClass(TYourForm); | |
| 371 | + | end; | |
| 427 | 372 | ... | |
| 428 | - | ||
| 429 | - | ||
| 430 | - | ||
| 431 | - | ||
| 432 | - | ||
| 433 | - | ||
| 434 | - | ||
| 435 | - | ||
| 436 | - | ||
| 437 | - | ||
| 438 | - | ||
| 439 | - | ||
| 440 | - | ||
| 441 | - | ||
| 442 | - | ||
| 443 | - | ||
| 444 | - | ||
| 445 | - | ||
| 446 | - | ||
| 447 | - | ||
| 448 | - | ||
| 449 | 373 | ``` | |
| 450 | 374 | ||
| 451 | - | ||
| 452 | - | ||
| 375 | + | - check the "Register" in the package editor for this unit. | |
| 376 | + | - Install the package in the IDE | |
| 453 | 377 | ||
| 454 | 378 | # Designer | |
| 455 | 379 | ||
| 456 | 380 | ## Writing a designer mediator | |
| 457 | 381 | ||
| 458 | - | ||
| 382 | + | The standard designer allows to visually edit LCL controls, while all others are shown as icons(like TOpenDialog or TDataSource). To visually edit non LCL control, you need to create a **designer mediator**. This can be used to design webpages, UML diagrams or other widgetsets like [[fpGUI]]. There is a complete example in examples/designnonlcl/. | |
| 459 | 383 | ||
| 460 | - | ||
| 461 | - | ||
| 462 | - | ||
| 384 | + | - Install the example package examples/designnonlcl/notlcldesigner.lpk and restart the IDE. This will register the designer mediator for TMyWidget components and add the new components TMyButton, TMyGroupBox to the component palette. | |
| 385 | + | - Open the the example project examples/designnonlcl/project/NonLCL1.lpi. | |
| 386 | + | - Open the unit1.pas and show the designer form (F12). You should see the components as red rectangles, which can be selected, moved and resized like LCL controls. | |
| 463 | 387 | ||
| 464 | 388 | ## Create a new unique component name | |
| 465 | - | ||
| 389 | + | ||
| 390 | + | ``` pascal | |
| 466 | 391 | uses FormEditingIntf; | |
| 467 | - | ||
| 468 | - | ||
| 469 | - | ||
| 470 | - | ||
| 471 | - | ||
| 472 | - | ||
| 473 | - | ||
| 474 | - | ||
| 475 | - | ||
| 476 | - | ||
| 392 | + | ||
| 393 | + | ... | |
| 394 | + | ||
| 395 | + | NewName:=FormEditingHook.CreateUniqueComponentName(AComponent); | |
| 396 | + | ||
| 397 | + | // Or if you need to create the name before creating the component: | |
| 398 | + | ||
| 399 | + | NewName:=FormEditingHook.CreateUniqueComponentName(ComponentClassName,OwnerComponent); | |
| 400 | + | // ComponentClassName will be used as prefix, without a leading T. | |
| 401 | + | // OwnerComponent is the new owner of the new component. | |
| 477 | 402 | ``` | |
| 478 | 403 | ||
| 479 | 404 | ## Select a component in the designer/object inspector | |
| 480 | - | ||
| 405 | + | ||
| 406 | + | ``` pascal | |
| 481 | 407 | uses propedits; | |
| 482 | - | ||
| 483 | - | ||
| 408 | + | .. | |
| 409 | + | GlobalDesignHook.SelectOnlyThis(AComponent); | |
| 484 | 410 | ``` | |
| 485 | 411 | ||
| 486 | 412 | ## Get unit, designer, form of a file | |
| 487 | - | ||
| 413 | + | ||
| 414 | + | ``` pascal | |
| 488 | 415 | uses ProjectIntf, LazIDEIntf, ComponentEditors; | |
| 489 | - | ||
| 490 | - | ||
| 491 | - | ||
| 492 | - | ||
| 493 | - | ||
| 494 | - | ||
| 495 | - | ||
| 496 | - | ||
| 497 | - | ||
| 498 | - | ||
| 499 | - | ||
| 416 | + | ... | |
| 417 | + | // open file | |
| 418 | + | if LazarusIDE.DoOpenEditorFile(Filename,-1,-1,[ofAddToRecent])<>mrOk then exit; | |
| 419 | + | // get file interface | |
| 420 | + | aFile:=LazarusIDE.ActiveProject.FindFile(Filename,[]); | |
| 421 | + | // get designer | |
| 422 | + | aDesigner:=TComponentEditorDesigner(LazarusIDE.GetDesignerWithProjectFile(AFile,true)); | |
| 423 | + | if aDesigner=nil then | |
| 424 | + | exit; // this unit has no resource (form, frame, datamodule, etc.) | |
| 425 | + | // get form | |
| 426 | + | aForm:=aDesigner.Form; | |
| 500 | 427 | ``` | |
| 501 | 428 | ||
| 502 | 429 | ## Save unit, designer form | |
| 503 | - | ||
| 430 | + | ||
| 431 | + | ``` pascal | |
| 504 | 432 | uses LazIDEIntf; | |
| 505 | - | ||
| 506 | - | ||
| 433 | + | ... | |
| 434 | + | if LazarusIDE.DoSaveEditorFile(Filename,[])<>mrOk then exit; | |
| 507 | 435 | ``` | |
| 508 | 436 | ||
| 509 | 437 | # Event handlers | |
| 510 | 438 | ||
| 511 | - | ||
| 439 | + | There are several events in the IDE, for which plugins can add their own handlers. | |
| 512 | 440 | ||
| 513 | 441 | ## Designer events | |
| 514 | 442 | ||
| 515 | - | ||
| 443 | + | 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. | |
| 516 | 444 | ||
| 517 | - | ||
| 445 | + | Examples: | |
| 518 | 446 | ||
| 519 | - | ||
| 447 | + | - Adding your handler (this is normally done in the constructor of your object): | |
| 520 | 448 | ||
| 521 | - | ||
| 522 | - | ||
| 523 | - | ||
| 449 | + | ` GlobalDesignHook.AddHandlerPersistentAdded(@YourOnPersistentAdded);` | |
| 524 | 450 | ||
| 525 | - | ||
| 451 | + | - Removing your handler: | |
| 526 | 452 | ||
| 527 | - | ||
| 528 | - | ||
| 529 | - | ||
| 453 | + | ` GlobalDesignHook.RemoveHandlerPersistentAdded(@YourOnPersistentAdded);` | |
| 530 | 454 | ||
| 531 | - | ||
| 455 | + | - You can remove all handlers at once. For example, it is a good idea to add this line in the destructor of your object: | |
| 532 | 456 | ||
| 533 | - | ||
| 534 | - | ||
| 535 | - | ||
| 457 | + | ` GlobalDesignHook.RemoveAllHandlersForObject(Self);` | |
| 536 | 458 | ||
| 537 | - | ||
| 459 | + | The handlers of GlobalDesignHook: | |
| 538 | 460 | ||
| 539 | - | ||
| 540 | - | ||
| 541 | - | ||
| 542 | - | ||
| 543 | - | ||
| 544 | - | ||
| 545 | - | ||
| 546 | - | ||
| 547 | - | ||
| 548 | - | ||
| 549 | - | ||
| 550 | - | ||
| 551 | - | ||
| 552 | - | ||
| 553 | - | ||
| 554 | - | ||
| 555 | - | ||
| 556 | - | ||
| 557 | - | ||
| 558 | - | ||
| 559 | - | ||
| 560 | - | ||
| 561 | - | ||
| 562 | - | ||
| 563 | - | ||
| 564 | - | ||
| 565 | - | ||
| 566 | - | ||
| 567 | - | ||
| 568 | - | ||
| 569 | - | ||
| 570 | - | ||
| 571 | - | ||
| 572 | - | ||
| 461 | + | - Lookup root | |
| 462 | + | - ChangeLookupRoot - Called when the "LookupRoot" changed. The "LookupRoot" is the owner object of the currently selected components. Normally this is a TForm. | |
| 463 | + | - Methods | |
| 464 | + | - CreateMethod | |
| 465 | + | - GetMethodName | |
| 466 | + | - GetMethods | |
| 467 | + | - MethodExists | |
| 468 | + | - RenameMethod | |
| 469 | + | - ShowMethod | |
| 470 | + | - MethodFromAncestor | |
| 471 | + | - ChainCall | |
| 472 | + | - Components | |
| 473 | + | - GetComponent | |
| 474 | + | - GetComponentName | |
| 475 | + | - GetComponentNames | |
| 476 | + | - GetRootClassName | |
| 477 | + | - AddClicked - Called when the user selected a component class and clicked on the designer to add a new component. You can change the component class and the parent. | |
| 478 | + | - ComponentRenamed - Called when a component was renamed | |
| 479 | + | - TPersistent objects | |
| 480 | + | - PersistentAdded - Called when a new TPersistent was added to the LookupRoot | |
| 481 | + | - PersistentDeleting - Called before a TPersistent is freed. | |
| 482 | + | - DeletePersistent - Called by the IDE to delete a TPersistent. | |
| 483 | + | - GetSelectedPersistents - Called when getting the current selection of TPersistent. | |
| 484 | + | - SetSelectedPersistents - Called when setting the current selection of TPersistent. | |
| 485 | + | - GetObject | |
| 486 | + | - GetObjectName | |
| 487 | + | - GetObjectNames | |
| 488 | + | - Modifing | |
| 489 | + | - Modified | |
| 490 | + | - Revert | |
| 491 | + | - RefreshPropertyValues | |
| 492 | + | - Selection | |
| 493 | + | - SetSelection | |
| 494 | + | - GetSelection | |
| 573 | 495 | ||
| 574 | 496 | ### Examples for designer events | |
| 575 | 497 | ||
| 576 | 498 | #### Example: When dropping a new component move control to a child | |
| 577 | - | ||
| 499 | + | ||
| 500 | + | ``` pascal | |
| 578 | 501 | ... | |
| 579 | - | ||
| 580 | - | ||
| 581 | - | ||
| 582 | - | ||
| 583 | - | ||
| 584 | - | ||
| 585 | - | ||
| 586 | - | ||
| 587 | - | ||
| 588 | - | ||
| 589 | - | ||
| 590 | - | ||
| 591 | - | ||
| 592 | - | ||
| 593 | - | ||
| 594 | - | ||
| 595 | - | ||
| 596 | - | ||
| 597 | - | ||
| 598 | - | ||
| 599 | - | ||
| 600 | - | ||
| 601 | - | ||
| 602 | - | ||
| 603 | - | ||
| 604 | - | ||
| 605 | - | ||
| 606 | - | ||
| 607 | - | ||
| 608 | - | ||
| 609 | - | ||
| 610 | - | ||
| 611 | - | ||
| 612 | - | ||
| 613 | - | ||
| 614 | - | ||
| 615 | - | ||
| 616 | - | ||
| 617 | - | ||
| 618 | - | ||
| 619 | - | ||
| 502 | + | type | |
| 503 | + | TYourDesignerExtension = class | |
| 504 | + | private | |
| 505 | + | function AddClicked(ADesigner: TIDesigner; | |
| 506 | + | MouseDownComponent: TComponent; Button: TMouseButton; | |
| 507 | + | Shift: TShiftState; X, Y: Integer; | |
| 508 | + | var AComponentClass: TComponentClass; | |
| 509 | + | var NewParent: TComponent): boolean of object; | |
| 510 | + | public | |
| 511 | + | constructor Create; | |
| 512 | + | destructor Destroy; override; | |
| 513 | + | end; | |
| 514 | + | ||
| 515 | + | ... | |
| 516 | + | constructor TYourDesignerExtension.Create; | |
| 517 | + | begin | |
| 518 | + | // register your handler | |
| 519 | + | GlobalDesignHook.AddHandlerAddClicked(@AddClicked); | |
| 520 | + | end; | |
| 521 | + | ||
| 522 | + | destructor TYourDesignerExtension.Destroy; | |
| 523 | + | begin | |
| 524 | + | // remove your handler: | |
| 525 | + | GlobalDesignHook.RemoveHandlerAddClicked(@AddClicked); | |
| 526 | + | end; | |
| 527 | + | ||
| 528 | + | function TYourDesignerExtension.AddClicked(ADesigner: TIDesigner; | |
| 529 | + | MouseDownComponent: TComponent; Button: TMouseButton; | |
| 530 | + | Shift: TShiftState; X, Y: Integer; | |
| 531 | + | var AComponentClass: TComponentClass; | |
| 532 | + | var NewParent: TComponent): boolean of object; | |
| 533 | + | begin | |
| 534 | + | // in this example TYourControl is a custom control with a ChildControl. | |
| 535 | + | // Whenever the user drops a control on the TYourControl instead of adding | |
| 536 | + | // the new control to the TYourControl, the new control is added as child | |
| 537 | + | // of ChildControl. | |
| 538 | + | // created | |
| 539 | + | if MouseDownComponent is TYourControl then | |
| 540 | + | NewParent:=TYourControl(MouseDownComponent).ChildControl; | |
| 541 | + | Result:=true; | |
| 542 | + | end; | |
| 620 | 543 | ``` | |
| 621 | 544 | ||
| 622 | 545 | ### Disabling the designer mouse handler | |
| 623 | 546 | ||
| 624 | - | ||
| 625 | - | ||
| 547 | + | Normally the designer catches all mouse events of a component. If your custom control should handle the mouse events handle you can either set the **csDesignInteractive** **ControlStyle** or you can fine control it via the message *CM_DESIGNHITTEST* in your control: | |
| 548 | + | ||
| 549 | + | ``` pascal | |
| 626 | 550 | type | |
| 627 | - | ||
| 628 | - | ||
| 629 | - | ||
| 630 | - | ||
| 631 | - | ||
| 632 | - | ||
| 633 | - | ||
| 634 | - | ||
| 635 | - | ||
| 636 | - | ||
| 637 | - | ||
| 638 | - | ||
| 639 | - | ||
| 640 | - | ||
| 641 | - | ||
| 642 | - | ||
| 551 | + | TYourControl = class(TCustomControl) | |
| 552 | + | protected | |
| 553 | + | procedure CMDesignHitTest(var Message: TLMessage); message CM_DESIGNHITTEST; | |
| 554 | + | end; | |
| 555 | + | ... | |
| 556 | + | procedure TYourControl.CMDesignHitTest(var Message: TLMessage); | |
| 557 | + | var | |
| 558 | + | p: TSmallPoint; | |
| 559 | + | aShiftState: TShiftState; | |
| 560 | + | begin | |
| 561 | + | aShiftState:=KeysToShiftState(PtrUInt(Message.WParam)); | |
| 562 | + | p:=TSmallPoint(longint(Message.LParam)); | |
| 563 | + | debugln(['TForm1.CMDesignHitTest ShiftState=',dbgs(aShiftState),' x=',p.x,' y=',p.y]); | |
| 564 | + | if SkipDesignerMouseHandler then | |
| 565 | + | Message.Result:=1; // now the designer calls the normal MouseUp, MouseMove and MouseDown methods. | |
| 566 | + | end; | |
| 643 | 567 | ``` | |
| 644 | 568 | ||
| 645 | 569 | ## Getting notified when a designer form is modified | |
| 646 | 570 | ||
| 647 | - | ||
| 648 | - | ||
| 571 | + | Every designed LCL form has a Designer of type TIDesigner. The IDE creates designers of type TComponentEditorDesigner defined in the IDEIntf unit componenteditors. For example: | |
| 572 | + | ||
| 573 | + | ``` pascal | |
| 649 | 574 | procedure TYourAddOn.OnDesignerModified(Sender: TObject); | |
| 650 | - | ||
| 651 | - | ||
| 652 | - | ||
| 653 | - | ||
| 654 | - | ||
| 655 | - | ||
| 656 | - | ||
| 657 | - | ||
| 658 | - | ||
| 659 | - | ||
| 660 | - | ||
| 661 | - | ||
| 662 | - | ||
| 663 | - | ||
| 575 | + | var | |
| 576 | + | IDEDesigner: TComponentEditorDesigner; | |
| 577 | + | begin | |
| 578 | + | IDEDesigner:=TComponentEditorDesigner(Sender); | |
| 579 | + | ... | |
| 580 | + | end; | |
| 581 | + | ||
| 582 | + | procedure TYourAddOn.ConnectDesignerForm(Form1: TCustomForm); | |
| 583 | + | var | |
| 584 | + | IDEDesigner: TComponentEditorDesigner; | |
| 585 | + | begin | |
| 586 | + | IDEDesigner:=TComponentEditorDesigner(Form1.Designer); | |
| 587 | + | IDEDesigner.AddHandlerModified(@OnDesignerModified); | |
| 588 | + | end; | |
| 664 | 589 | ``` | |
| 665 | 590 | ||
| 666 | 591 | ## Project events | |
| 667 | 592 | ||
| 668 | - | ||
| 593 | + | These events are defined in unit LazIDEIntf. | |
| 669 | 594 | ||
| 670 | - | ||
| 671 | - | ||
| 672 | - | ||
| 673 | - | ||
| 674 | - | ||
| 675 | - | ||
| 676 | - | ||
| 677 | - | ||
| 595 | + | - **LazarusIDE.AddHandlerOnProjectClose**: called before a project is closed | |
| 596 | + | - **LazarusIDE.AddHandlerOnProjectOpened**: called after the project was completely opened (for example all required packages were loaded, units were opened in the source editor) | |
| 597 | + | - **LazarusIDE.AddHandlerOnSavingAll**: called before IDE saves everything | |
| 598 | + | - **LazarusIDE.AddHandlerOnSavedAll**: called after IDE saved everything | |
| 599 | + | - **LazarusIDE.AddHandlerOnProjectBuilding**: called before IDE builds the project | |
| 600 | + | - **LazarusIDE.AddHandlerOnProjectDependenciesCompiling**: called before IDE compiles package dependencies of project | |
| 601 | + | - **LazarusIDE.AddHandlerOnProjectDependenciesCompiled**: called after IDE compiled package dependencies of project | |
| 602 | + | - **LazarusIDE.AddHandlerOnProjectBuildingFinished**: called after IDE built the project (successful or not) (since 1.5) | |
| 678 | 603 | ||
| 679 | 604 | ## Other IDE events | |
| 680 | 605 | ||
| 681 | - | ||
| 606 | + | uses LazIDEIntf; | |
| 682 | 607 | ||
| 683 | - | ||
| 608 | + | Call these in the Register procedure of your package: | |
| 684 | 609 | ||
| 685 | - | ||
| 686 | - | ||
| 687 | - | ||
| 688 | - | ||
| 689 | - | ||
| 690 | - | ||
| 691 | - | ||
| 692 | - | ||
| 693 | - | ||
| 694 | - | ||
| 695 | - | ||
| 696 | - | ||
| 610 | + | - **LazarusIDE.AddHandlerOnIDERestoreWindows**: called when IDE is restores its windows (before opening the first project) | |
| 611 | + | - **LazarusIDE.AddHandlerOnIDEClose**: called when IDE is shutting down (after closequery, so no more interactivity) | |
| 612 | + | - **LazarusIDE.AddHandlerOnQuickSyntaxCheck**: called when the menu item or the shortcut for Quick syntax check is executed | |
| 613 | + | - **LazarusIDE.AddHandlerOnLazarusBuilding**: // called before IDE builds Lazarus IDE (since 1.5) | |
| 614 | + | - **LazarusIDE.AddHandlerOnLazarusBuildingFinished**: // called after IDE builds Lazarus IDE (since 1.5) | |
| 615 | + | - **LazarusIDE.AddHandlerGetFPCFrontEndParams**: // called when the IDE gets the parameters of the 'fpc' front end tool (since 1.5) | |
| 616 | + | - **LazarusIDE.AddHandlerGetFPCFrontEndPath**: // called when the IDE gets the path of the 'fpc' front end tool (since 1.5) | |
| 617 | + | - **LazarusIDE.AddHandlerOnUpdateIDEComponentPalette**: ? | |
| 618 | + | - **LazarusIDE.AddHandlerOnUpdateComponentPageControl**: ? | |
| 619 | + | - **LazarusIDE.AddHandlerOnShowDesignerFormOfSource**: // called after showing a designer form for code editor (AEditor can be nil!) (since 1.5) | |
| 620 | + | - **LazarusIDE.AddHandlerOnShowSourceOfActiveDesignerForm**: // called after showing a code of designer form (since 1.5) | |
| 621 | + | - **LazarusIDE.AddHandlerOnChangeToolStatus**: //called when IDEToolStatus has changed (e.g. itNone-\>itBuilder etc.) (since 1.5) | |
| 697 | 622 | ||
| 698 | - | ||
| 623 | + | Call these in the initialization section of one of your units: | |
| 699 | 624 | ||
| 700 | - | ||
| 701 | - | ||
| 702 | - | ||
| 625 | + | - **AddBootHandler** | |
| 626 | + | - AddBootHandler(**libhTransferMacrosCreated**,@YourProc): called after IDEMacros were created (since 1.3) | |
| 627 | + | - AddBootHandler(**libhEnvironmentOptionsLoaded**,@YourProc): called after environment options were loaded (since 1.3) | |
| 703 | 628 | ||
| 704 | 629 | # Project | |
| 705 | 630 | ||
| 706 | 631 | ## Current Project | |
| 707 | 632 | ||
| 708 | - | ||
| 633 | + | The current main project can be obtained by LazarusIDE.ActiveProject. (unit LazIDEIntf) | |
| 709 | 634 | ||
| 710 | 635 | ## All units of current project | |
| 711 | 636 | ||
| 712 | - | ||
| 637 | + | Note that the term "units of project" is ambiguous. | |
| 713 | 638 | ||
| 714 | - | ||
| 715 | - | ||
| 639 | + | - The project inspector shows the list of the .lpi file. The project might not use all these units on all platforms and maybe the developer forgot to add all used units. | |
| 640 | + | - Units from used packages are not project units. | |
| 716 | 641 | ||
| 717 | 642 | ### All units of the project inspector | |
| 718 | 643 | ||
| 719 | - | ||
| 720 | - | ||
| 644 | + | To iterate through all pascal units listed in the project inspector you can use for example: | |
| 645 | + | ||
| 646 | + | ``` pascal | |
| 721 | 647 | uses | |
| 722 | - | ||
| 723 | - | ||
| 724 | - | ||
| 725 | - | ||
| 726 | - | ||
| 727 | - | ||
| 728 | - | ||
| 648 | + | LCLProc, FileUtil, LazIDEIntf, ProjectIntf; | |
| 649 | + | ||
| 650 | + | procedure ListProjectUnits; | |
| 651 | + | var | |
| 652 | + | LazProject: TLazProject; | |
| 653 | + | i: Integer; | |
| 654 | + | LazFile: TLazProjectFile; | |
| 655 | + | begin | |
| 656 | + | LazProject:=LazarusIDE.ActiveProject; | |
| 657 | + | if LazProject<>nil then | |
| 658 | + | for i:=0 to LazProject.FileCount-1 do | |
| 729 | 659 | begin | |
| 730 | - | ||
| 731 | - | ||
| 732 | - | ||
| 733 | - | ||
| 734 | - | ||
| 735 | - | ||
| 736 | - | ||
| 737 | - | ||
| 738 | - | ||
| 739 | - | ||
| 660 | + | LazFile:=LazProject.Files[i]; | |
| 661 | + | if LazFile.IsPartOfProject | |
| 662 | + | and FilenameIsPascalUnit(LazFile.Filename) | |
| 663 | + | then | |
| 664 | + | debugln(LazFile.Filename); | |
| 740 | 665 | end; | |
| 666 | + | end; | |
| 741 | 667 | ``` | |
| 742 | 668 | ||
| 743 | 669 | ### All used units of project | |
| 744 | 670 | ||
| 745 | - | ||
| 746 | - | ||
| 671 | + | To find all currently used units of a project/package you can use the following. Note that the IDE needs to parse all units, so it can take some time. | |
| 672 | + | ||
| 673 | + | ``` pascal | |
| 747 | 674 | uses | |
| 748 | - | ||
| 749 | - | ||
| 750 | - | ||
| 751 | - | ||
| 752 | - | ||
| 753 | - | ||
| 754 | - | ||
| 755 | - | ||
| 756 | - | ||
| 757 | - | ||
| 758 | - | ||
| 759 | - | ||
| 760 | - | ||
| 761 | - | ||
| 762 | - | ||
| 763 | - | ||
| 764 | - | ||
| 765 | - | ||
| 675 | + | LazLoggerBase, LazIDEIntf, ProjectIntf; | |
| 676 | + | ||
| 677 | + | procedure ListProjectUnits; | |
| 678 | + | var | |
| 679 | + | LazProject: TLazProject; | |
| 680 | + | i: Integer; | |
| 681 | + | begin | |
| 682 | + | LazProject:=LazarusIDE.ActiveProject; | |
| 683 | + | if LazProject<>nil then | |
| 684 | + | begin | |
| 685 | + | Units:=LazarusIDE.FindUnitsOfOwner(LazProject,[fuooListed,fuooUsed]); // add fuooPackages to include units from packages | |
| 686 | + | try | |
| 687 | + | for i:=0 to Units.Count-1 do | |
| 688 | + | debugln('Filename=',Units[i]); | |
| 689 | + | finally | |
| 690 | + | Units.Free; | |
| 766 | 691 | end; | |
| 692 | + | end; | |
| 693 | + | end; | |
| 767 | 694 | ``` | |
| 768 | 695 | ||
| 769 | 696 | ## The .lpr, .lpi and .lps file of a project | |
| 770 | - | ||
| 697 | + | ||
| 698 | + | ``` pascal | |
| 771 | 699 | uses | |
| 772 | - | ||
| 773 | - | ||
| 774 | - | ||
| 775 | - | ||
| 776 | - | ||
| 777 | - | ||
| 778 | - | ||
| 779 | - | ||
| 780 | - | ||
| 781 | - | ||
| 782 | - | ||
| 783 | - | ||
| 784 | - | ||
| 785 | - | ||
| 786 | - | ||
| 787 | - | ||
| 788 | - | ||
| 700 | + | LCLProc, FileUtil, ProjectIntf, LazIDEIntf; | |
| 701 | + | var | |
| 702 | + | LazProject: TLazProject; | |
| 703 | + | begin | |
| 704 | + | LazProject:=LazarusIDE.ActiveProject; | |
| 705 | + | // every project has a .lpi file: | |
| 706 | + | DebugLn(['Project'' lpi file: ',LazProject.ProjectInfoFile]); | |
| 707 | + | ||
| 708 | + | // if the project session information is stored in a separate .lps file: | |
| 709 | + | if LazProject.SessionStorage<>pssNone then | |
| 710 | + | DebugLn(['Project'' lps file: ',LazProject.ProjectSessionFile]); | |
| 711 | + | ||
| 712 | + | // If the project has a .lpr file it is the main source file: | |
| 713 | + | if (LazProject.MainFile<>nil) | |
| 714 | + | and (CompareFileExt(LazProject.MainFile.Filename,'lpr')=0) then | |
| 715 | + | DebugLn(['Project has lpr file: ',LazProject.MainFile.Filename]); | |
| 716 | + | end; | |
| 789 | 717 | ``` | |
| 790 | 718 | ||
| 791 | 719 | ## The executable / target file name of a project | |
| 792 | 720 | ||
| 793 | - | ||
| 794 | - | ||
| 721 | + | There is a macro \$(TargetFile), which can be used in paths and external tools. You can query the macro in code: | |
| 722 | + | ||
| 723 | + | ``` pascal | |
| 795 | 724 | uses MacroIntf; | |
| 796 | - | ||
| 797 | - | ||
| 798 | - | ||
| 799 | - | ||
| 800 | - | ||
| 801 | - | ||
| 802 | - | ||
| 725 | + | ||
| 726 | + | function MyGetProjectTargetFile: string; | |
| 727 | + | begin | |
| 728 | + | Result:='$(TargetFile)'; | |
| 729 | + | if not IDEMacros.SubstituteMacros(Result) then | |
| 730 | + | raise Exception.Create('unable to retrieve target file of project'); | |
| 731 | + | end; | |
| 803 | 732 | ``` | |
| 804 | 733 | ||
| 805 | - | ||
| 734 | + | See here for more macros: [[IDE Macros in paths and filenames]]. | |
| 806 | 735 | ||
| 807 | 736 | ## Add your own project type | |
| 808 | 737 | ||
| 809 | - | ||
| 810 | - | ||
| 811 | - | ||
| 812 | - | ||
| 738 | + | You can add items to the 'New ...' dialog: | |
| 813 | 739 | ||
| 814 | - | ||
| 740 | + | - See the unit ProjectIntf of the package IDEIntf. | |
| 741 | + | - See the [[Project Templates]] | |
| 815 | 742 | ||
| 816 | 743 | ## Add your own file type | |
| 817 | 744 | ||
| 818 | - | ||
| 745 | + | You can add items to the 'New ...' dialog: | |
| 819 | 746 | ||
| 820 | - | ||
| 821 | - | ||
| 747 | + | - See the unit ProjectIntf of the package IDEIntf. | |
| 748 | + | - Choose a base class TFileDescPascalUnit for normal units or TFileDescPascalUnitWithResource for a new form/datamodule. | |
| 822 | 749 | ||
| 823 | 750 | ### Add a new file type | |
| 824 | - | ||
| 751 | + | ||
| 752 | + | ``` pascal | |
| 825 | 753 | uses ProjectIntf; | |
| 826 | - | ||
| 827 | - | ||
| 828 | - | ||
| 829 | - | ||
| 830 | - | ||
| 831 | - | ||
| 832 | - | ||
| 833 | - | ||
| 834 | - | ||
| 835 | - | ||
| 836 | - | ||
| 837 | - | ||
| 838 | - | ||
| 839 | - | ||
| 840 | - | ||
| 841 | - | ||
| 842 | - | ||
| 843 | - | ||
| 844 | - | ||
| 845 | - | ||
| 846 | - | ||
| 847 | - | ||
| 848 | - | ||
| 849 | - | ||
| 850 | - | ||
| 851 | - | ||
| 852 | - | ||
| 853 | - | ||
| 854 | - | ||
| 855 | - | ||
| 856 | - | ||
| 857 | - | ||
| 858 | - | ||
| 859 | - | ||
| 860 | - | ||
| 861 | - | ||
| 862 | - | ||
| 863 | - | ||
| 864 | - | ||
| 754 | + | ... | |
| 755 | + | { TFileDescText } | |
| 756 | + | ||
| 757 | + | TFileDescMyText = class(TProjectFileDescriptor) | |
| 758 | + | public | |
| 759 | + | constructor Create; override; | |
| 760 | + | function GetLocalizedName: string; override; | |
| 761 | + | function GetLocalizedDescription: string; override; | |
| 762 | + | end; | |
| 763 | + | ... | |
| 764 | + | ||
| 765 | + | procedure Register; | |
| 766 | + | ||
| 767 | + | implementation | |
| 768 | + | ||
| 769 | + | procedure Register; | |
| 770 | + | begin | |
| 771 | + | RegisterProjectFileDescriptor(TFileDescMyText.Create,FileDescGroupName); | |
| 772 | + | end; | |
| 773 | + | ||
| 774 | + | { TFileDescMyText } | |
| 775 | + | ||
| 776 | + | constructor TFileDescMyText.Create; | |
| 777 | + | begin | |
| 778 | + | inherited Create; | |
| 779 | + | Name:='MyText'; // do not translate this | |
| 780 | + | DefaultFilename:='text.txt'; | |
| 781 | + | AddToProject:=false; | |
| 782 | + | end; | |
| 783 | + | ||
| 784 | + | function TFileDescText.GetLocalizedName: string; | |
| 785 | + | begin | |
| 786 | + | Result:='My Text'; // replace this with a resourcestring | |
| 787 | + | end; | |
| 788 | + | ||
| 789 | + | function TFileDescText.GetLocalizedDescription: string; | |
| 790 | + | begin | |
| 791 | + | Result:='An empty text file'; | |
| 792 | + | end; | |
| 865 | 793 | ``` | |
| 866 | 794 | ||
| 867 | 795 | ### Add a new form type | |
| 868 | - | ||
| 796 | + | ||
| 797 | + | ``` pascal | |
| 869 | 798 | uses ProjectIntf; | |
| 870 | - | ||
| 871 | - | ||
| 872 | - | ||
| 873 | - | ||
| 874 | - | ||
| 875 | - | ||
| 876 | - | ||
| 877 | - | ||
| 878 | - | ||
| 879 | - | ||
| 880 | - | ||
| 881 | - | ||
| 882 | - | ||
| 883 | - | ||
| 884 | - | ||
| 885 | - | ||
| 886 | - | ||
| 887 | - | ||
| 888 | - | ||
| 889 | - | ||
| 890 | - | ||
| 891 | - | ||
| 892 | - | ||
| 893 | - | ||
| 894 | - | ||
| 895 | - | ||
| 896 | - | ||
| 897 | - | ||
| 898 | - | ||
| 899 | - | ||
| 900 | - | ||
| 901 | - | ||
| 902 | - | ||
| 903 | - | ||
| 904 | - | ||
| 905 | - | ||
| 906 | - | ||
| 907 | - | ||
| 908 | - | ||
| 909 | - | ||
| 910 | - | ||
| 911 | - | ||
| 912 | - | ||
| 913 | - | ||
| 799 | + | ||
| 800 | + | ... | |
| 801 | + | TFileDescPascalUnitWithMyForm = class(TFileDescPascalUnitWithResource) | |
| 802 | + | public | |
| 803 | + | constructor Create; override; | |
| 804 | + | function GetInterfaceUsesSection: string; override; | |
| 805 | + | function GetLocalizedName: string; override; | |
| 806 | + | function GetLocalizedDescription: string; override; | |
| 807 | + | end; | |
| 808 | + | ... | |
| 809 | + | ||
| 810 | + | procedure Register; | |
| 811 | + | ||
| 812 | + | implementation | |
| 813 | + | ||
| 814 | + | procedure Register; | |
| 815 | + | begin | |
| 816 | + | RegisterProjectFileDescriptor(TFileDescPascalUnitWithMyForm.Create,FileDescGroupName); | |
| 817 | + | end; | |
| 818 | + | ||
| 819 | + | { TFileDescPascalUnitWithMyForm } | |
| 820 | + | ||
| 821 | + | constructor TFileDescPascalUnitWithMyForm.Create; | |
| 822 | + | begin | |
| 823 | + | inherited Create; | |
| 824 | + | Name:='MyForm'; // do not translate this | |
| 825 | + | ResourceClass:=TMyForm; | |
| 826 | + | UseCreateFormStatements:=true; | |
| 827 | + | end; | |
| 828 | + | ||
| 829 | + | function TFileDescPascalUnitWithMyForm.GetInterfaceUsesSection: string; | |
| 830 | + | begin | |
| 831 | + | Result:='Classes, SysUtils, MyWidgetSet'; | |
| 832 | + | end; | |
| 833 | + | ||
| 834 | + | function TFileDescPascalUnitWithForm.GetLocalizedName: string; | |
| 835 | + | begin | |
| 836 | + | Result:='MyForm'; // replace this with a resourcestring | |
| 837 | + | end; | |
| 838 | + | ||
| 839 | + | function TFileDescPascalUnitWithForm.GetLocalizedDescription: string; | |
| 840 | + | begin | |
| 841 | + | Result:='Create a new MyForm from example package NotLCLDesigner'; | |
| 842 | + | end; | |
| 914 | 843 | ``` | |
| 915 | 844 | ||
| 916 | 845 | # Packages | |
| 917 | 846 | ||
| 918 | - | ||
| 847 | + | You can perform various actions with [[Lazarus Packages|Packages]]: | |
| 919 | 848 | ||
| 920 | 849 | ## Search in all packages | |
| 921 | 850 | ||
| 922 | - | ||
| 923 | - | ||
| 851 | + | Iterate all packages loaded in the IDE (since 0.9.29). | |
| 852 | + | ||
| 853 | + | ``` pascal | |
| 924 | 854 | uses PackageIntf; | |
| 925 | - | ||
| 926 | - | ||
| 927 | - | ||
| 855 | + | ... | |
| 856 | + | for i:=0 to PackageEditingInterface.GetPackageCount-1 do | |
| 857 | + | writeln(PackageEditingInterface.GetPackages(i).Name); | |
| 928 | 858 | ``` | |
| 929 | 859 | ||
| 930 | 860 | ## Search a package with a name | |
| 931 | - | ||
| 861 | + | ||
| 862 | + | ``` pascal | |
| 932 | 863 | uses PackageIntf; | |
| 864 | + | ... | |
| 865 | + | var | |
| 866 | + | Pkg: TIDEPackage; | |
| 867 | + | begin | |
| 868 | + | Pkg:=PackageEditingInterface.FindPackageWithName('LCL'); | |
| 869 | + | if Pkg<>nil then | |
| 933 | 870 | ... | |
| 934 | - | ||
| 935 | - | ||
| 936 | - | ||
| 937 | - | ||
| 938 | - | ||
| 939 | - | ||
| 940 | - | ||
| 871 | + | end; | |
| 941 | 872 | ``` | |
| 942 | 873 | ||
| 943 | - | ||
| 874 | + | Note: FindPackageWithName does not open the package editor. For that use DoOpenPackageWithName. | |
| 944 | 875 | ||
| 945 | 876 | ## Obtener el nombre de fichero .lpk de un paquete instalado | |
| 946 | - | ||
| 877 | + | ||
| 878 | + | ``` pascal | |
| 947 | 879 | uses PackageIntf; | |
| 948 | - | ||
| 949 | - | ||
| 950 | - | ||
| 951 | - | ||
| 952 | - | ||
| 953 | - | ||
| 954 | - | ||
| 955 | - | ||
| 880 | + | ... | |
| 881 | + | var | |
| 882 | + | Pkg: TIDEPackage; | |
| 883 | + | begin | |
| 884 | + | Pkg:=PackageEditingInterface.FindPackageWithName('LCL'); | |
| 885 | + | if Pkg<>nil then | |
| 886 | + | LPKFilename:=Pkg.Filename; | |
| 887 | + | end; | |
| 956 | 888 | ``` | |
| 957 | 889 | ||
| 958 | 890 | ## Instalar paquetes | |
| 959 | 891 | ||
| 960 | - | ||
| 961 | - | ||
| 892 | + | **Note**: Instalar únicamente paquetes con plugins IDE. Instalar otros paquetes puede hacer el IDE inestable. | |
| 893 | + | ||
| 894 | + | ``` pascal | |
| 962 | 895 | uses PackageIntf, contnrs; | |
| 963 | - | ||
| 964 | - | ||
| 965 | - | ||
| 966 | - | ||
| 967 | - | ||
| 968 | - | ||
| 969 | - | ||
| 970 | - | ||
| 971 | - | ||
| 972 | - | ||
| 973 | - | ||
| 974 | - | ||
| 975 | - | ||
| 976 | - | ||
| 977 | - | ||
| 978 | - | ||
| 979 | - | ||
| 896 | + | ... | |
| 897 | + | PkgList:=TObjectList.create(true); | |
| 898 | + | try | |
| 899 | + | Pkg:=TLazPackageID.Create; | |
| 900 | + | Pkg.Name:='Cody'; | |
| 901 | + | PkgList.Add(Pkg); | |
| 902 | + | // Chequear si el IDE puede encontrar cody.lpk y todas las dependencias. | |
| 903 | + | // El IDE will muestra algunas advertencias/confirmaciones si algo parece extraño. | |
| 904 | + | if not PackageEditingInterface.CheckInstallPackageList(PkgList,[]) then | |
| 905 | + | exit; | |
| 906 | + | // in this example we have checked already, so skip the warnings | |
| 907 | + | // and rebuild the IDE | |
| 908 | + | if PackageEditingInterface.InstallPackages(PkgList,[piiifSkipChecks,piiifRebuildIDE])<>mrOK then | |
| 909 | + | exit; | |
| 910 | + | finally | |
| 911 | + | PkgList.Free; | |
| 912 | + | end; | |
| 980 | 913 | ``` | |
| 981 | 914 | ||
| 982 | 915 | ## Abrir un fichero de paquete (lpk) | |
| 983 | - | ||
| 916 | + | ||
| 917 | + | ``` pascal | |
| 984 | 918 | uses PackageIntf, FileUtil; | |
| 985 | - | ||
| 986 | - | ||
| 987 | - | ||
| 988 | - | ||
| 989 | - | ||
| 990 | - | ||
| 991 | - | ||
| 992 | - | ||
| 993 | - | ||
| 919 | + | ... | |
| 920 | + | var | |
| 921 | + | pkg: TIDEPackage; | |
| 922 | + | begin | |
| 923 | + | if PackageEditingInterface.DoOpenPackageFile(LPKFilename,[pofAddToRecent],false)<>mrOk then | |
| 924 | + | exit; | |
| 925 | + | Pkg:=PackageEditingInterface.FindPackageWithName(ExtractFilenameOnly(LPKFilename)); | |
| 926 | + | ... | |
| 927 | + | end; | |
| 994 | 928 | ``` | |
| 995 | 929 | ||
| 996 | - | ||
| 997 | - | ||
| 998 | - | ||
| 930 | + | > **Warning:** El IDE cierra automáticamentes paquetes no utilizados on idle. Nunca mantener referencias a un TIDEPackage. | |
| 999 | 931 | ||
| 1000 | 932 | ## Find the package(s) of a unit | |
| 1001 | 933 | ||
| 1002 | - | ||
| 1003 | - | ||
| 934 | + | You have the file name of a unit, e.g. '/home/user/unit.pas', and you want to know to which package(s) and project(s) it belongs use this: | |
| 935 | + | ||
| 936 | + | ``` pascal | |
| 1004 | 937 | uses Classes, PackageIntf, ProjectIntf; | |
| 1005 | - | ||
| 1006 | - | ||
| 1007 | - | ||
| 1008 | - | ||
| 1009 | - | ||
| 1010 | - | ||
| 1011 | - | ||
| 1012 | - | ||
| 1013 | - | ||
| 1014 | - | ||
| 1015 | - | ||
| 1016 | - | ||
| 1017 | - | ||
| 1018 | - | ||
| 1019 | - | ||
| 1020 | - | ||
| 1021 | - | ||
| 1022 | - | ||
| 1023 | - | ||
| 1024 | - | ||
| 1025 | - | ||
| 1026 | - | ||
| 1027 | - | ||
| 1028 | - | ||
| 1029 | - | ||
| 1030 | - | ||
| 1031 | - | ||
| 938 | + | ... | |
| 939 | + | var | |
| 940 | + | Owners: TFPList; | |
| 941 | + | i: Integer; | |
| 942 | + | o: TObject; | |
| 943 | + | begin | |
| 944 | + | Owners:=PackageEditingInterface.GetPossibleOwnersOfUnit('/full/path/of/unit.pas',[]); | |
| 945 | + | if Owners=nil then begin | |
| 946 | + | // unit is not directly associated with a project/package | |
| 947 | + | // maybe the unit was for some reason not added, but is reachable | |
| 948 | + | // search in all unit paths of all projects/packages | |
| 949 | + | // Beware: This can lead to false hits | |
| 950 | + | Owners:=PackageEditingInterface.GetPossibleOwnersOfUnit('/full/path/of/unit.pas', | |
| 951 | + | [piosfExcludeOwned,piosfIncludeSourceDirectories]); | |
| 952 | + | end; | |
| 953 | + | if Owners=nil then exit; | |
| 954 | + | try | |
| 955 | + | for i:=0 to Owners.Count-1 do begin | |
| 956 | + | o:=TObject(Owners[i]); | |
| 957 | + | if o is TIDEPackage then begin | |
| 958 | + | writeln('Owner is package ',TIDEPackage(o).Name); | |
| 959 | + | end else if o is TLazProject then begin | |
| 960 | + | writeln('Owner is project ',TLazProject(o).ProjectInfoFile); | |
| 1032 | 961 | end; | |
| 962 | + | end; | |
| 963 | + | finally | |
| 964 | + | Owners.Free; | |
| 965 | + | end; | |
| 1033 | 966 | ``` | |
| 1034 | 967 | ||
| 1035 | 968 | # Ventanas | |
| 1036 | 969 | ||
| 1037 | - | ||
| 970 | + | Hay básicamente cuatro tipos de ventandas del IDE: | |
| 1038 | 971 | ||
| 1039 | - | ||
| 1040 | - | ||
| 1041 | - | ||
| 1042 | - | ||
| 972 | + | - La barra principal del IDE bar que es Application.MainForm. Siempre está presente. | |
| 973 | + | - Ventanas flotantes/acoplables tales como el editor del código fuente, the Object Inspectors and Messages. | |
| 974 | + | - Fomas modales, tales como los diálogos de búsqueda, opciones y preguntas. | |
| 975 | + | - Sugerencias y formas de completado. | |
| 1043 | 976 | ||
| 1044 | 977 | ## Añadiendo una nueva ventana de acoplado en el IDE | |
| 1045 | 978 | ||
| 1046 | - | ||
| 979 | + | Que es una ventana del IDE acoplable: Ventanas tales como el Editor de Código Fuente o el Inspector de Objetos son ventanas flotantes que se pueden acoplar si se instala un paquete de acoplamiento, y su estado, posición y tamaño se almacena y restaura en el siguiente inicio del IDE. En orden a restaurar una ventana el IDE necesita un creador como se definie en la unidad **IDEWindowIntf** del paquete IDEIntf. Cada ventana acoplable debe tener un único nombre. No usar por tanto nombres genéricos como 'FileBrowser' porque haría que entre fácilmente en conflicto con otros paquetes. Y no usar nombres cortos como 'XYZ' porque el creador es responsable de todas las formas que comiencen con dicho nombre. | |
| 1047 | 980 | ||
| 1048 | 981 | ### Como registrar una ventana acoplable del IDE | |
| 1049 | 982 | ||
| 1050 | - | ||
| 1051 | - | ||
| 983 | + | Recuerda utilizar un nombre largo única que sea un identificador pascal válido. Tus ventanas pueden tener cualquier caption que necesites. | |
| 984 | + | ||
| 985 | + | ``` pascal | |
| 1052 | 986 | uses SysUtils, IDEWindowIntf; | |
| 1053 | - | ||
| 1054 | - | ||
| 1055 | - | ||
| 1056 | - | ||
| 1057 | - | ||
| 1058 | - | ||
| 1059 | - | ||
| 1060 | - | ||
| 1061 | - | ||
| 1062 | - | ||
| 1063 | - | ||
| 1064 | - | ||
| 1065 | - | ||
| 1066 | - | ||
| 1067 | - | ||
| 1068 | - | ||
| 1069 | - | ||
| 1070 | - | ||
| 1071 | - | ||
| 1072 | - | ||
| 987 | + | ... | |
| 988 | + | var MyIDEWindow: TMyIDEWindow = nil; | |
| 989 | + | ||
| 990 | + | procedure CreateMyIDEWindow(Sender: TObject; aFormName: string; var AForm: TCustomForm; DoDisableAutoSizing: boolean); | |
| 991 | + | begin | |
| 992 | + | // check the name | |
| 993 | + | if CompareText(aFormName,MyIDEWindowName)<>0 then exit; | |
| 994 | + | // create the form if not already done and disable autosizing | |
| 995 | + | IDEWindowCreators.CreateForm(MyIDEWindow,TMyIDEWindowm,DoDisableAutosizing,Application); | |
| 996 | + | ... init the window ... | |
| 997 | + | AForm:=MyIDEWindow; | |
| 998 | + | end; | |
| 999 | + | ||
| 1000 | + | procedure Register; | |
| 1001 | + | begin | |
| 1002 | + | IDEWindowCreators.Add('MyIDEWindow',@CreateMyIDEWindow,nil,'100','50%','+300','+20%'); | |
| 1003 | + | // the default boundsrect of the form is: | |
| 1004 | + | // Left=100, Top=50% of Screen.Height, Width=300, Height=20% of Screen.Height | |
| 1005 | + | // when the IDE needs an instance of this window it calls the procedure CreateMyIDEWindow. | |
| 1006 | + | end; | |
| 1073 | 1007 | ``` | |
| 1074 | 1008 | ||
| 1075 | 1009 | ### Showing an IDE window | |
| 1076 | 1010 | ||
| 1077 | - | ||
| 1078 | - | ||
| 1011 | + | **Do not use Show**. Use: | |
| 1012 | + | ||
| 1013 | + | ``` pascal | |
| 1079 | 1014 | IDEWindowCreators.ShowForm(MyIDEWindow,false); | |
| 1080 | 1015 | ``` | |
| 1081 | 1016 | ||
| 1082 | - | ||
| 1017 | + | This will work with docking. The docking system might wrap the form into a docking site. The BringToFront parameter tells the docking system to make the form and all its parent sites visible and bring the top level site to the front. | |
| 1083 | 1018 | ||
| 1084 | 1019 | ### Notes about IDEWindowCreators and SimpleLayoutStorage | |
| 1085 | 1020 | ||
| 1086 | - | ||
| 1021 | + | The IDEWindowCreators.SimpleLayoutStorage simply stores the BoundsRect and WindowState of all forms that were once opened. It is used as fallback if no dockmaster is installed. It stores the state even if a DockMaster is installed, so that when the dockmaster is uninstalled the forms bounds are restored. | |
| 1087 | 1022 | ||
| 1088 | - | ||
| 1023 | + | The IDEWindowCreators is used by all dockable forms to register themselves and to show forms. When showing a form the Creator checks if a IDEDockMaster is installed and will delegate the showing to it. If no IDEDockMaster is installed it simply shows the form. The IDEDockMaster can use the information in the IDEWindowCreators to create forms by names and get an idea where to place a form when showing it for the first time. For more details see the packages AnchorDockingDsgn and EasyDockMgDsgn. | |
| 1089 | 1024 | ||
| 1090 | 1025 | # CodeTools | |
| 1091 | 1026 | ||
| 1092 | - | ||
| 1027 | + | The CodeTools is a package providing a vast amount of functions to parse, search and change pascal sources and some basic functions for other languages as well. You can use them without the IDE too. It is recommended that you read first about the CodeTools in general before using them in the IDE: [[Codetools]]. | |
| 1093 | 1028 | ||
| 1094 | - | ||
| 1095 | - | ||
| 1029 | + | Before calling any of the CodeTools functions in the IDE you should commit the current changes of the source editor to the CodeTools buffers: | |
| 1030 | + | ||
| 1031 | + | ``` pascal | |
| 1096 | 1032 | uses LazIDEIntf; | |
| 1097 | - | ||
| 1098 | - | ||
| 1099 | - | ||
| 1033 | + | ... | |
| 1034 | + | // save changes in source editor to codetools | |
| 1035 | + | LazarusIDE.SaveSourceEditorChangesToCodeCache(-1); // -1: commit all source editors | |
| 1100 | 1036 | ``` | |
| 1101 | 1037 | ||
| 1102 | 1038 | ## Adding a resource directive to a file | |
| 1103 | 1039 | ||
| 1104 | - | ||
| 1105 | - | ||
| 1040 | + | This adds a {\$R example.res} to a pascal unit: | |
| 1041 | + | ||
| 1042 | + | ``` pascal | |
| 1106 | 1043 | procedure AddResourceDirectiveToPascalSource(const Filename: string); | |
| 1107 | - | ||
| 1108 | - | ||
| 1109 | - | ||
| 1110 | - | ||
| 1111 | - | ||
| 1112 | - | ||
| 1113 | - | ||
| 1114 | - | ||
| 1115 | - | ||
| 1116 | - | ||
| 1117 | - | ||
| 1118 | - | ||
| 1119 | - | ||
| 1120 | - | ||
| 1121 | - | ||
| 1122 | - | ||
| 1123 | - | ||
| 1044 | + | var | |
| 1045 | + | ExpandedFilename: String; | |
| 1046 | + | CodeBuf: TCodeBuffer; | |
| 1047 | + | begin | |
| 1048 | + | // make sure the filename is trimmed and contains a full path | |
| 1049 | + | ExpandedFilename:=CleanAndExpandFilename(Filename); | |
| 1050 | + | ||
| 1051 | + | // save changes in source editor to codetools | |
| 1052 | + | LazarusIDE.SaveSourceEditorChangesToCodeCache(-1); | |
| 1053 | + | ||
| 1054 | + | // load the file | |
| 1055 | + | CodeBuf:=CodeToolBoss.LoadFile(ExpandedFilename,true,false); | |
| 1056 | + | ||
| 1057 | + | // add the resource directive | |
| 1058 | + | if not CodeToolBoss.AddResourceDirective(CodeBuf,'example.res') then | |
| 1059 | + | LazarusIDE.DoJumpToCodeToolBossError; | |
| 1060 | + | end; | |
| 1124 | 1061 | ``` | |
| 1125 | 1062 | ||
| 1126 | - | ||
| 1063 | + | The codetools provides also functions like FindResourceDirective and RemoveDirective. | |
| 1127 | 1064 | ||
| 1128 | 1065 | ## Getting the search paths for units and include files | |
| 1129 | 1066 | ||
| 1130 | - | ||
| 1131 | - | ||
| 1067 | + | There are many different search paths in the IDE from projects, packages, the fpc and lazarus directory and there are many types of paths: before or after resolving macros, with or without inherited search paths, as relative or absolute paths. All files in a directory share the same set of search paths. You can get the search paths for each directory fully resolved by asking the codetools: | |
| 1068 | + | ||
| 1069 | + | ``` pascal | |
| 1132 | 1070 | uses CodeToolManager; | |
| 1133 | - | ||
| 1134 | - | ||
| 1135 | - | ||
| 1136 | - | ||
| 1137 | - | ||
| 1138 | - | ||
| 1139 | - | ||
| 1140 | - | ||
| 1141 | - | ||
| 1142 | - | ||
| 1143 | - | ||
| 1144 | - | ||
| 1145 | - | ||
| 1146 | - | ||
| 1147 | - | ||
| 1148 | - | ||
| 1149 | - | ||
| 1071 | + | ... | |
| 1072 | + | ||
| 1073 | + | Dir:=''; // the empty directory is for new files and has the same settings as the project directory | |
| 1074 | + | ||
| 1075 | + | // Getting the search paths for include files: | |
| 1076 | + | Path:=CodeToolBoss.GetIncludePathForDirectory(Dir); | |
| 1077 | + | ||
| 1078 | + | // Getting the search paths for units: | |
| 1079 | + | // This search path is passed to the compiler. | |
| 1080 | + | // It contains the package output directories, but not the package source directories. | |
| 1081 | + | Path:=CodeToolBoss.GetUnitPathForDirectory(Dir); | |
| 1082 | + | ||
| 1083 | + | // There can be additional unit search paths for the IDE only (not passed to the compiler) | |
| 1084 | + | Path:=CodeToolBoss.GetSrcPathForDirectory(Dir); | |
| 1085 | + | ||
| 1086 | + | // The complete search path contains also all package source paths for units: | |
| 1087 | + | Path:=CodeToolBoss.GetCompleteSrcPathForDirectory(Dir); | |
| 1150 | 1088 | ``` | |
| 1151 | 1089 | ||
| 1152 | 1090 | # Source Editor | |
| 1153 | 1091 | ||
| 1154 | 1092 | ## Active source editor | |
| 1155 | - | ||
| 1093 | + | ||
| 1094 | + | ``` pascal | |
| 1156 | 1095 | uses SrcEditorIntf; | |
| 1157 | - | ||
| 1158 | - | ||
| 1159 | - | ||
| 1160 | - | ||
| 1161 | - | ||
| 1162 | - | ||
| 1096 | + | ... | |
| 1097 | + | Editor:=SourceEditorManagerIntf.ActiveEditor; | |
| 1098 | + | if Editor=nil then exit; | |
| 1099 | + | Filename:=Editor.FileName; | |
| 1100 | + | ScreenPos:=Editor.CursorScreenXY; | |
| 1101 | + | TextPos:=Editor.CursorTextXY; | |
| 1163 | 1102 | ``` | |
| 1164 | 1103 | ||
| 1165 | 1104 | # SynEdit | |
| 1166 | 1105 | ||
| 1167 | 1106 | ## Getting the settings for a TSynEdit | |
| 1168 | 1107 | ||
| 1169 | - | ||
| 1170 | - | ||
| 1108 | + | When you have a dialog using a TSynEdit and you want to use the same font and settings like the source editor use: | |
| 1109 | + | ||
| 1110 | + | ``` pascal | |
| 1171 | 1111 | uses SrcEditorIntf; | |
| 1172 | - | ||
| 1173 | - | ||
| 1112 | + | ... | |
| 1113 | + | SourceEditorManagerIntf.GetEditorControlSettings(ASynEdit); | |
| 1174 | 1114 | ``` | |
| 1175 | 1115 | ||
| 1176 | 1116 | ## Getting the settings for a SynEdit highlighter | |
| 1177 | 1117 | ||
| 1178 | - | ||
| 1179 | - | ||
| 1118 | + | When you have a dialog using a TSynEdit with a highlighter and you want to use the same colors like the source editor highlighter for this language use: | |
| 1119 | + | ||
| 1120 | + | ``` pascal | |
| 1180 | 1121 | uses SrcEditorIntf; | |
| 1181 | - | ||
| 1182 | - | ||
| 1122 | + | ... | |
| 1123 | + | SourceEditorManagerIntf.GetHighlighterSettings(ASynHighlighter); | |
| 1183 | 1124 | ``` | |
| 1184 | 1125 | ||
| 1185 | - | ||
| 1126 | + | See for an example: TSQLStringsPropertyEditorDlg.Create in the unit [SQLStringsPropertyEditorDlg](http://svn.freepascal.org/svn/lazarus/trunk/components/sqldb/sqlstringspropertyeditordlg.pas). | |
| 1186 | 1127 | ||
| 1187 | 1128 | # Help | |
| 1188 | 1129 | ||
| 1189 | 1130 | ## Adding help for sources | |
| 1190 | 1131 | ||
| 1191 | - | ||
| 1192 | - | ||
| 1132 | + | First create a THelpDatabase: | |
| 1133 | + | ||
| 1134 | + | ``` pascal | |
| 1193 | 1135 | HelpDB := TFPDocHTMLHelpDatabase( | |
| 1194 | - | ||
| 1195 | - | ||
| 1196 | - | ||
| 1197 | - | ||
| 1198 | - | ||
| 1199 | - | ||
| 1200 | - | ||
| 1201 | - | ||
| 1202 | - | ||
| 1203 | - | ||
| 1204 | - | ||
| 1136 | + | HelpDatabases.CreateHelpDatabase('ANameOfYourChoiceForTheDatabase', | |
| 1137 | + | TFPDocHTMLHelpDatabase,true)); | |
| 1138 | + | HelpDB.DefaultBaseURL := 'http://your.help.org/'; | |
| 1139 | + | ||
| 1140 | + | FPDocNode := THelpNode.CreateURL(HelpDB, | |
| 1141 | + | 'Package1 - A new package', | |
| 1142 | + | 'file://index.html'); | |
| 1143 | + | HelpDB.TOCNode := THelpNode.Create(HelpDB,FPDocNode);// once as TOC | |
| 1144 | + | DirectoryItem := THelpDBISourceDirectory.Create(FPDocNode,'$(PkgDir)/lcl', | |
| 1145 | + | '*.pp;*.pas',false);// and once as normal page | |
| 1146 | + | HelpDB.RegisterItem(DirectoryItem); | |
| 1205 | 1147 | ``` | |
| 1206 | 1148 | ||
| 1207 | 1149 | ## Adding lines to the messages window | |
| 1208 | - | ||
| 1150 | + | ||
| 1151 | + | ``` pascal | |
| 1209 | 1152 | unit IDEMsgIntf; | |
| 1210 | - | ||
| 1211 | - | ||
| 1212 | - | ||
| 1213 | - | ||
| 1214 | - | ||
| 1215 | - | ||
| 1216 | - | ||
| 1217 | - | ||
| 1153 | + | ... | |
| 1154 | + | var Dir: String; | |
| 1155 | + | begin | |
| 1156 | + | Dir:=GetCurrentDir; | |
| 1157 | + | IDEMessagesWindow.BeginBlock; | |
| 1158 | + | IDEMessagesWindow.AddMsg('unit1.pas(30,4) Error: Identifier not found "a"',Dir,0); | |
| 1159 | + | IDEMessagesWindow.EndBlock; | |
| 1160 | + | end; | |
| 1218 | 1161 | ``` | |
| 1219 | 1162 | ||
| 1220 | 1163 | # Miscellaneous | |
| 1221 | 1164 | ||
| 1222 | 1165 | ## Adding a macro | |
| 1223 | 1166 | ||
| 1224 | - | ||
| 1225 | - | ||
| 1167 | + | You can add your own IDE macros: | |
| 1168 | + | ||
| 1169 | + | ``` pascal | |
| 1226 | 1170 | uses MacroIntf, MacroDefIntf; | |
| 1227 | - | ||
| 1228 | - | ||
| 1229 | - | ||
| 1230 | - | ||
| 1231 | - | ||
| 1232 | - | ||
| 1233 | - | ||
| 1234 | - | ||
| 1235 | - | ||
| 1236 | - | ||
| 1237 | - | ||
| 1238 | - | ||
| 1239 | - | ||
| 1240 | - | ||
| 1241 | - | ||
| 1242 | - | ||
| 1243 | - | ||
| 1244 | - | ||
| 1245 | - | ||
| 1246 | - | ||
| 1247 | - | ||
| 1248 | - | ||
| 1171 | + | ||
| 1172 | + | procedure Register; | |
| 1173 | + | begin | |
| 1174 | + | // registering a Macro with a fixed value: | |
| 1175 | + | IDEMacros.Add(TTransferMacro.Create('MyMacro1','Value','Description',nil,[])); | |
| 1176 | + | end; | |
| 1177 | + | ||
| 1178 | + | // registering a Macro with a dynamic value requires a method of an object | |
| 1179 | + | procedure TForm1.Init; | |
| 1180 | + | begin | |
| 1181 | + | IDEMacros.Add(TTransferMacro.Create('MyMacro','Value','Description',@OnResolveMyMacro,[])); | |
| 1182 | + | end; | |
| 1183 | + | ||
| 1184 | + | function TForm1.OnResolveMyMacro(const s: string; const Data: PtrInt; | |
| 1185 | + | var Abort: boolean): string; | |
| 1186 | + | // s is the parameter. For example $MyMacro(parameter) | |
| 1187 | + | // Data is the querying instance. Can be nil. | |
| 1188 | + | // If there is an error set Abort to true. | |
| 1189 | + | // The result string can contain macros. For example Result:='$(FPCVer)/$(TargetOS)'; | |
| 1190 | + | begin | |
| 1191 | + | Result:='MyValue'; | |
| 1192 | + | end; | |
| 1249 | 1193 | ``` | |
| 1250 | 1194 | ||
| 1251 | 1195 | ## Depurando el IDE | |
| 1252 | 1196 | ||
| 1253 | - | ||
| 1254 | - | ||
| 1255 | - | ||
| 1197 | + | - Compila el IDE como habitualmente e.g. via Tools/Build de Lazarus. Asegúrate de establecer los flags de depuración tales como -g o -gw2. Lo mejor es utilizar el profile "Debug IDE" que contiene algunos flags útiles para depuración. | |
| 1198 | + | - Abre el proyecto ide\lazarus.lpi. No se puede compilar directamente este proyecto. | |
| 1199 | + | - Establece los puntos de ruptura (breakpoints) acorde a tus necesidades etc y ejecuta el proyecto. | |
| 1256 | 1200 | ||
| 1257 | 1201 | ## See also | |
| 1258 | 1202 | ||
| 1259 | - | ||
| 1260 | - | ||
| 1261 | - | ||
| 1203 | + | - [[Creating IDE Help]] | |
| 1204 | + | - [[Help protocol]] | |
| 1205 | + | - [[How To Write Lazarus Component]] | |
| 1262 | 1206 | ||
| 1263 | 1207 | --- | |
| 1264 | - | ||
| 1208 | + | *From the Free Pascal wiki, page "Extending the IDE/es", as it stood on 2020-02-14 after a change by Trev, out of the wiki's dump of 2024-05-26. Copyright stays with the author who wrote it, according to the old wiki's [[Licensing]] page. If you have concerns about this material, [message the admin](/wiki-contact).* |