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
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
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
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
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
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
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
573
574
575
576
577
578
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
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
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
865
866
867
868
869
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
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
1001
1002
1003
1004
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
1032
1033
1034
1035
1036
1037
1038
1039
1040
1041
1042
1043
1044
1045
1046
1047
1048
1049
1050
1051
1052
1053
1054
1055
1056
1057
1058
1059
1060
1061
1062
1063
1064
1065
1066
1067
1068
1069
1070
1071
1072
1073
1074
1075
1076
1077
1078
1079
1080
1081
1082
1083
1084
1085
1086
1087
1088
1089
1090
1091
1092
1093
1094
1095
1096
1097
1098
1099
1100
1101
1102
1103
1104
1105
1106
1107
1108
1109
1110
1111
1112
1113
1114
1115
1116
1117
1118
1119
1120
1121
1122
1123
1124
1125
1126
1127
1128
1129
1130
1131
1132
1133
1134
1135
1136
1137
1138
1139
1140
1141
1142
1143
1144
1145
1146
1147
1148
1149
1150
1151
1152
1153
1154
1155
1156
1157
1158
1159
1160
1161
1162
1163
1164
1165
1166
1167
1168
1169
1170
1171
1172
1173
1174
1175
1176
1177
1178
1179
1180
1181
1182
1183
1184
1185
1186
1187
1188
1189
1190
1191
1192
1193
1194
1195
1196
1197
1198
1199
1200
1201
1202
1203
1204
1205
1206
1207
1208
1209
1210
1211
1212
1213
1214
1215
1216
1217
1218
1219
1220
1221
1222
1223
1224
1225
1226
1227
1228
1229
1230
1231
1232
1233
1234
1235
1236
1237
1238
1239
1240
1241
1242
1243
1244
1245
1246
1247
1248
1249
1250
1251
1252
1253
1254
1255
1256
1257
1258
1259
1260
1261
1262
1263
1264
1265
1266
1267
1268
1269
1270
1271
1272
1273
1274
1275
1276
1277
1278
1279
1280
1281
1282
1283
1284
1285
1286
1287
1288
1289
1290
1291
1292
1293
1294
1295
1296
1297
1298
1299
1300
1301
1302
1303
1304
1305
1306
1307
1308
1309
1310
1311
1312
1313
1314
1315
1316
1317
1318
1319
1320
1321
1322
1323
1324
1325
1326
1327
1328
1329
1330
1331
1332
1333
1334
1335
1336
1337
1338
1339
1340
1341
1342
1343
1344
1345
1346
1347
1348
1349
1350
1351
1352
1353
1354
1355
1356
1357
1358
1359
1360
1361
1362
1363
1364
1365
1366
1367
1368
1369
1370
1371
1372
1373
1374
1375
1376
1377
1378
1379
1380
1381
1382
1383
1384
1385
1386
1387
1388
1389
1390
1391
1392
1393
1394
1395
1396
1397
1398
1399
1400
1401
1402
1403
1404
1405
1406
1407
1408
1409
1410
1411
1412
1413
1414
1415
1416
1417
1418
1419
1420
1421
1422
1423
1424
1425
1426
1427
1428
1429
1430
1431
1432
1433
1434
1435
1436
1437
1438
1439
1440
1441
1442
1443
1444
1445
1446
1447
1448
1449
1450
1451
1452
1453
1454
1455
1456
1457
1458
1459
1460
1461
1462
1463
1464
1465
1466
1467
1468
1469
1470
1471
1472
1473
1474
1475
1476
1477
1478
1479
1480
1481
1482
1483
1484
1485
1486
1487
1488
1489
1490
1491
1492
1493
1494
1495
1496
1497
1498
1499
1500
1501
1502
1503
1504
1505
1506
1507
1508
1509
1510
1511
1512
1513
1514
1515
1516
1517
1518
1519
1520
1521
1522
1523
1524
1525
1526
1527
1528
1529
1530
1531
1532
1533
1534
1535
1536
1537
1538
1539
1540
1541
1542
1543
1544
1545
1546
1547
1548
1549
1550
1551
|
<sect1 id="developers-plugins">
<title
>Udvikling af plugin for &chalk;</title>
<sect2 id="developers-plugins-introduction">
<title
>Indledning</title>
<para
>&chalk; kan udvides i det uendelige med plugin. Værktøjer, filtre, store dele af brugergrænsefladen og alle farverum er plugin. I virkeligheden genkender &chalk; følgende seks typer plugin: </para>
<itemizedlist>
<listitem
><para
>farverum — disse definerer kanalerne som udgør et enkelt billedpunkt</para
></listitem>
<listitem
><para
>værktøjer — alt som udføres med en mus eller styreplade</para
></listitem>
<listitem
><para
>maleoperationer — maleeffekter for værktøjer som kan indlæses</para
></listitem>
<listitem
><para
>billedfiltre — ændr alle billedpunkter, eller kun markerede billedpunkter i et lag</para
></listitem>
<listitem
><para
>visningsplugin — udvider Chalks brugergrænseflade med nye dialoger, paletter og handlinger</para
></listitem>
<listitem
><para
>import- og eksportfiltre — læs og skriv alle slags billedformater</para
></listitem>
</itemizedlist>
<para
>Selve &chalk; består af tre biblioteker i lag og en mappe med visse fælles støtteklasser: chalkcolor, chalkimage og chalkui. Inde i &chalk; kan objekter identificeres af en <classname
>KisID</classname
>, som er en kombinationen af en entydig uoversat streng (som for eksempel bruges når noget skal gemmes) og en øversat streng beregnet til den grafiske brugergrænseflade. </para
><para
>Et ord om kompatibilitet: &chalk; er stadigvæk under udvikling. Fra &chalk; 1.5 til 1.6 forventes ikke mange ændringer af programmeringsgrænsefladen, men der kan være nogle. Fra &chalk; 1.6 til 2.0 skifter vi fra &Qt; 3 til &Qt; 4, fra &kde; 3 til &kde; 4 og fra <command
>automake</command
> til <command
>cmake</command
>: mange ændringer kan forventes. Hvis du udvikler et plugin for &chalk; og vælger at gøre det i &chalk;s subversion-arkiv, er der udmærkede muligheder for at vi hjælper dig med overførslen. Ændringerne kan også gøre at visse dele af dette dokument bliver forældede. Tjek altid den seneste dokumentation af programmeringsgrænsefladen eller deklarationsfilerne som er installerede på dit system. </para>
<sect3 id="developers-plugins-introduction-chalkcolor">
<title
>ChalkColor</title>
<para
>Det første bibliotek er chalkcolor. Dette bibliotek indlæser farverumsplugin. </para
><para
>Et farverumsplugin skal implementere den abstrakte klasse <classname
>KisColorSpace</classname
>, eller hvis de grundlæggende funktioner i det nye farverum implementeres af <command
>lcms</command
> (<ulink url="http://www.littlecms.com/"
></ulink
>), udvide <classname
>KisAbstractColorSpace</classname
>. Biblioteket chalkcolor kan bruges fra andre program, og afhænger ikke af &koffice;. </para>
</sect3>
<sect3 id="developers-plugins-introduction-chalkimage">
<title
>ChalkImage</title>
<para
>Biblioteket libchalkimage indlæser filter- og maleoperationsplugin, og er ansvarligt for at arbejde med billeddata: ændre billedpunkter, sammensætte og male. Pensler, paletter, toninger og mønstre indlæses også af libchalkimage. Det er et udtalt mål at gøre libchalkimage uafhængig af &koffice;, men for øjeblikket deler vi koden til at indlæse toninger med &koffice;. </para
><para
>Det er for øjeblikket ikke nemt at tilføje nye typer af ressourcer såsom pensler, paletter, toninger eller mønstre i &chalk;. (At tilføje nye pensler, paletter, toninger og mønstre er naturligvis enkelt.) &chalk; følger anvisningerne fra projektet Create (<ulink url="http://create.freedesktop.org/"
></ulink
>) for disse. At tilføje understøttelse for Photoshops penselfilformat kræver kodning i libchalkimage. At tilføje flere penseldatafiler fra Gimp kræver ikke dette. </para
><para
><classname
>ChalkImage</classname
> indlæser følgende plugintyper: </para>
<itemizedlist>
<listitem
><para
>Filter i &chalk; skal udvide og implementere den abstrakte klasse <classname
>KisFilter</classname
>, <classname
>KisFilterConfiguration</classname
> og muligvis <classname
>KisFilterConfigurationWidget</classname
>. Et eksempel på et filter er Uskarp maske.</para
></listitem>
<listitem
><para
>Maleoperationer er det sæt af operationer som maleværktøjer såsom frihånd eller cirkel har adgang til. Eksempel på maleoperationer er pen, retuschsprøjte eller viskelæder. Maleoperationer skal udvide basisklassen <classname
>KisPaintop</classname
>. Eksempel på nye maleoperationer kunne være en kridtbørste, en pensel til oliemaling eller en kompleks programmerbar pensel.</para
></listitem>
</itemizedlist>
</sect3>
<sect3 id="developers-plugins-introduction-chalkui">
<title
>ChalkUI</title>
<para
>Biblioteket libchalkui indlæser værktøjet og visningsplugin. Dette bibliotek er et &koffice;-partprogram, men indeholder også et antal grafiske kontroller som er nyttige i grafikprogrammer. Måske skal dette bibliotek deles i chalkpart og chalkui for udgave 2.0. For øjeblikket gives forfattere af scripter ikke adgang til dette bibliotek og forfattere af plugin tillades kun at bruge dette bibliotek når værktøerj og visningsplugin skrives. <classname
>ChalkUI</classname
> indlæser følgende plugintyper: </para>
<itemizedlist>
<listitem
><para
>Værktøjer afledes fra <classname
>KisTool</classname
> eller en af de specialiserede værktøjsbasisklasser såsom <classname
>KisToolPaint</classname
>, <classname
>KisToolNonPaint</classname
> eller <classname
>KisToolFreehand</classname
>. Et nyt værktøj kunne være et værktøj til markering af forgrunden. Maleværktøjer (og det omfatter værktøjer som maler på markeringen) kan bruge en hvilken som helst maleoperation til at bestemme hvordan billedpunkter ændres.</para
></listitem>
<listitem
><para
>Visningsplugin er sædvanlige KParts, som bruger <command
>kxmlgui</command
> til at indlejre sig i &chalk;s brugergrænseflade. Menupunkter, dialoger, værktøjslinjer — alle slags udvidelser af brugergrænsefladen kan være visningsplugin. I virkeligheden er vigtige funktioner, såsom &chalk;s understøttelse for scripter, skrevet som visningsplugin.</para
></listitem>
</itemizedlist>
</sect3>
<sect3 id="developers-plugins-introduction-importexport">
<title
>Import- og eksportfiltre</title>
<para
>Import- og eksportfiltre er &koffice;-filter, delklasser af <classname
>KoFilter</classname
>. Filtre læser og skriver billeddata på et af de utroligt mange billedformater som eksisterer. Et eksempel på et nyt import- og eksportfiler for &chalk; kunne være et PDF-filter. Filtre indlæses af &koffice;-bibliotekerne. </para>
</sect3>
</sect2>
<sect2 id="developers-plugins-creating">
<title
>Opret plugin</title>
<para
>Plugin skrives i C++ og kan bruge hele programmeringsgrænsefladen i &kde; og &Qt; samt &chalk;s udviklingsgrænseflade. Kun visningsplugin skal bruge &koffice;' programmeringsgrænseflade. Du skal ikke bekymre dig, &chalk;s programmeringsgrænseflade er meget ren og relativt udførligt dokumenteret (af frit programmel at være) og at kode dit første filter er meget nemt. </para
><para
>Hvis du ikke vil bruge C++ kan du skrive scripter i Python eller Ruby: det er dog en helt anden sag, og du kan for øjeblikket ikke skrive værktøjer, farverum, maleoperationer eller import- og eksportfilter som scripter. </para
><para
>Plugin i &chalk; bruger &kde;'s mekanisme for partprogrammer til indlæsning, så dokumentationen om partprogrammer på <ulink url="http://developer.kde.org"
></ulink
> er også relevant her. </para
><para
>Relevante deklarationsfiler skal enten være installeret med selve &chalk; af din distribution, eller også er deklarationsfilerne måske enten lagt i pakken &koffice;-dev eller i &chalk;-dev. Du finder dokumentationen af &chalk;s eksterne programmeringsgrænseflade på <ulink url="http://koffice.org/developer/apidocs/chalk/html/"
></ulink
>. </para>
<sect3 id="developers-plugins-creating-automake">
<title
>Automake (og CMake)</title>
<para
>&kde; 3.x og derfor også &koffice; 1.5 og 1.6 bruger <command
>automake</command
>. &kde; 4.0 og &koffice; 2.0 bruger <command
>cmake</command
>. Denne gennemgang beskriver måden at oprette plugin som bruger <command
>automake</command
>. </para
><para
>Plugin er &kde;-moduler, og skal markeres som sådanne i <filename
>Makefile.am</filename
>. Filtre, værktøjer, maleoperationer, farverum samt import- og eksportfiltre har brug for <literal role="extension"
>.desktop</literal
>-filer. Visningsplugin har desuden brug for en <application
>KXMLGui</application
> <filename
>pluginname.rc</filename
>-fil. Den nemmeste måde at komme i gang er at tjekke projektet chalk-plugins ud fra &koffice; Subversion-arkiv og bruge det som basis for dit eget projekt. Vi har til hensigt at oprette en pakke med en &chalk; pluginskabeloner for Kdevelop, men har ikke fået tid til at gøre det endnu. </para>
<sect4 id="d-p-c-a-makefile">
<title
><filename
>Makefile.am</filename
></title>
<para
>Lad os tage et kig på skabelonen for et plugin-modul. Først filen <filename
>Makefile.am</filename
>. Det er den &kde; bruger til at oprette byggefilen som bygger dit plugin: <programlisting>
kde_services_DATA = chalkBIBLIOTEKSNAVN.desktop
INCLUDES = $(all_includes)
chalkBIBLIOTEKSNAVN_la_SOURCES = sourcefile1.cc sourcefile2.cc
kde_module_LTLIBRARIES = chalkBIBLIOTEKSNAVN.la
noinst_HEADERS = header1.h header2.h
chalkBIBLIOTEKSNAVN_la_LDFLAGS = $(all_libraries) -module $(KDE_PLUGIN)
chalkLIBRARY_la_LIBADD = -lchalkcommon
chalkextensioncolorsfilters_la_METASOURCES = AUTO
</programlisting
> Dette er byggefilen for et filter-plugin. Erstat <replaceable
>BIBLIOTEKSNAVN</replaceable
> med navnet på dit arbejde, så er du klar. </para
><para
>Hvis dit plugin er et visningsplugin, installerer du formodentlig også en <literal role="extension"
>.rc</literal
>-fil med indgange for menulinjer og værktøjslinjer. På lignende måde skal du måske også installere markører og ikoner. Alt dette gøres via de magiske besværgelser i &kde;'s sædvanlige <filename
>Makefile.am</filename
>. <programlisting
>chalkrcdir = $(kde_datadir)/chalk/chalkplugins
chalkrc_DATA = BIBLIOTEKSNAVN.rc
EXTRA_DIST = $(chalkrc_DATA)
chalkpics_DATA = \
bla.png \
bla_cursor.png
chalkpicsdir = $(kde_datadir)/chalk/pics
</programlisting>
</para>
</sect4>
<sect4 id="d-p-c-a-desktop">
<title
>Desktopfiler</title>
<para
>Filen <literal role="extension"
>.desktop</literal
> fortæller pluginnets type: <programlisting
>[Desktop Entry]
Encoding=UTF-8
Icon=
Name=User-visible Name
ServiceTypes=Chalk/Filter
Type=Service
X-KDE-Library=chalkBIBLIOTEKSNAVN
X-KDE-Version=2
</programlisting>
</para
><para
>Mulige tjenestetyper er: </para>
<itemizedlist>
<listitem
><para
>Chalk/Filter</para
></listitem>
<listitem
><para
>Chalk/Paintop</para
></listitem>
<listitem
><para
>Chalk/ViewPlugin</para
></listitem>
<listitem
><para
>Chalk/Tool</para
></listitem>
<listitem
><para
>Chalk/ColorSpace</para
></listitem>
</itemizedlist>
<para
>Import- og eksportfiltre for filer bruger det generelle filterskelet i &koffice; og må beskrives separat. </para>
</sect4>
<sect4 id="d-p-c-a-boilerplate">
<title
>Standardkode</title>
<para
>Du behøver også en del standardkode som kaldes af &kde;'s skelet for partprogrammer for at instantiere pluginnet — en deklarationsfil og en implementeringsfil. </para
><para
>En deklarationsfil: <programlisting
>#ifndef TOOL_STAR_H_
#define TOOL_STAR_H_
#include <tdeparts/plugin.h>
/**
* En modul som sørger for et stjerneværktøj.
*/
class ToolStar : public KParts::Plugin
{
Q_OBJECT
public:
ToolStar(QObject *parent, const char *name, const QStringList &);
virtual ~ToolStar();
};
#endif // TOOL_STAR_H_
</programlisting>
</para>
<para
>Og en implementeringsfil: <programlisting
>#include <kinstance.h>
#include <kgenericfactory.h>
#include <kis_tool_registry.h>
#include "tool_star.h"
#include "kis_tool_star.h"
typedef KGenericFactory<ToolStar> ToolStarFactory;
K_EXPORT_COMPONENT_FACTORY( chalktoolstar, ToolStarFactory( "chalk" ) )
ToolStar::ToolStar(QObject *parent, const char *name, const QStringList &)
: KParts::Plugin(parent, name)
{
setInstance(ToolStarFactory::instance());
if ( parent->inherits("KisToolRegistry") )
{
KisToolRegistry * r = dynamic_cast<KisToolRegistry*>( parent );
r -> add(new KisToolStarFactory());
}
}
ToolStar::~ToolStar()
{
}
#include "tool_star.moc"
</programlisting>
</para>
</sect4>
<sect4 id="d-p-c-a-registries">
<title
>Registre</title>
<para
>Værktøjer indlæses af værktøjsregistret og registrerer sig selv med værktøjsregistret. Plugin såsom værktøjer, filtre og maleoperationer indlæses kun en gang. Visningsplugin indlæses for hver visning som skabes. Bemærk at vi registrerer fabriker generelt sagt. For værktøjer skabes eksempelvis en ny instans af et værktøj for hver peger (mus, pen, viskelæder), og en ny maleoperation skabes så snart et værktøj får begivenheden museklik. </para>
<para
>Filtre kalder filterregistret: <programlisting
>if (parent->inherits("KisFilterRegistry")) {
KisFilterRegistry * manager = dynamic_cast<KisFilterRegistry *>(parent);
manager->add(new KisFilterInvert());
}
</programlisting>
</para
><para
>Maleoperationer maleoperationsregistret: <programlisting
>if ( parent->inherits("KisPaintOpRegistry") ) {
KisPaintOpRegistry * r = dynamic_cast<KisPaintOpRegistry*>(parent);
r -> add ( new KisSmearyOpFactory );
}
</programlisting>
</para
><para
>Farverum farverumsregistret (med visse komplikationer): <programlisting
>if ( parent->inherits("KisColorSpaceFactoryRegistry") ) {
KisColorSpaceFactoryRegistry * f = dynamic_cast<isColorSpaceFactoryRegistry*>(parent);
KisProfile *defProfile = new KisProfile(cmsCreate_sRGBProfile());
f->addProfile(defProfile);
KisColorSpaceFactory * csFactory = new KisRgbColorSpaceFactory();
f->add(csFactory);
KisColorSpace * colorSpaceRGBA = new KisRgbColorSpace(f, 0);
KisHistogramProducerFactoryRegistry::instance() -> add(
new KisBasicHistogramProducerFactory<KisBasicU8HistogramProducer>
(KisID("RGB8HISTO", i18n("RGB8 Histogram")), colorSpaceRGBA) );
}
</programlisting>
</para
><para
>Visningsplugin har ikke noget eget register, og de får adgang til et objekt af klassen <classname
>KisView</classname
>: <programlisting
>if ( parent->inherits("KisView") )
{
setInstance(ShearImageFactory::instance());
setXMLFile(locate("data","chalkplugins/shearimage.rc"), true);
(void) new KAction(i18n("&Shear Image..."), 0, 0, this, SLOT(slotShearImage()), actionCollection(), "shearimage");
(void) new KAction(i18n("&Shear Layer..."), 0, 0, this, SLOT(slotShearLayer()), actionCollection(), "shearlayer");
m_view = (KisView*) parent;
}
</programlisting>
</para
><para
>Husk at dette betyder at et visningsplugin skabes for hver visning som brugeren laver: at opdele en visning betyder at alle visningsplugin indlæses igen. </para>
</sect4>
<sect4 id="d-p-c-a-versioning">
<title
>Versionshåndtering af plugin</title>
<para
>&chalk; 1.5 indlæser plugin med <literal
>X-KDE-Version=2</literal
> angivet i <literal role="extension"
>.desktop</literal
>-filen. &chalk; 1.6 kommer formodentlig ikke til at være binært kompatibel med 1.5 plugin og vil behøve versionsnumret 3. &chalk; 2.0 plugin kommer til at behøve versionsnumret 3. Ja, det er ikke helt logisk. </para>
</sect4>
</sect3>
</sect2>
<sect2 id="developers-plugins-colorspaces">
<title
>Farverum</title>
<para
>Farverum implementerer den rent virtuelle klasse <classname
>KisColorSpace</classname
>. Der er to typer af farverum: de som kan bruge <command
>lcms</command
> til overførsler mellem farverum, og de som er for mærkelige for <command
>lcms</command
> at håndtere. Eksempel på de første er cmyk, rgb, yuv. Et eksempel på den senere er watercolor eller wet & sticky. Farverum som bruger <command
>lcms</command
> kan afledes fra <classname
>KisAbstractColorSpace</classname
> eller en af basisklasserne som er specialiserede til et vist antal bit per kanal. </para
><para
>Det er ganske enkelt at implementere et farverum. Det generelle princip er at farverum arbejder med et enkelt felt af byte. Tolkningen af disse bestemmes af farverummet selv. For eksempel består et billedpunkt i 16-bit GrayA af fire byte: to for gråskalaværdien og to for alfaværdien. Du er fri til at bruge en struct til at arbejde med hukommelseslayouten af et billedpunkt i din implementering af farverum, men den repræsentationen eksporteres ikke. Den eneste måde som resten af &chalk; kan vide hvilke kanaler og typer af kanaler din farverums billedpunkter består af er via klassen <classname
>KisChannelInfo</classname
>. </para
><para
>Filtre og maleoperationer udnytter den omfattande mængde metoder som der sørges for af <classname
>KisColorSpace</classname
> til at udføre sit arbejde. I mange tilfælde fungerer standardimplementeringen i <classname
>KisAbstractColorSpace</classname
> men langsommere end en egen implementering i dit eget farverum, eftersom <classname
>KisAbstractColorSpace</classname
> konverterer alle billedpunkter til 16-bit L*a*b og tilbage. </para>
<sect3 id="developers-plugins-colorspaces-kischannelinfo">
<title
><classname
>KisChannelInfo</classname
></title>
<programlisting
>(http://websvn.kde.org/trunk/koffice/chalk/chalkcolor/kis_channelinfo.h)
</programlisting>
<para
>Denne klasse definerer kanalerne som udgør et enkelt billedpunkt i et bestemt farverum. En kanal har følgende vigtige egenskaber: </para>
<itemizedlist>
<listitem
><para
>et navn på en skærm i brugergrænsefladen</para
></listitem>
<listitem
><para
>en position: den byte hvor alle de byte som repræsenterer kanalen begynder i billedpunktet.</para
></listitem>
<listitem
><para
>en type: farve, alfa, substans eller substrat. Farve er sædvanlig farve, alfa er gennemsigtighed, substans er en repræsentation af mængden af pigment eller lignende ting, substrat er en repræsentation af kanvassen. (Bemærk at dette kan ændres meget hurtigt hvis det ønskes.)</para
></listitem>
<listitem
><para
>en værditype: byte, short, integer, float — eller noget andet.</para
></listitem>
<listitem
><para
>størrelse: antal byte som kanalen optager</para
></listitem>
<listitem
><para
>farve: en repræsentation med <classname
>QColor</classname
> af kanalen for visualisering i brugergrænseflade, for eksempel i histogrammer.</para
></listitem>
<listitem
><para
>en forkortelse at bruge i den grafiske brugergrænseflade når der ikke er meget plads</para
></listitem>
</itemizedlist>
</sect3>
<sect3 id="developers-plugins-colorspaces-kiscompositeop">
<title
><classname
>KisCompositeOp</classname
></title>
<para
>Ligesom for den oprindelige Porter-Duff, er der mange måder at kombinere billedpunkter for at få en ny farve. Klassen <classname
>KisCompositeOp</classname
> definerer de fleste af dem: Dette sæt kan ikke enkelt udvides undtagen ved at ændre kode i biblioteket chalkcolor. </para
><para
>Et farverumsplugin kan understøtte en hvilken som helst delmængde af de mulige sammensætningsoperationer, men sættet skal altid omfatte "OVER" (samme som "NORMAL") og "COPY". De øvrige er mere eller mindre valgfrie, selvom flere naturligvis er bedre. </para>
</sect3>
<sect3 id="developers-plugins-colorspaces-kiscolorspace">
<title
><classname
>KisColorSpace</classname
></title>
<para
>Metoderne i den rent virtuelle klasse <classname
>KisColorSpace</classname
> kan deles op i et antal grupper: konvertering, identifikation og behandling. </para
><para
>Alle klasser skal kunne konvertere et billedpunkt fra og til 8-bit RGB (dvs. en <classname
>QColor</classname
>), og helst også til og fra 16-bit L*a*b*. Desuden er der en metode til at konvertere til et hvilket som helst andet farverum fra det nuværende farverum. </para
><para
>Farverum beskrives af vektoren <classname
>KisChannelInfo</classname
>, antal kanaler, antal byte i et enkelt billedpunkt, om det understøtter billeder med stort dynamisk område, med mere. </para
><para
>Behandling er for eksempel at kombinere to billedpunkter til et nyt billedpunkt: bitBlt, at gøre billedpunkter mørkere eller foldning af billedpunkter. </para
><para
>Kig i dokumentationen af programmeringsgrænsefladen for en fuldstændig beskrivelse af alle metoder du skal implementere i en farverum. </para
><para
><classname
>KisAbstractColorSpace</classname
> implementerer mange af de virtuelle metoder i <classname
>KisColorSpace</classname
> ved brug af funktioner fra biblioteket <command
>lcms</command
>. Ovenpå <classname
>KisAbstractColorSpace</classname
> er der basisklasser for farverum med 8- og 16-bit heltal samt 16- og 32-bit float som definerer fælles operationer for at flytte mellem bitdybder. </para>
</sect3>
</sect2>
<sect2 id="developers-plugins-filters">
<title
>Filtre</title>
<para
>Filtre er plugin som undersøger billedpunkter i et lag og derefter udfører ændringer af dem. Selvom &chalk; bruger en effektiv hukommelsesgrænseflade baseret på tiles til at opbevare billedpunkter, skalforfattere af filtre ikke bekymre sig om det. Når et filterplugin skrives for billedbehandlingsgrænsefladen i &Java;, Photoshop eller Gimp skal man sørge for at tile-kanter og <quote
>sammenkoble</quote
> tiles med hinanden. &chalk; skjuler alle sådanne implementeringsdetaljer. </para>
<note
><para
>Bemærk at det teoretisk er nemt at erstatte den nuværende grænseflade for dataopbevaring baseret på tiles med en andet grænseflade, men at denne grænseflade af ydelsesgrunde for øjeblikket ikke er rigtige plugin.</para
></note>
<para
>&chalk; bruger interatorer til at læse og skrive billedpunktværdier. Alternativt kan du indlæse en blok med billedpunkter i en hukommelsesbuffer, arbejde med den og derefter skrive den tilbage som en blok. Dette er dog ikke nødvendigvis effektivere, men kan til og med være langsommere end at bruge iteration: det er måske blot bekvemmere. Se dokumentationen af programmeringsgrænsefladen. </para
><para
>Billeder i &chalk; består af lag, hvoraf der for øjeblikket findes fire slags: malelag, gruppelag, justeringslag (som indeholder et filter som dynamisk bruges for lag under justeringslaget) og part-lag. Filtre arbejder altid med malelag. Malelag indeholder maleenheder af klassen <classname
>KisPaintDevice</classname
>. En maleenhed giver på sin side mulighed for at få adgang til selve billedpunkterne. </para
><para
>En <classname
>PaintDevice</classname
> sendes generelt rundt indlejret i en delt peger. En delt peger holder styr på hvor mange steder som maleenheden for øjeblikket bruges, og fjerner maleenheden når den ikke længere bruges nogen steder. Du genkender versionen af en maleenhed med en delt peger på dens suffix <literal
>SP</literal
>. Husk blot at du aldrig eksplicit behøver at fjerne en <classname
>KisPaintDeviceSP</classname
>. </para
><para
>Lad os undersøge et meget enkelt filter, et som inverterer alle billedpunkter. Koden for filtret findes i mappen <filename class="directory"
>koffice/chalk/plugins/filters/example</filename
>. Hovedmetoden er: <programlisting>
KisFilterInvert::process(KisPaintDeviceSP src, KisPaintDeviceSP dst,
KisFilterConfiguration* /*config*/, const QRect& rect).
</programlisting
> Funktionen modtager to maleenheder, et indstillingsobjekt (som ikke bruges i dette enkle filter) og en <varname
>rect</varname
>. Denne <varname
>rect</varname
> beskriver maleenhedens område som filtret skal håndtere. Området beskrives med heltal, hvilket betyder at der ikke findes nogen nøjagtighed på delbilledpunktsniveau. </para
><para
>Maleenheden <varname
>src</varname
> er til for at læse fra, og maleenheden <varname
>dst</varname
> er til for at skrive til. Disse parametre kan pege på samme egentlige maleenhed, eller være to forskellige maleenheder. (Bemærk: dette vil måske blive ændret til en enkelt maleenhed i fremtiden.) </para
><para
>Lad os nu betragte koden linje for linje: </para>
<programlisting
>void KisFilterInvert::process(KisPaintDeviceSP src, KisPaintDeviceSP dst,
KisFilterConfiguration* /*config*/, const QRect& rect)
{
Q_ASSERT(src != 0);
Q_ASSERT(dst != 0);
KisRectIteratorPixel srcIt = src->createRectIterator(rect.x(), rect.y(), rect.width(), rect.height(), false); <co id="invert1" />
KisRectIteratorPixel dstIt = dst->createRectIterator(rect.x(), rect.y(), rect.width(), rect.height(), true ); <co id="invert2" />
int pixelsProcessed = 0;
setProgressTotalSteps(rect.width() * rect.height());
KisColorSpace * cs = src->colorSpace();
Q_INT32 psize = cs->pixelSize();
while( ! srcIt.isDone() )
{
if(srcIt.isSelected()) <co id="invert3" />
{
memcpy(dstIt.rawData(), srcIt.oldRawData(), psize); <co id="invert4" />
cs->invertColor( dstIt.rawData(), 1); <co id="invert5" />
}
setProgress(++pixelsProcessed);
++srcIt;
++dstIt;
}
setProgressDone(); // Skal kaldes også selvom det ikke understøttes
}
</programlisting>
<calloutlist>
<callout arearefs="invert1">
<para
>Dette laver en iterator til at læse eksisterende billedpunkter. Chalk har tre typer af iteration: vandret, lodret og rektangulær. Iterationen rect går den effektiveste vej gennem billeddata, men garanterer ikke noget om stedet for næste billedpunkt den returnerer. Det betyder at du ikke kan være sikker på at billedpunkter du henter næste gang ligger ved siden af de billedpunkter du netop modtot. De vandrette og lodrette iterationer garanterer virkelig stedet for de billedpunkter de returnerer. </para
></callout>
<callout arearefs="invert2"
><para
>Vi laver destinationsiteratoren med værdien <literal
>true</literal
> for indstillingen <literal
>write</literal
>. Det betyder at hvis destinationens malesenhed er mindre end rektanglen vi skriver, forstørres den automatisk til at omfatte alle billedpunkter i iterationen. Bemærk at vi har et potentiel fejl her: hvis <varname
>dst</varname
> og <varname
>src</varname
> ikke er samme enhed er det meget muligt at billedpunkterne som iteratorerne returnerer ikke svarer til hinanden. For hver position i iteratoren kan <varname
>src</varname
> for eksempel være 165, 200, mens <varname
>dst</varname
> ville kunne være 20, 8 — og derfor vil kopien vi laver nedenfor kunne forvrænge billedet ... </para
></callout>
<callout arearefs="invert3"
><para
>Vil du vide om et billedpunkt er markeret? Det er nemt: brug metoden <methodname
>isSelected</methodname
>. Men at være markeret er ikke en binær egenskab for et billedpunkt. Et billedpunkt kan være halvmarkeret, næsten umarkeret, eller næsten helt markeret. Markeringer er i virkeligheden en maskemaleenhed med området 0 til 255, hvor 0 er helt umarkeret og 255 helt markeret. Iteratoren har to metoder: <methodname
>isSelected()</methodname
> og <methodname
>selectedNess()</methodname
>. Den første returnerer sand hvis et billedpunkt overhovedet er markeret (dvs. maskeværdien er større end 1), den anden returnerer maskeværdien. </para
></callout>
<callout arearefs="invert4"
><para
>Som nævnt ovenfor, er denne <literal
>memcpy</literal
> et stor grim fejl ... <methodname
>rawData()</methodname
> returnerer bytefeltet som er billedpunktets nuværende tilstand og <methodname
>oldRawData()</methodname
> returnerer bytefeltet som det var inden vi oprettete iteratoren. Vi kan imidlertid kopiere et forkert billedpunkt her. I praksis sker dette ikke alt for ofte, hvis ikke <varname
>dst</varname
> allerede findes og ikke er justeret i forhold til <varname
>src</varname
>. </para
></callout>
<callout arearefs="invert5"
><para
>Men dette er rigtigt: I stedet for at regne ud hvilken byte som repræsenterer hvilken kanal, bruger vi en funktion som der sørges for af alle farverum til at invertere det nuværende billedpunkt. Farverum har en mængde billedpunktsoperationer som du kan udnytte. </para
></callout>
</calloutlist>
<para
>Dette er ikke alt som behøves for at oprette et filter. Filtre har to andre vigtige komponenter: et indstillingsobjekt og en grafisk indstillingskontrol. De to fungerer tæt sammen. Den grafiske indstillingskomponenten laver et indstillingsobjekt, men kan også udfyldes fra et indstillingsobjekt som allerede eksisterer. Indstillingsobjekter kan repræsenteres som XML, og kan skabes fra XML. Det er det som gør justeringslag mulige. </para>
<sect3 id="developers-plugins-filters-iterators">
<title
>Iteratorer</title>
<para
>Der er tre typer af iteratorer: </para>
<itemizedlist>
<listitem
><para
>Vandrette linjer</para
></listitem>
<listitem
><para
>Lodrette linjer</para
></listitem>
<listitem
><para
>Rektangulære iteratorer</para
></listitem>
</itemizedlist>
<para
>De vandrette og lodrette linjeiteratorer har en metode til at flytte iteratoren til næste linje eller søjle: <methodname
>nextRow()</methodname
> og <methodname
>nextCol()</methodname
>. At bruge dem er meget hurtigere end at oprette en ny iterator for hver linje eller søjle. </para
><para
>Iteratorer er trådsikre i &chalk;, så det er muligt at opdele arbejdet i flere tråde. Dog kommer fremtidige versioner af &chalk; til at bruge metoden <methodname
>supportsThreading()</methodname
> til at afgøre om filtret kan bruges på stumper af billedet (dvs. alle billedpunkter ændrede uafhængig af hinanden, i stedet for ændrede af en værdi som bestemmes af at undersøge alle billedpunkter i billedet) og automatisk bruge tråde til at køre dit filter. </para>
</sect3>
<sect3 id="developers-plugins-filters-kisfilterconfiguration">
<title
><classname
>KisFilterConfiguration</classname
></title>
<para
><classname
>KisFilterConfiguration</classname
> er en struktur som bruges til at gemme filterindstillinger på disken, for eksempel for justeringslag. Scriptpluginnet bruger egenskabsafbildningen som findes længst tilbage i <classname
>KisFilterConfigaration</classname
> for at gøre det muligt at lave scripter med filtre. Filtre kan sørge for en egen grafisk kontrol som &chalk; viser i filtergalleriet, forhåndsvisningen af filtre og fanebladet med værktøjstilvalg for værktøjet Mal med filtre. </para>
<para
>Et eksempel, som kommer fra filtret for oliemalerieffekt: </para>
<programlisting
>class KisOilPaintFilterConfiguration : public KisFilterConfiguration
{
public:
KisOilPaintFilterConfiguration(Q_UINT32 brushSize, Q_UINT32 smooth)
: KisFilterConfiguration( "oilpaint", 1 )
{
setProperty("brushSize", brushSize);
setProperty("smooth", smooth);
};
public:
inline Q_UINT32 brushSize() { return getInt("brushSize"); };
inline Q_UINT32 smooth() {return getInt("smooth"); };
};
</programlisting>
</sect3>
<sect3 id="developers-plugins-filters-kisfilterconfigurationwidget">
<title
><classname
>KisFilterConfigurationWidget</classname
></title>
<para
>De fleste filtre kan justeres af brugeren. Du kan oprette en indstillingskontrol som Chalk bruger så snart filtret bruges. Et eksempel: </para>
<para>
<screenshot>
<screeninfo
>Dialogen <guilabel
>Oliemaleri</guilabel
></screeninfo>
<mediaobject>
<imageobject>
<imagedata fileref="dialogs-oilpaint.png" format="PNG"/>
</imageobject>
<textobject>
<phrase
>Dialogen <guilabel
>Oliemaleri</guilabel
></phrase>
</textobject>
<caption
><para
>Dialogen <guilabel
>Oliemaleri</guilabel
></para
></caption>
</mediaobject>
</screenshot>
</para>
<para
>Bemærk at kun venstresiden af dialogen er dit ansvar: &chalk; sørger for resten. Der er tre måder at opføre sig på for at oprette en tilvalgskontrol: </para>
<itemizedlist>
<listitem
><para
>Brug &Qt; Designer til at oprette basen for den grafiske kontrol, og opret en delklasse for dit filter</para
></listitem>
<listitem
><para
>Brug en af de simple grafiske kontroller som viser et antal skydere for lister af heltal, decimaltal med dobbelt præcision eller Booleske værdier. Se dokumentationen af programmeringsgrænsefladen for <classname
>KisMultiIntegerFilterWidget</classname
>, <classname
>KisMultiDoubleFilterWidget</classname
> og <classname
>KisMultiBoolFilterWidget</classname
>.</para
></listitem>
<listitem
><para
>Håndkod en grafisk kontrol. Dette anbefales ikke, og hvis du gør det og ønsker at filtret skal være en del af &chalk;s officielle udgave, vil jeg bede dig om at erstatte din håndkodede kontrol med en &Qt; Designer-kontrol.</para
></listitem>
</itemizedlist>
<para
>Oliemalerifiltret bruger multiheltalskontrollen: </para>
<programlisting
>KisFilterConfigWidget * KisOilPaintFilter::createConfigurationWidget(QWidget* parent, KisPaintDeviceSP /*dev*/)
{
vKisIntegerWidgetParam param;
param.push_back( KisIntegerWidgetParam( 1, 5, 1, i18n("Brush size"), "brushSize" ) );
param.push_back( KisIntegerWidgetParam( 10, 255, 30, i18n("Smooth"), "smooth" ) );
return new KisMultiIntegerFilterWidget(parent, id().id().ascii(), id().id().ascii(), param );
}
KisFilterConfiguration* KisOilPaintFilter::configuration(QWidget* nwidget)
{
KisMultiIntegerFilterWidget* widget = (KisMultiIntegerFilterWidget*) nwidget;
if( widget == 0 )
{
return new KisOilPaintFilterConfiguration( 1, 30);
} else {
return new KisOilPaintFilterConfiguration( widget->valueAt( 0 ), widget->valueAt( 1 ) );
}
}
std::list<KisFilterConfiguration*> KisOilPaintFilter::listOfExamplesConfiguration(KisPaintDeviceSP )
{
std::list<KisFilterConfiguration*> list;
list.insert(list.begin(), new KisOilPaintFilterConfiguration( 1, 30));
return list;
}
</programlisting>
<para
>Du ser hvordan det virker: udfyld en vektor med heltalsparametre og opret den grafiske kontrol. Metoden <methodname
>configuration()</methodname
> inspicerer den grafiske kontrol og laver det rette filterindstillingsobjekt, i dette tilfælde naturligvis <classname
>KisOilPaintFilterConfiguration</classname
>. Metoden <methodname
>listOfExamplesConfiguration</methodname
> (som burde omdøbes til rigtigt engelsk ...) returnerer en liste med eksempelindstillingsobjekter for dialogen for filtergalleriet. </para>
</sect3>
<sect3 id="developers-plugins-filters-conclusion">
<title
>Afslutning af filtre</title>
<para
>Der kræves naturligvis mere for at kode interessante filtre, men med denne forklaring, dokumentationen af programmeringsgrænsefladen og adgang til vor kildekode, bør du kunne komme i gang. Tøv ikke med at kontakte udviklerne af &chalk; på IRC eller via e-mail-listen. </para>
</sect3>
</sect2>
<sect2 id="developers-plugins-tools">
<title
>Værktøjer</title>
<para
>Værktøjer vises i &chalk;s værktøjskasse. Det betyder at der er begrænset plads til nye værktøjer: tænk nøje over om en maleoperation ikke er tilstrækkeligt til dit formål. Værktøjer kan bruge musen eller styrepladen og tastaturet på komplekse måder, hvilket maleoperationer ikke kan. Dette er grunden til at Duplikere er et værktøj, mens retuschsprøjte er en maleoperation. </para
><para
>Vær forsigtig med statisk data i værktøjet: en ny instans af værktøjet oprettes for hver inddataenhed: mus, pen, viskelæder, retuschsprøjte med mere. Værktøjer er opdelt i logiske grupper: </para>
<itemizedlist>
<listitem
><para
>formgivende maleværktøjer (cirkel, rektangel)</para
></listitem>
<listitem
><para
>frihåndsmaleværktøjer (pensel)</para
></listitem>
<listitem
><para
>transformeringsværktøj som ændrer et lags geometri</para
></listitem>
<listitem
><para
>udfyldningsværktøjer (såsom udfyldning eller toning)</para
></listitem>
<listitem
><para
>visningsværktøjer (som ikke ændrer billedpunkter, men ændrer måden du ser kanvassen, såsom zooming)</para
></listitem>
<listitem
><para
>markeringsværktøjer (som ændrer markeringsmasken)</para
></listitem>
</itemizedlist>
<para
>Værktøjsgrænsefladen beskrives i dokumentationen af programmeringsgrænsefladen for <classname
>KisTool</classname
>. Der er tre delklasser: <classname
>KisToolPaint</classname
>, <classname
>KisToolNonPaint</classname
> og <classname
>KisToolShape</classname
> (som egentlig er en delklasse af <classname
>KisToolPaint</classname
>) som specialiserer <classname
>KisTool</classname
> for maleopgaver (dvs. ændre billedpunkter), ikke-maleopgaver og maleopgaver for former. </para
><para
>Et værktøj har en grafisk indstillingskontrol, præcis som filtre. For øjeblikket vises de grafiske indstillingskontroller i et faneblad i et dokket vindue. Det kan komme til at blive ændret til en linje under hovedmenuen (som så erstatter værktøjslinjen) for &chalk; 2.0, men for øjeblikket skal indstillingskontroller konstrueres for at få plads i et faneblad. Som altid er det bedst at bruge &Qt; Designer til konstruktion af indstillingskontrollen. </para
><para
>Et godt eksempel på et værktøj er stjerneværktøjet: </para>
<screen
>kis_tool_star.cc Makefile.am tool_star_cursor.png wdg_tool_star.ui
kis_tool_star.h Makefile.in tool_star.h
chalktoolstar.desktop tool_star.cc tool_star.png
</screen>
<para
>Som du ser, har du brug for to billeder: et for markøren og et for værktøjskassen. <filename
>tool_star.cc</filename
> indlæser kun pluginnet, på lignende måde som vi har set ovenfor. Det egentligt nyttige findes i implementeringen: </para>
<programlisting
>KisToolStar::KisToolStar()
: KisToolShape(i18n("Star")),
m_dragging (false),
m_currentImage (0)
{
setName("tool_star");
setCursor(KisCursor::load("tool_star_cursor.png", 6, 6));
m_innerOuterRatio=40;
m_vertices=5;
}
</programlisting>
<para
>Konstruktoren laver det interne navn, som ikke oversættes, og kaldet til superklassen angiver det synlige navn. Vi indlæser også markørbilledet og tildeler værdier til et antal variabler. </para>
<programlisting
>void KisToolStar::update (KisCanvasSubject *subject)
{
KisToolShape::update (subject);
if (m_subject)
m_currentImage = m_subject->currentImg();
}
</programlisting>
<para
>Metoden <methodname
>update()</methodname
> kaldes når værktøjet vælges. Dette er ikke en metode i <classname
>KisTool</classname
>, men en metode i <classname
>KisCanvasObserver</classname
>. Kanvasobservatører underrettes så snart noget ændres i visningen, hvilket kan være nyttigt for værktøjer. </para
><para
>Følgende metoder (<methodname
>buttonPress</methodname
>, <methodname
>move</methodname
> og <methodname
>buttonRelease</methodname
>) kaldes af &chalk; når indtastningsenheden (mus, pen, viskelæder, osv.) trykkes ned, flyttes eller slippes. Bemærk at forflytningsbegivenheder også afgives hvis museknappen ikke er trykket ned. Begivenhederne er ikke de sædvanlige &Qt;-begivenheder, men syntetiske begivenheder i &chalk;, eftersom vi drager nytte af trick på lavt niveau for at få tilstrækkeligt med begivenheder til at tegne en glat linje. Normalt smider værktøjskasser såsom &Qt; (og GTK) begivenheder væk hvis de er for travle til at håndtere dem, og vi vil have dem alle. </para>
<programlisting
>void KisToolStar::buttonPress(KisButtonPressEvent *event)
{
if (m_currentImage && event->button() == LeftButton) {
m_dragging = true;
m_dragStart = event->pos();
m_dragEnd = event->pos();
m_vertices = m_optWidget->verticesSpinBox->value();
m_innerOuterRatio = m_optWidget->ratioSpinBox->value();
}
}
void KisToolStar::move(KisMoveEvent *event)
{
if (m_dragging) {
// erase old lines on canvas
draw(m_dragStart, m_dragEnd);
// move (alt) or resize star
if (event->state() & Qt::AltButton) {
KisPoint trans = event->pos() - m_dragEnd;
m_dragStart += trans;
m_dragEnd += trans;
} else {
m_dragEnd = event->pos();
}
// draw new lines on canvas
draw(m_dragStart, m_dragEnd);
}
}
void KisToolStar::buttonRelease(KisButtonReleaseEvent *event)
{
if (!m_subject || !m_currentImage)
return;
if (m_dragging && event->button() == LeftButton) {
// erase old lines on canvas
draw(m_dragStart, m_dragEnd);
m_dragging = false;
if (m_dragStart == m_dragEnd)
return;
if (!m_currentImage)
return;
if (!m_currentImage->activeDevice())
return;
KisPaintDeviceSP device = m_currentImage->activeDevice ();;
KisPainter painter (device);
if (m_currentImage->undo()) painter.beginTransaction (i18n("Star"));
painter.setPaintColor(m_subject->fgColor());
painter.setBackgroundColor(m_subject->bgColor());
painter.setFillStyle(fillStyle());
painter.setBrush(m_subject->currentBrush());
painter.setPattern(m_subject->currentPattern());
painter.setOpacity(m_opacity);
painter.setCompositeOp(m_compositeOp);
KisPaintOp * op =
KisPaintOpRegistry::instance()->paintOp(m_subject->currentPaintop(), m_subject->currentPaintopSettings(), &painter);
painter.setPaintOp(op); // Painter takes ownership
vKisPoint coord = starCoordinates(m_vertices, m_dragStart.x(), m_dragStart.y(), m_dragEnd.x(), m_dragEnd.y());
painter.paintPolygon(coord);
device->setDirty( painter.dirtyRect() );
notifyModified();
if (m_currentImage->undo()) {
m_currentImage->undoAdapter()->addCommand(painter.endTransaction());
}
}
}
</programlisting>
<para
>Metoden <methodname
>draw()</methodname
> er en intern metode i <classname
>KisToolStar</classname
> som tegner stjernens omrids. Vi kalder den fra metoden <methodname
>move()</methodname
> for at give brugeren tilbagemelding om stjernens størrelse og form. Bemærk at vi bruger <varname
>Qt::NotROP</varname
> rasteroperationen, hvilket betyder at kalde <methodname
>draw()</methodname
> endnu en gang med samme start- og slutpunkt gør at stjernen fjernes. </para>
<programlisting
>void KisToolStar::draw(const KisPoint& start, const KisPoint& end )
{
if (!m_subject || !m_currentImage)
return;
KisCanvasController *controller = m_subject->canvasController();
KisCanvas *canvas = controller->kiscanvas();
KisCanvasPainter p (canvas);
QPen pen(Qt::SolidLine);
KisPoint startPos;
KisPoint endPos;
startPos = controller->windowToView(start);
endPos = controller->windowToView(end);
p.setRasterOp(Qt::NotROP);
vKisPoint points = starCoordinates(m_vertices, startPos.x(), startPos.y(), endPos.x(), endPos.y());
for (uint i = 0; i < points.count() - 1; i++) {
p.drawLine(points[i].floorQPoint(), points[i + 1].floorQPoint());
}
p.drawLine(points[points.count() - 1].floorQPoint(), points[0].floorQPoint());
p.end ();
}
</programlisting>
<para
>Metoden <methodname
>setup()</methodname
> er fundamental: Her laver vi handlingen som vil blive puttet ind i værktøjskassen så brugere virkelig kan vælge værktøjet. Vi tildeler også en genvejstast. Bemærk at en del programkneb bruges her. Husk at vi oprettede en instans af værktøjet for hver indtastningsenhed. Det betyder også at vi kalder <methodname
>setup()</methodname
> for hver indtastningsenhed og at en handling med samme navn lægges til flere gange i handlingssamlingen. Men alt synes at virke, så hvorfor bekymre sig? </para>
<programlisting
>void KisToolStar::setup(KActionCollection *collection)
{
m_action = static_cast<KRadioAction *>(collection->action(name()));
if (m_action == 0) {
KShortcut shortcut(Qt::Key_Plus);
shortcut.append(KShortcut(Qt::Key_F9));
m_action = new KRadioAction(i18n("&Star"),
"tool_star",
shortcut,
this,
SLOT(activate()),
collection,
name());
Q_CHECK_PTR(m_action);
m_action->setToolTip(i18n("Draw a star"));
m_action->setExclusiveGroup("tools");
m_ownAction = true;
}
}
</programlisting>
<para
>Metoden <methodname
>starCoordinates()</methodname
> indeholder en del underlig matematik, men den er ikke særlig interessant i beskrivelsen af hvordan man laver værktøjsplugin. </para>
<programlisting
>KisPoint KisToolStar::starCoordinates(int N, double mx, double my, double x, double y)
{
double R=0, r=0;
Q_INT32 n=0;
double angle;
vKisPoint starCoordinatesArray(2*N);
// the radius of the outer edges
R=sqrt((x-mx)*(x-mx)+(y-my)*(y-my));
// the radius of the inner edges
r=R*m_innerOuterRatio/100.0;
// the angle
angle=-atan2((x-mx),(y-my));
//set outer edges
for(n=0;n<N;n++){
starCoordinatesArray[2*n] = KisPoint(mx+R*cos(n * 2.0 * M_PI / N + angle),my+R*sin(n *2.0 * M_PI / N+angle));
}
//set inner edges
for(n=0;n<N;n++){
starCoordinatesArray[2*n+1] = KisPoint(mx+r*cos((n + 0.5) * 2.0 * M_PI / N + angle),my+r*sin((n +0.5) * 2.0 * M_PI / N + angle));
}
return starCoordinatesArray;
}
</programlisting>
<para
>Metoden <methodname
>createOptionWidget()</methodname
> kaldes for at oprette den grafiske indstillingskontrol som &chalk; viser fanebladet. Eftersom der er et værktøj per indtastningsenhed og per visning, kan tilstanden af et værktøj opbevares i værktøjet. Denne metode kaldes kun en gang: den grafiske indstillingskontrol opbevares og hentes næste gang værktøjet aktiveres. </para>
<programlisting
>QWidget* KisToolStar::createOptionWidget(QWidget* parent)
{
QWidget *widget = KisToolShape::createOptionWidget(parent);
m_optWidget = new WdgToolStar(widget);
Q_CHECK_PTR(m_optWidget);
m_optWidget->ratioSpinBox->setValue(m_innerOuterRatio);
QGridLayout *optionLayout = new QGridLayout(widget, 1, 1);
super::addOptionWidgetLayout(optionLayout);
optionLayout->addWidget(m_optWidget, 0, 0);
return widget;
}
</programlisting>
<sect3 id="developers-plugins-tools-conclusions">
<title
>Afslutning af værktøj</title>
<para
>Værktøjer er relativt simple plugin at oprette. Du skal kombinere grænsefladen <classname
>KisTool</classname
> og <classname
>KisCanvasObserver</classname
> for at oprette et værktøj effektivt. </para>
</sect3>
</sect2>
<sect2 id="developers-plugins-paintoperations">
<title
>Maleoperationer</title>
<para
>Maleoperationer er en af de mest opfindsomme typer af plugin i Chalk (sammen med farverum som kan bruges som plugin). En maleoperation definerer hvordan værktøj ændrer de billedpunkter de berører. Retuschsprøjte, pen uden antialias eller billedpunktpensel med antialias er alle maleoperationer. Men du skulle kunne, med en stor mængde arbejde, oprette en maleoperation som læser Corel Paint XML-penseldefinitioner og bruger dem til at bestemme hvordan man skal male </para
><para
>Maleoperationer instantieres når et maleværktøj modtager begivenheden <literal
>mouseDown</literal
> og fjernes når begivenheden mouseUp modtages af et maleværktøj. I mellemtiden kan maleoperationen holde styr på tidligere positioner og anden information, såsom trykniveauer hvis brugeren bruger en styreplade. </para
><para
>Den grundlæggende handling for en maleoperation er at ændre billedpunkter ved et maleværktøjs markørposition. Det kan kun gøres en gang, eller også kan maleoperationen bede om at blive udført med regelmæssige intervaller, ved brug af en tidsmåler. Det første tilfælde er nyttigt for en penlignende maleoperation, og det andet naturligvis for en maleoperation som ligner en retuschsprøjte. </para
><para
>Maleoperationer kan have en lille grafisk indstillingskontrol som placeres i en værktøjslinje. Altså skal grafiske indstillingskontroller for maleoperationer have en vandret layout som ikke er højere end en knap i en værktøjslinje, ellers ville &chalk; se meget mærkeligt ud. </para
><para
>Lad os kigge på et enkelt plugin for en maleoperation,, et som viser en vis mængde programbaseret intelligens. For det første er der en fabrik defineret i deklarationsfilen. Denne fabrik laver en maleoperation når det aktive værktøj behøver en: </para>
<programlisting
>public:
KisSmearyOpFactory() {}
virtual ~KisSmearyOpFactory() {}
virtual KisPaintOp * createOp(const KisPaintOpSettings *settings, KisPainter * painter);
virtual KisID id() { return KisID("paintSmeary", i18n("Smeary Brush")); }
virtual bool userVisible(KisColorSpace * ) { return false; }
virtual QString pixmap() { return ""; }
};
</programlisting>
<para
>Fabrikken indeholder også <classname
>KisID</classname
> med det offentlige og private navn på maleoperationen, og kan valgfrtt returnere en punktafbildning. &chalk; kan derefter vise punktafbildningen sammen med navnet som en visuel identifikation af maleoperationen. For eksempel vil maleoperationen malerkniv have et billede af et sådant værktøj. Sørg for at maleoperationens private navn ikke kommer i konflikt med en anden maleoperation. </para
><para
>Implementeringen af maleoperationer er meget ligetil: </para>
<programlisting
>KisSmearyOp::KisSmearyOp(KisPainter * painter)
: KisPaintOp(painter)
{
}
KisSmearyOp::~KisSmearyOp()
{
}
void KisSmearyOp::paintAt(const KisPoint &pos, const KisPaintInformation& info)
{
</programlisting>
<para
>Metoden <methodname
>paintAt()</methodname
> er stedet hvor alt sker for maleoperationer. Denne metode har to parametre, den nuværende position (som angives i floats, ikke i hele billedpunkter) og objektet <classname
>KisPaintInformation</classname
>, som indeholder tryk, x, y, hældning og forflytningsvektor, og som kan udvides med yderligere information i fremtiden. </para>
<programlisting
>if (!m_painter->device()) return;
KisBrush *brush = m_painter->brush();
</programlisting>
<para
>En <classname
>KisBrush</classname
> er repræsentationen af en Gimp penselfil: det vil sige en maske, enten en enkelt maske eller en serie masker. I virkeligheden bruger vi ikke penslen her, men til at bestemme <quote
>malepunktet</quote
> under markøren. </para>
<programlisting
>Q_ASSERT(brush);
if (!brush) return;
if (! brush->canPaintFor(info) )
return;
KisPaintDeviceSP device = m_painter->device();
KisColorSpace * colorSpace = device->colorSpace();
KisColor kc = m_painter->paintColor();
kc.convertTo(colorSpace);
KisPoint hotSpot = brush->hotSpot(info);
KisPoint pt = pos - hotSpot;
// Split the coordinates into integer plus fractional parts. The integer
// is where the dab will be positioned and the fractional part determines
// the sub-pixel positioning.
Q_INT32 x, y;
double xFraction, yFraction;
splitCoordinate(pt.x(), &x, &xFraction);
splitCoordinate(pt.y(), &y, &yFraction);
KisPaintDeviceSP dab = new KisPaintDevice(colorSpace, "smeary dab");
Q_CHECK_PTR(dab);
</programlisting>
<para
>Vi ændrer ikke billedpunkterne på en maleenheden direkte: i stedet laver vi en lille maleenhed, en dab, og sammensætter den med den nuværende maleenhed. </para>
<programlisting
>m_painter->setPressure(info.pressure);
</programlisting>
<para
>I overensstemmelse med kommentarerne, udfører følgende kodestump lidt programarbejde for at oprette selve dabben. I dette tilfælde tegner vi et antal linjer. Når maleoperationen er færdig, kommer linjernes længde, position og tykhed til at afhænge af tryk og farvemængde, og vi har oprettet en stiv, smidig oljefarvepensel. Men jeg har ikke haft tid at afslutte dette endnu. </para>
<programlisting
>// Compute the position of the tufts. The tufts are arranged in a line
// perpendicular to the motion of the brush, i.e, the straight line between
// the current position and the previous position.
// The tufts are spread out through the pressure
KisPoint previousPoint = info.movement.toKisPoint();
KisVector2D brushVector(-previousPoint.y(), previousPoint.x());
KisVector2D currentPointVector = KisVector2D(pos);
brushVector.normalize();
KisVector2D vl, vr;
for (int i = 0; i < (NUMBER_OF_TUFTS / 2); ++i) {
// Compute the positions on the new vector.
vl = currentPointVector + i * brushVector;
KisPoint pl = vl.toKisPoint();
dab->setPixel(pl.roundX(), pl.roundY(), kc);
vr = currentPointVector - i * brushVector;
KisPoint pr = vr.toKisPoint();
dab->setPixel(pr.roundX(), pr.roundY(), kc);
}
vr = vr - vl;
vr.normalize();
</programlisting>
<para
>Tilsidst overfører vi dabben med en blokoverførsel på den oprindelige maleenhed og fortæller maleren at vi har påvirket et lille rektangel på maleenheden. </para>
<programlisting
>if (m_source->hasSelection()) {
m_painter->bltSelection(x - 32, y - 32, m_painter->compositeOp(), dab.data(),
m_source->selection(), m_painter->opacity(), x - 32, y -32, 64, 64);
}
else {
m_painter->bitBlt(x - 32, y - 32, m_painter->compositeOp(), dab.data(), m_painter->opacity(), x - 32, y -32, 64, 64);
}
m_painter->addDirtyRect(QRect(x -32, y -32, 64, 64));
}
KisPaintOp * KisSmearyOpFactory::createOp(const KisPaintOpSettings */*settings*/, KisPainter * painter)
{
KisPaintOp * op = new KisSmearyOp(painter);
Q_CHECK_PTR(op);
return op;
}
</programlisting>
<para
>Det er alt: maleoperationer er nemme og sjove! </para>
</sect2>
<sect2 id="developers-plugins-viewplugins">
<title
>Visningsplugin</title>
<para
>Visningsplugin er de mærkeligste i hele gænget: Et visningsplugin er en sædvanlig KPart som kan sørge for en vss mængde brugergrænseflade og en del funktioner. Histogramfanebladet er for eksempel et visningsplugin, ligesom rotationsdialogen. </para>
</sect2>
<sect2 id="developers-plugins-importexport">
<title
>Import- og eksportfiltre</title>
<para
>&chalk; arbejder med den sædvanlige filterarkitektur for filer i &koffice;. Der findes en vejledning, noget gammel, men stadigvæk nyttig, på: <ulink url="http://koffice.org/developer/filters/oldfaq.php"
></ulink
>. Det er sandsynligvis bedst at samarbejde med &chalk;-gruppen ved udvikling af filfiltere og at gøre udviklingen i &koffice; filtertræ. Bemærk at du kan teste filtre uden at køre &chalk; ved at bruge værktøjet <command
>koconverter</command
>. </para
><para
>Filtre har to sider: import og eksport. De er oftest to forskellige plugin som kan dele noget kode. </para
><para
>De vigtige indgange i <filename
>Makefile.am</filename
> er: </para>
<programlisting
>service_DATA = chalk_XXX_import.desktop chalk_XXX_export.desktop
servicedir = $(kde_servicesdir)
kdelnk_DATA = chalk_XXX.desktop
kdelnkdir = $(kde_appsdir)/Office
libchalkXXXimport_la_SOURCES = XXXimport.cpp
libchalkXXXexport_la_SOURCES = XXXexport.cpp
METASOURCES = AUTO
</programlisting>
<para
>Uafhængigt af om du laver et importfilter eller et eksportfilter, er indholdet af arbejdet altid at implementere følgende funktion: </para>
<programlisting
>virtual KoFilter::ConversionStatus convert(const QCString& from, const QCString& to);
</programlisting>
<para
>Det er indstillingerna i filen <literal role="extension"
>.desktop</literal
> som afgør på hvilken måde et filter konverterer: </para
><para
>Import: </para>
<programlisting
>X-KDE-Export=application/x-chalk
X-KDE-Import=image/x-xcf-gimp
X-KDE-Weight=1
X-KDE-Library=libchalkXXXimport
ServiceTypes=KOfficeFilter
</programlisting>
<para
>Eksport: </para>
<programlisting
>X-KDE-Export=image/x-xcf-gimp
X-KDE-Import=application/x-chalk
ServiceTypes=KOfficeFilter
Type=Service
X-KDE-Weight=1
X-KDE-Library=libchalkXXXexport
</programlisting>
<para
>Og ja, MIME-typen som er valgt i eksemplet er en antydning: Vær virkelig sød og implemetér et XCF-filter! </para>
<sect3 id="plugins-developers-importexport-import">
<title
>Import</title>
<para
>Det store problem med importfiltre er naturligvis koden til at læse data på disken. Standardkoden for at kalde denne kode er ganske enkel: </para>
<note
><para
>Bemærk: Vi burde virkelig finde en måde at gøre det muligt for &chalk; at holde en fil åben kun læse data efterhånden som det behøves, i stedet for at kopiere hele indholdet til den interne repræsentationen i maleenheden. Men det ville betyde en grænseflade for datahåndtering som kender til TIFF-filer og så videre, og dette er for øjeblikket ikke implementeret. Det ville være ideelt hvis visse filfiltre kunne implementere en klasse, preliminært kaldet <classname
>KisFileDataManager</classname
>, oprette et objekt af den instans med den nuværende fil og sende den til KisDoc. Men &chalk; håndterer opbevaring per lag, ikke per dokument, så det ville være en svær omskrivning.</para
></note>
<programlisting
>KoFilter::ConversionStatus XXXImport::convert(const QCString&, const QCString& to)
{
if (to != "application/x-chalk") <co id="import1" />
return KoFilter::BadMimeType;
KisDoc * doc = dynamic_cast<KisDoc*>(m_chain -> outputDocument()); <co id="import2" />
KisView * view = static_cast<KisView*>(doc -> views().getFirst()); <co id="import3" />
QString filename = m_chain -> inputFile(); <co id="import4" />
if (!doc)
return KoFilter::CreationError;
doc -> prepareForImport(); <co id="import5" />
if (!filename.isEmpty()) {
KURL url(filename);
if (url.isEmpty())
return KoFilter::FileNotFound;
KisImageXXXConverter ib(doc, doc -> undoAdapter()); <co id="import6" />
if (view != 0)
view -> canvasSubject() -> progressDisplay() -> setSubject(&ib, false, true);
switch (ib.buildImage(url)) <co id="import7" /> {
case KisImageBuilder_RESULT_UNSUPPORTED:
return KoFilter::NotImplemented;
break;
case KisImageBuilder_RESULT_INVALID_ARG:
return KoFilter::BadMimeType;
break;
case KisImageBuilder_RESULT_NO_URI:
case KisImageBuilder_RESULT_NOT_LOCAL:
return KoFilter::FileNotFound;
break;
case KisImageBuilder_RESULT_BAD_FETCH:
case KisImageBuilder_RESULT_EMPTY:
return KoFilter::ParsingError;
break;
case KisImageBuilder_RESULT_FAILURE:
return KoFilter::InternalError;
break;
case KisImageBuilder_RESULT_OK:
doc -> setCurrentImage( ib.image()); <co id="import8" />
return KoFilter::OK;
default:
break;
}
}
return KoFilter::StorageCreationError;
}
</programlisting>
<calloutlist>
<callout arearefs="import1"
><para
>Dette er beregnet til at være et importfilter, så hvis det ikke kaldes for at konvertere til et billede i &chalk;, er der noget som er forkert.</para
></callout>
<callout arearefs="import2"
><para
>Filterkæden har allerede oprettet et uddatadokument for os. Vi skal typekonvertere det til <classname
>KisDocM</classname
>, eftersom &chalk;-dokumenter kræver særlig behandling. Det ville i virkeligheden ikke være en dum idé at kontrollere at resultatet af typekonverteringen ikke er 0, eftersom hvis den er det vil importen mislykkes.</para
></callout>
<callout arearefs="import3"
><para
>Hvis vi kalder filtret fra den grafiske grænseflade, forsøger vi at få visningen. Hvis der er en visning, kan konverteringskoden forsøge at opdatere fremgangslinjen.</para
></callout>
<callout arearefs="import4"
><para
>Filtret har filnavnet på inddatafilen for os.</para
></callout>
<callout arearefs="import5"
><para
><classname
>KisDoc</classname
> skal forberedes for import. Visse indstillinger initieres og fortryd deaktiveres. Ellers ville du kunne fortryde tilføjelse af lag som udføres af importfiltret, og det er en mærkelig opførsel.</para
></callout>
<callout arearefs="import6"
><para
>Jeg har valgt at implementere selve importkoden i en separat klasse som jeg instantierer her. Du kan også lægge al din kode direkte i denne metode, men det ville være lidt rodet.</para
></callout>
<callout arearefs="import7"
><para
>Min importkode returnerer en statuskode, som jeg siden kan bruge til at angive status for importfiltret. &koffice; sørger for at vise fejlmeddelelser.</para
></callout>
<callout arearefs="import8"
><para
>Hvis det er lykkedes at oprette <classname
>KisImage</classname
> sætter vi dokumentets nuværende billede til vort nyoprettede billede. Derefter er vi færdige: <literal
>return KoFilter::OK;</literal
>.</para
></callout>
</calloutlist>
</sect3>
</sect2>
</sect1>
|