path: root/tde-i18n-pl/docs/tdebase/kate/advanced.docbook

<chapter id="advanced-editing-tools">
<chapterinfo>
<authorgroup>
<author>&Anders.Lund; &Anders.Lund.mail;</author>
<author>&Dominik.Haumann; &Dominik.Haumann.mail;</author>
<othercredit role="translator"><firstname>Suse</firstname><surname>Polska</surname><affiliation><address><email>[email protected]</email></address></affiliation><contrib>Polskie tłumaczenie</contrib></othercredit> <othercredit role="translator"><firstname>Krzysztof</firstname><surname>Woźniak</surname><affiliation><address><email>[email protected]</email></address></affiliation><contrib>Polskie tłumaczenie</contrib></othercredit>  
</authorgroup>
</chapterinfo>
<title>Zaawansowane narzędzia edycyjne</title>

<sect1 id="advanced-editing-tools-comment">

<title>Komentarz/Odkomentuj</title>

<para>Polecenia Komentarz i Odkomentuj dostępne z menu <guimenu>Narzędzia</guimenu> pozwalają na dodanie znaczników komentarza do zaznaczonego fragmentu tekstu (lub do bieżącego wiersza, gdy brak zaznaczenia). Bieżący format dokumentu musi obsługiwać możliwość komentowania tekstu.</para>

<para>Sposób komentowania jest określony w definicji reguł podświetlania składni. Jeżeli podświetlanie składni jest wyłączone, to polecenia Komentarz i Odkomentuj są nieaktywne. </para>

<para>Dla pewnych formatów dokumentów zdefiniowane są znaczniki komentowania wiersza, inne zaś zawierają znaczniki komentarzy jedno- i wielowierszowych. Jeżeli znaczniki komentarza wielowierszowego są niedostępne, to nie będzie się dało skomentować zaznaczenia nie zawierającego w sobie całości ostatniego wiersza.</para>

<para>Gdy dostępny jest znacznik komentarza dla całego wiersza kodu, to jego użycie jest preferowane, gdyż pozwala na uniknięcie problemów w przypadku zagnieżdżonych komentarzy.</para>

<para>Podczas usuwania znaczników komentarza nie należy zaznaczać tekstu nie będącego komentarzem. Jeżeli usuwany jest komentarz wielowierszowy z zaznaczenia, to wszystkie spacje znajdujące się poza znacznikami komentarza są ignorowane.</para>

<para><indexterm><primary>komentuj</primary></indexterm> Aby skomentować fragment tekstu należy użyć menu <menuchoice><guimenu>Narzędzia</guimenu><guimenuitem>Komentarz</guimenuitem></menuchoice>, lub skrótu klawiszowego <keycombo action="simul">&Ctrl;<keycap>D</keycap></keycombo>.</para>

<para><indexterm><primary>odkomentuj</primary></indexterm> Aby usunąć znaczniki komentarza z wybranego fragmentu tekstu, należy użyć menu <menuchoice><guimenu>Narzędzia</guimenu><guimenuitem>Odkomentuj</guimenuitem></menuchoice>, lub skrótu klawiszowego <keycombo action="simul">&Ctrl; &Shift;<keycap>D</keycap></keycombo>.</para>

</sect1>

<sect1 id="advanced-editing-tools-commandline">
<title>Linia poleceń edytora</title>

<para>Komponent edytora w &kate; zawiera wbudowaną linię poleceń, pozwalającą na sterowanie pracą bez pośrednictwa graficznego interfejsu użytkownika. Linia poleceń znajduje sią w dolnej części okna edytora, aby ją włączyć należy wybrać z menu: <menuchoice><guimenu>Widok</guimenu><guimenuitem>Przełącz do linii poleceń</guimenuitem></menuchoice> lub skorzystać ze skrótu klawiszowego (domyślnie jest to <keycombo action="simul"><keycap>F7</keycap></keycombo>). Zestaw poleceń dostępnych w linii poleceń edytora opisany został poniżej. Może on ulec rozszerzeniu przez zastosowanie wtyczek.</para>

<para>Naciśnięcie klawisza ENTER uruchamia wprowadzone polecenie. Komunikat wyświetlony w linii poleceń pokaże informacje o wynikach polecenia lub ewentualnym błędzie. Jeżeli linia poleceń została wyświetlona za pomocą klawisza <keycap>F7</keycap>, to schowa się ona automatycznie po kilku sekundach. Ponowne naciśnięcie klawisza <keycap>F7</keycap> usuwa komunikat i pozwala na wprowadzenie następnego polecenia.</para>

<para>Linia poleceń zawiera wbudowany system pomocy uruchamiany poleceniem <command>help</command>. Aby wyświetlić listę wszystkich dostępnych poleceń należy wpisać <command>help list</command>. Pomoc dotycząca wybranego polecenia dostępna jest po wpisaniu: <command>help <replaceable>polecenie</replaceable></command>.</para>

<para>Linia poleceń przechowuje historię poleceń pozwalając na ponowne użycie poleceń wcześniej już wpisanych. Dostęp i nawigacja w historii linii poleceń odbywa się za pomocą klawiszy strzałek <keycap>w górę</keycap> oraz <keycap>w dół</keycap>. Argumenty wywołanych z historii poleceń będą zaznaczone, pozwalając na łatwą ich zmianę.</para>

<sect2 id="advanced-editing-tools-commandline-commands">
<title>Polecenia standardowe</title>

<sect3 id="advanced-editing-tools-commandline-commands-configure">
<title>Polecenia konfiguracyjne edytora</title>

<para>Polecenia opisane poniżej dotyczą wbudowanego edytora i pozwalają na konfigurację bieżącego widoku i dokumentu. Może to być przydatne, gdy użytkownik chce wykorzystać ustawienia inne niż domyślne, np. dla automatycznych wcięć. </para>

<variablelist>
<title>Typy argumentów</title>

<varlistentry>
<term>BOOLEAN</term>
<listitem><para>Stosowane dla poleceń, które włączają lub wyłączają jakąś funkcję. Dopuszczalne wartości takiego argumentu to:<userinput>on</userinput>, <userinput>off</userinput>, <userinput>true</userinput>, <userinput>false</userinput>, <userinput>1</userinput> lub <userinput>0</userinput></para></listitem>
</varlistentry>

<varlistentry>
<term>INTEGER</term>
<listitem><para>Liczba całkowita</para></listitem>
</varlistentry>

<varlistentry>
<term>STRING</term>
<listitem><para>Napis</para></listitem>
</varlistentry>

</variablelist>

<variablelist>

<varlistentry>
<term><cmdsynopsis><command>set-tab-width</command><arg>INTEGER szerokość</arg></cmdsynopsis></term>
<listitem><para>Ustawia szerokość tabulacji (w znakach) na wartość określoną przez argument <userinput>szerokość</userinput>.</para></listitem>
</varlistentry>

<varlistentry>
<term><cmdsynopsis><command>set-indent-width</command><arg>INTEGER szerokość</arg></cmdsynopsis></term>
<listitem><para>Ustawia szerokość wcięcia na wartość określoną przez argument <userinput>szerokość</userinput>. Polecenie odnosi się do trybu wcięć dokonywanych za pomocą znaku spacji.</para></listitem>
</varlistentry>

<varlistentry>
<term><cmdsynopsis><command>set-word-wrap-column</command><arg>INTEGER szerokość</arg></cmdsynopsis></term>
<listitem><para>Ustawia liczbę znaków w wierszu dla funkcji statycznego zawijania wyrazów na wartość określoną przez argument <userinput>szerokość</userinput>. Działa jedynie w przypadku włączonego automatycznego zawijania wyrazów.</para></listitem>
</varlistentry>

<varlistentry>
<term><cmdsynopsis><command>set-icon-border</command><arg>BOOLEAN włącz</arg> </cmdsynopsis></term>
<listitem><para>Włącza lub wyłącza wyświetlanie paska ikon.</para></listitem>
</varlistentry>

<varlistentry>
<term><cmdsynopsis><command>set-folding-markers</command><arg>BOOLEAN włącz</arg></cmdsynopsis></term>
<listitem><para>Włącza lub wyłącza wyświetlanie paska znaczników zwijania kodu.</para></listitem>
</varlistentry>

<varlistentry>
<term><cmdsynopsis><command>set-line-numbers</command><arg>BOOLEAN włącz</arg></cmdsynopsis></term>
<listitem><para>Włącza lub wyłącza wyświetlanie paska z numerami wierszy.</para></listitem>
</varlistentry>

<varlistentry>
<term><cmdsynopsis><command>set-replace-tabs</command><arg>BOOLEAN włącz</arg></cmdsynopsis></term>
<listitem><para>Włącza lub wyłącza zastępowanie znaków tabulacji znakami spacji w trakcie pisania. </para></listitem>
</varlistentry>

<varlistentry>
<term><cmdsynopsis><command>set-remove-trailing-space</command><arg>BOOLEAN włącz</arg></cmdsynopsis></term>
<listitem><para>Włącza lub wyłącza usuwanie spacji końcowych po przejściu kursorem do innego wiersza.</para></listitem>
</varlistentry>

<varlistentry>
<term><cmdsynopsis><command>set-show-tabs</command><arg>BOOLEAN włącz</arg></cmdsynopsis></term>
<listitem><para>Włącza lub wyłącza wyświetlanie małej kropki w miejscu znaków tabulacji oraz spacji kończących wiersz.</para></listitem>
</varlistentry>

<varlistentry>
<term><cmdsynopsis><command>set-indent-spaces</command><arg>BOOLEAN włącz</arg></cmdsynopsis></term>
<listitem><para>Włącza lub wyłącza generowanie wcięć za pomocą zdefiniowanej przez parametr <option>indent-width</option> liczby spacji, dla każdego poziomu wcięcia. Wyłączenie opcji przywraca stosowanie znaku tabulacji do generowania wcięć.</para></listitem>
</varlistentry>

<varlistentry>
<term><cmdsynopsis><command>set-mixed-indent</command><arg>BOOLEAN włącz</arg></cmdsynopsis></term>
<listitem><para>Włączenie tej opcji pozwala na jednoczesne użycie znaków tabulacji i spacji do generowania wcięć przez &kate;. Poziomy wcięć będą określane zgodnie z ustawieniami opcji <option>indent-width</option>, zaś wcięcia wielopoziomowe będą generowane za pomocą największej możliwej liczby znaków tabulacji.</para>
<para>Po wykonaniu tego polecenia, dodatkowo włączona zostanie funkcja wcięć za pomocą spacji, a jeżeli szerokość wcięcia jest nieokreślona, to zostanie ustawiona na połowę wartości parametru <option>tab-width</option> określonego dla bieżącego dokumentu.</para></listitem>
</varlistentry>

<varlistentry>
<term><cmdsynopsis><command>set-word-wrap</command><arg>BOOLEAN włącz</arg></cmdsynopsis></term>
<listitem><para>Włącza lub wyłącza funkcję dynamicznego zawijania wyrazów</para></listitem>
</varlistentry>

<varlistentry>
<term><cmdsynopsis><command>set-replace-tabs-save</command><arg>BOOLEAN włącz </arg></cmdsynopsis></term>
<listitem><para>Włącza lub wyłącza zamienianie znaków tabulacji na spacje przed zapisaniem dokumentu.</para></listitem>
</varlistentry>

<varlistentry>
<term><cmdsynopsis><command>set-remove-trailing-space-save</command><arg>BOOLEAN włącz</arg></cmdsynopsis></term>
<listitem><para>Włącza lub wyłącza usuwanie spacji kończących wiersze przed jego zapisaniem.</para></listitem>
</varlistentry>

<varlistentry>
<term><cmdsynopsis><command>set-indent-mode</command><arg>nazwa</arg></cmdsynopsis></term>
<listitem><para>Określa tryb automatycznych wcięć, możliwe <userinput>nazwy</userinput> trybów to: 'cstyle', 'csands', 'xml', 'python', 'varindent' oraz 'none'. Jeżeli wprowadzona nazwa jest nieznana to przyjęta zostanie wartość 'none'.</para></listitem>
</varlistentry>

<varlistentry>
<term><cmdsynopsis><command>set-highlight</command><arg>nazwa</arg></cmdsynopsis></term>
<listitem><para>Wybiera zestaw reguł podświetlania składni dla dokumentu. Argument musi określać nazwę istniejącej reguły podświetlania. Dostępne nazwy widoczne są w menu: <menuchoice><guimenu>Narzędzia</guimenu><guisubmenu>Podświetlenie</guisubmenu></menuchoice>. W trakcie wprowadzania polecenia, pojawi się pomocnicza lista automatycznego dopełniania nazwy.</para></listitem>
</varlistentry>

</variablelist>

</sect3>

<sect3 id="advanced-editing-tools-commandline-commands-edit">
<title>Polecenia edycyjne</title>

<para>Ich wykonanie modyfikuje bieżący dokument.</para>

<variablelist>
<varlistentry>
<term><cmdsynopsis><command>indent</command></cmdsynopsis></term>
<listitem><para>Generuje wcięcie w wybranych wierszach lub w bieżącym wierszu.</para></listitem>
</varlistentry>

<varlistentry>
<term><cmdsynopsis><command>unindent</command></cmdsynopsis></term>
<listitem><para>Usuwa wcięcie z zaznaczonego fragmentu lub bieżącego wiersza.</para></listitem>
</varlistentry>

<varlistentry>
<term><cmdsynopsis><command>cleanindent</command></cmdsynopsis></term>
<listitem><para>Wyrównuje wcięcia dla zaznaczonego fragmentu tekstu lub dla bieżącego wiersza, zgodnie z ustawionymi dla dokumentu regułami wcięć. </para></listitem>
</varlistentry>

<varlistentry>
<term><cmdsynopsis><command>comment</command></cmdsynopsis></term>
<listitem><para>Wprowadza znaczniki komentarza dla zaznaczonego fragmentu tekstu lub dla bieżącego wiersza, zgodnie z definicją reguł podświetlania składni wybraną dla bieżącego dokumentu.</para></listitem>
</varlistentry>

<varlistentry>
<term><cmdsynopsis><command>uncomment</command></cmdsynopsis></term>
<listitem><para>Usuwa znaczniki komentarza z zaznaczonego fragmentu tekstu lub bieżącego wiersza, zgodnie z definicją reguł podświetlania składni wybraną dla bieżącego dokumentu.</para></listitem>
</varlistentry>

<varlistentry>
<term><cmdsynopsis><command>kill-line</command></cmdsynopsis></term>
<listitem><para>Usuwa bieżący wiersz.</para></listitem>
</varlistentry>

<varlistentry>
<term><cmdsynopsis><command>replace</command><arg>wzorzec</arg><arg>zastąpienie</arg></cmdsynopsis></term>
<listitem><para>Zamienia tekst pasujący do napisu: <userinput>wzorzec</userinput> tekstem określonym w: <userinput>zastąpienie</userinput>. Jeżeli wzorzec lub zastąpienie zawiera spację, to oba argumenty należy podać w cudzysłowach (pojedynczych lub podwójnych). Jeżeli argument nie jest zamknięty w cudzysłowie, to pierwsze słowo traktowane jest jako  <userinput>wzorzec</userinput>, a reszta tekstu jako <userinput>zastąpienie</userinput>. Jeżeli tekst <userinput>zastąpienie</userinput> nie zostanie podany, to każde wystąpienie <userinput>wzorca</userinput> zostanie usunięte.</para>
<para>Parametry działania polecenia zamień mogą być dostosowywane poprzez dodanie dwukropka i jednej z dostępnych opcji. Polecenie przyjmuje wówczas postać: <userinput>replace:opcja wzorzec zastąpienie</userinput>. Dostępne są następujące opcje: <variablelist>

<varlistentry>
<term><userinput>b</userinput></term>
<listitem><para>Szuka tekstu wstecz.</para></listitem>
</varlistentry>

<varlistentry>
<term><userinput>c</userinput></term>
<listitem><para>Szuka począwszy od pozycji kursora.</para></listitem>
</varlistentry>

<varlistentry>
<term><userinput>e</userinput></term>
<listitem><para>Szuka w ramach zaznaczonego fragmentu.</para></listitem>
</varlistentry>

<varlistentry>
<term><userinput>r</userinput></term>
<listitem><para>Wykonuje polecenie szukania za pomocą wyrażenia regularnego. W przypadku użycia tej opcji, można w argumencie "zastąpienie" użyć parametru <userinput>\N</userinput>, gdzie N jest numerem podwyrażenia, które zostanie wstawione w zastępowanym tekście.</para></listitem>
</varlistentry>

<varlistentry>
<term><userinput>s</userinput></term>
<listitem><para>Szuka zwracając uwagę na wielkość liter.</para></listitem>
</varlistentry>

<varlistentry>
<term><userinput>p</userinput></term>
<listitem><para>Pyta się przed zastąpieniem kolejnego wystąpienia.</para></listitem>
</varlistentry>

<varlistentry>
<term><userinput>w</userinput></term>
<listitem><para>Szuka dopasowując tylko całe wyrazy.</para></listitem>
</varlistentry>

</variablelist>

</para>
</listitem>
</varlistentry>

<varlistentry>
<term><cmdsynopsis><command>date</command><arg>format</arg></cmdsynopsis></term>
<listitem><para>Wprowadza do dokumentu bieżący czas i datę w formacie określonym przez: <userinput>format</userinput> lub w formacie <quote>yyyy-MM-dd hh:mm:ss</quote> gdy brak jest argumentu. Interpretacja treści argumentu <userinput>format</userinput> jest następująca: <informaltable> <tgroup cols="2"> <tbody>
<row><entry><literal>d</literal></entry><entry>Dzień podany jako liczba bez wiodącego zera (1-31).</entry></row>
<row><entry><literal>dd</literal></entry><entry>Dzień podany jako liczba z wiodącym zerem (01-31).</entry></row>
<row><entry><literal>ddd</literal></entry><entry>Skrót zlokalizowanej nazwy dnia (np. 'Pon'..'Nie').</entry></row>
<row><entry><literal>dddd</literal></entry><entry>Pełna zlokalizowana nazwa dnia (np.: 'Poniedziałek'..'Niedziela').</entry></row>
<row><entry><literal>M</literal></entry><entry>Miesiąc jako liczba bez wiodącego zera (1-12).</entry></row>
<row><entry><literal>MM</literal></entry><entry>Miesiąc jako liczba z wiodącym zerem (01-12).</entry></row>
<row><entry><literal>MMM</literal></entry><entry>Skrót zlokalizowanej nazwy miesiąca (np. 'Sty'..'Gru').</entry></row>
<row><entry><literal>yy</literal></entry><entry>Rok - dwucyfrowo (00-99).</entry></row>
<row><entry><literal>yyyy</literal></entry><entry>Rok zapisany jako 4 cyfry (1752-8000).</entry></row>
<row><entry><literal>h</literal></entry><entry>Godzina, zapisana bez wiodącego zera (0..23 lub 1..12 przy wyświetlanym AM/PM).</entry></row>
<row><entry><literal>hh</literal></entry><entry>Godzina, zapisana z wiodącym zerem (00..23 lub 01..12 przy wyświetlanym AM/PM).</entry></row>
<row><entry><literal>m</literal></entry><entry>Minuta, bez wiodącego zera (0..59).</entry></row>
<row><entry><literal>mm</literal></entry><entry>Minuta z wiodącym zerem (00..59).</entry></row>
<row><entry><literal>s</literal></entry><entry>Sekunda bez wiodącego zera (0..59).</entry></row>
<row><entry><literal>ss</literal></entry><entry>Sekunda z wiodącym zerem (00..59).</entry></row>
<row><entry><literal>z</literal></entry><entry>Milisekunda bez wiodącego zera (0..999).</entry></row>
<row><entry><literal>zzz</literal></entry><entry>Milisekunda z wiodącym zerem (000..999).</entry></row>
<row><entry><literal>AP</literal></entry><entry>Wyświetla symbol "AM" lub "PM" w zależności od pory dnia.</entry></row>
<row><entry><literal>ap</literal></entry><entry>Wyświetla symbol "am" lub "pm" w zależności od pory dnia.</entry></row>

</tbody>
</tgroup>
</informaltable>

</para></listitem>
</varlistentry>

<varlistentry>
<term><cmdsynopsis><command>char</command><arg>kod_znaku</arg></cmdsynopsis></term>
<listitem>
<para>Polecenie pozwala na wstawianie do treści dokumentu znaku określonego przez wartość numeryczną w formie dziesiętnej, ósemkowej lub szesnastkowej.</para>

<example>
<title>Polecenie <command>char</command>, przykłady</title>

<para>Wpisanie: <userinput>char 234</userinput></para>
<para>Wprowadzi do tekstu znak: <computeroutput>&#234;</computeroutput></para>
<para>Wpisanie: <userinput>char 0x1234</userinput></para>
<para>Wprowadzi do tekstu znak: <computeroutput>&#x1234;</computeroutput></para>
</example>

</listitem>
</varlistentry>

<varlistentry>
<term>
<indexterm><primary>zamień, w formacie "sed"</primary>
<secondary>szukaj, w formacie "sed"</secondary></indexterm>
<command>s///[ig]</command> <command>%s///[ig]</command></term>

<listitem>
<para>To polecenie wykonuje operację znajdź/zamień analogicznie jak program "sed". Polecenie działa dla bieżącego wiersza lub dla całego dokumentu (<command>%s///</command>).</para>

<para>Działanie polecenia polega na wyszukaniu w tekście <emphasis>wzorca wyszukiwania</emphasis> (określonego przez wyrażenie regularne pomiędzy pierwszym i drugim ukośnikiem). Po znalezieniu wzorca dopasowany tekst jest zamieniany na wyrażenie zawarte pomiędzy środkową i ostatnią częścią polecenia. Nawiasy we wzorcu wyszukiwania określają tzw.<emphasis>odwołania zwrotne</emphasis>, co oznacza iż program zapamiętuje wyszukany napis, który następnie może być użyty w definicji wyrażenia zastępującego. Odwołanie do zapamiętanego napisu odbywa się przez użycie <userinput>\1</userinput> dla pierwszego zestawu nawiasów, <userinput>\2</userinput> dla drugiego i tak dalej.</para>

<para>Wyszukiwanie w tekście nawiasów <literal>(</literal> lub <literal>)</literal> wymaga zastosowania sekwencji specjalnych, z użyciem znaku odwrotnego ukośnika. Nawiasy będą reprezentowane przez napisy: <userinput>\(</userinput> oraz <userinput>\)</userinput></para>

<para>Użycie znaku <userinput>i</userinput> na końcu wyrażenia spowoduje, iż przy wyszukiwaniu nie będzie uwzględniana wielkość liter. Jeżeli na końcu wyrażenia wprowadzone zostanie <userinput>g</userinput> spowoduje to zamienienie wszystkich wystąpień poszukiwanego wzorca (w innym wypadku zamienione zostanie tylko pierwsze wystąpienie).</para>

<example>

<title>Zastępowanie tekstu w bieżącym wierszu</title>

<para>Wyobraźmy sobie komunikat kompilatora informujący o następującym błędzie w wierszu 3902 edytowanego kodu programu: Klasa: <classname>myClass</classname> nie jest zdefiniowana.</para>

<para>Zamiast przeszukiwania i edycji wiersza 3902, celem zamienienia złej nazwy klasy na poprawną (<classname>MyClass</classname>), wystarczy uruchomić linię poleceń, uruchomić polecenie <userinput>s/myclass/MyClass/i</userinput>, zapisać plik, a następnie już bez błędów skompilować program.</para>

</example>

<example>
<title>Zastępowanie tekstu w całym dokumencie</title>

<para>Wyobraźmy sobie sytuację, że w trakcie edycji dokumentu, w którym często występuje napis <quote>Pani Nowak</quote> ktoś przychodzi i mówi, iż osoba ta wyszła za mąż za pana <quote>Kowalskiego</quote>. Należy oczywiście zamienić wszystkie wystąpienia <quote>Pani Nowak</quote> na <quote>Pani Kowalska</quote>.</para>

<para>W linii poleceń wystarczy wprowadzić:<userinput>%s/Pani Nowak/Pani Kowalska/</userinput> i po naciśnięciu ENTER wszystko już będzie w porządku.</para>

</example>

<example>
<title>Przykłady zaawansowane</title>

<para>W tym przykładzie zastosowano <emphasis>odwołanie zwrotne</emphasis> oraz mechanizm <emphasis>klas znaków</emphasis> (więcej informacji na ten temat znajduje się we wspomnianej poniżej dokumentacji).</para>

<para>Dokument zawiera następujący wiersz kodu: <programlisting>void MyClass::DoStringOps( String      &amp;foo, String &amp;bar, String *p, int  &amp;a, int &amp;b )</programlisting>
</para>
<para>Konieczne jest dodanie operatora <constant>const</constant> do wszystkich argumentów określonych przez <quote>referencję</quote> (reprezentowanych przez znak &amp; na początku nazwy argumentu). Dodatkowo trzeba ujednolicić odstępy między słowami tak, aby była to tylko jedna spacja).</para>

<para>Po uruchomieniu linii poleceń, należy wpisać: <userinput>s/\s+(\w+)\s+(&amp;)/ const \1 \2/g</userinput> i nacisnąć ENTER. Znak <userinput>g</userinput> na końcu wyrażenia wymusza ponowną kompilacją wyrażenia regularnego po każdym dopasowaniu wyrażenia w tekście, co jest wymagane do poprawnego działania mechanizmu <emphasis>odwołań zwrotnych</emphasis>.</para>

<para>Po wykonaniu polecenia wiersz przyjmie postać: <computeroutput>void MyClass::DoStringOps( const String &amp;foo, const String &amp;bar, String *p, const int &amp;a, const int &amp;b )</computeroutput></para>

<para>Interpretacja opisanego wyrażenia jest następujące. Najpierw wyszukuje ono spacje (<literal>\s+</literal>) po których wystąpił jeden lub więcej znaków alfanumerycznych (<literal>\w+</literal>) zakończonych kolejną spacją (<literal>\s+</literal>), za którą znajduje się znak &amp;. Pełna treść tego dopasowania zostaje zachowana do dalszego wykorzystania przy wykonaniu zastąpienia tekstu. W drugiej części dopasowany fragment zostaje zastąpiony spacją i napisem <quote>const</quote>, po którym następuje kolejna spacja i zachowany wcześniej fragment tekstu (<literal>\1</literal>), a dalej  spacja i kolejny fragment dopasowany po znaku &amp; (<literal>\2</literal>)</para>

<para>W powyższym przykładzie pierwszy dopasowany fragment mógł zawierać napis <quote>String</quote> lub też <quote>int</quote>, dlatego też zastosowanie klasy znakowej <literal>\w</literal> i operatora <literal>+</literal> dało wymagany efekt.</para>

</example>

</listitem>

</varlistentry>

</variablelist>

</sect3>

<sect3 id="advanced-editing-tools-commandline-commands-navigation">
<title>Komendy stosowane do nawigacji w tekście</title>

<variablelist>

<varlistentry>
<term><cmdsynopsis><command>goto</command><arg>INT wiersz</arg></cmdsynopsis></term>
<listitem><para>Powoduje przejście do podanego numeru wiersza.</para></listitem>
</varlistentry>

<varlistentry>
<term><cmdsynopsis><command>find</command><arg>wzorzec</arg></cmdsynopsis></term>
<listitem><para>Spowoduje przejście do pierwszego wystąpienia napisu <userinput>wzorzec</userinput> zgodnie z bieżącą konfiguracją funkcji wyszukiwania. Kolejne wystąpienia mogą zostać wyszukane za pomocą menu <menuchoice><guimenu>Edycja</guimenu><guimenuitem>Znajdź następne</guimenuitem></menuchoice> (domyślny skrót klawiszowy to <keycap>F3</keycap>).</para>
<para>Polecenie "find" może być skonfigurowane poprzez dodanie jednej lub więcej opcji po dwukropku w postaci: <userinput>find:opcje wzorzec</userinput>. Dostępne są następujące opcje: <variablelist>

<varlistentry>
<term><userinput>b</userinput></term>
<listitem><para>Szuka tekstu wstecz.</para></listitem>
</varlistentry>

<varlistentry>
<term><userinput>c</userinput></term>
<listitem><para>Szuka począwszy od pozycji kursora.</para></listitem>
</varlistentry>

<varlistentry>
<term><userinput>e</userinput></term>
<listitem><para>Szuka w ramach zaznaczonego fragmentu.</para></listitem>
</varlistentry>

<varlistentry>
<term><userinput>r</userinput></term>
<listitem><para>Wykonuje polecenie szukania za pomocą wyrażenia regularnego. W przypadku użycia tej opcji, można w argumencie "zastąpienie" użyć parametru <userinput>\N</userinput>, gdzie N jest numerem podwyrażenia, które zostanie wstawione w zastępowanym tekście.</para></listitem>
</varlistentry>

<varlistentry>
<term><userinput>s</userinput></term>
<listitem><para>Szuka zwracając uwagę na wielkość liter.</para></listitem>
</varlistentry>

<varlistentry>
<term><userinput>w</userinput></term>
<listitem><para>Szuka dopasowując tylko całe wyrazy.</para></listitem>
</varlistentry>

</variablelist>

</para>

</listitem>

</varlistentry>

<varlistentry>
<term><cmdsynopsis><command>ifind</command><arg>wzorzec</arg></cmdsynopsis></term>
<listitem><para>Polecenie wyszukuje tekst <quote>w trakcie pisania</quote>. Dodatkowo można skonfigurować zachowanie za pomocą opcji podanych po dwukropku w postaci: <userinput>ifind:opcje wzorzec</userinput>. Dostępne są następujące opcje: <variablelist>
<varlistentry>
<term><userinput>b</userinput></term>
<listitem><para>Szuka tekstu wstecz.</para></listitem>
</varlistentry>

<varlistentry>
<term><userinput>r</userinput></term>
<listitem><para>Wyszukaj za pomocą wyrażenia regularnego.</para></listitem>
</varlistentry>

<varlistentry>
<term><userinput>s</userinput></term>
<listitem><para>Szuka zwracając uwagę na wielkość liter.</para></listitem>
</varlistentry>

<varlistentry>
<term><userinput>c</userinput></term>
<listitem><para>Szuka począwszy od pozycji kursora.</para></listitem>
</varlistentry>

</variablelist>
</para></listitem>
</varlistentry>

</variablelist>

</sect3>

</sect2>

</sect1>

<sect1 id="advanced-editing-tools-code-folding">
<title>Korzystanie ze zwijania kodu źródłowego</title>

<para>Zwijanie kodu, pozwala na ukrywanie wydzielonych części tekstu, dzięki czemu łatwiej jest przeglądać duże fragmenty edytowanego kodu źródłowego. &kate; określa możliwość zwinięcia danej części na podstawie reguł określonych w definicji podświetlania składni. Zwijanie jest dostępne tylko dla niektórych formatów dokumentów, zwykle są to pliki XML, kod źródłowy, itp. Większość definicji podświetlania, obsługujących funkcję zwijania kodu, pozwala też na ręczne definiowanie zwijalnych fragmentów tekstu, zwykle za pomocą słów kluczowych <userinput>BEGIN</userinput> oraz <userinput>END</userinput>.</para>

<para>Aby włączyć funkcję zwijania kodu, należy skorzystać z menu <menuchoice><guimenu>Widok</guimenu><guimenuitem>Pokaż znaczniki zwijania</guimenuitem></menuchoice> (jeżeli nie były one wcześniej widoczne). Pasek znaczników zwijania, widoczny po lewej stronie okna edycji menu, wyświetla graficzną reprezentację zwijalnych fragmentów kodu wraz ze znakami +/- wskazującymi na możliwe do wykonania na nim operacje. Naciśnięcie znaku "-" zwija dotyczący go fragment, zaś "+" rozwija go.</para>

<para>W menu dostępne są cztery dodatkowe polecenia pozwalające na manipulację zwiniętymi częściami tekstu, więcej informacji na ten temat dostępne jest w <link linkend="view-code-folding">dokumentacji menu</link>. </para>

<para>Jeżeli użytkownik nie chce korzystać z funkcji zwijania kodu, to może wyłączyć opcję <guilabel>Pokaż znaczniki zwijania (jeżeli dostępne)</guilabel> w karcie <link linkend="config-dialog-editor-appearance">Edytor -> Wygląd</link> w oknie konfiguracji.</para>

</sect1>

<sect1 id="advanced-editing-tools-scripting">

<title>Wykorzystanie Javascript do sterowania pracą edytora</title>

<sect2 id="advanced-editing-tools-scripting-introduction">

<title>Wprowadzenie</title>

<para>Począwszy od wersji 2.5, edytor &kate; umożliwia tworzenie skryptów w standardzie ECMA, znanym również jako JavaScript.</para>

<para>Ze skryptów można korzystać tylko za pomocą <link linkend="advanced-editing-tools-commandline">wbudowanej linii poleceń</link>. Skrypt musi być zlokalizowany w katalogu, w którym &kate; może go odszukać wraz z opcjonalnym plikiem .desktop definiującym jego dodatkowe właściwości. Domyślnym katalogiem dla skryptów jest podkatalog <filename>katepart/scripts</filename> znajdujący się w katalogu z danymi środowiska &kde;. Ścieżka dostępu do katalogu z danymi środowiska jest wyświetlana za pomocą polecenia <command>tde-config <option>--path</option> <parameter>data</parameter></command>. Zwykle podczas instalacji systemu operacyjnego tworzone są katalogi danych: systemowy i użytkownika. Skrypty umieszczone w katalogu systemowym są dostępne dla wszystkich użytkowników, zaś w katalogu użytkownika dostępne są tylko dla tego użytkownika.</para>

<note><para>Ta funkcja programu ma charakter eksperymentalny i jej działanie może się zmienić w przyszłych wersjach programu.</para>
<para>W chwili obecnej nie jest możliwe dodawanie skryptów do menu lub przypisywanie im skrótów klawiszowych. W przyszłości ta możliwość może się pojawić.</para>
<para>Nie jest jeszcze możliwe przekazywanie do uruchamianego skryptu żadnych argumentów. Ta możliwość również w przyszłości się pojawi ;)</para>
</note>

</sect2>

<sect2 id="advanced-editing-tools-scripting-reference">

<title>Interfejs programisty (API) dla JavaScript w &kate;</title>

<para>Poniżej przedstawiono pełny zestaw funkcji i właściwości dostępnych dla obiektów <type>document</type> oraz <type>view</type>. Oczywiście możliwe jest korzystanie z innych obiektów standardowych Javascript takich jak np.: <type>Math</type>, <type>String</type> <type>Regex</type>, itd.</para>

<para>Podczas działania skryptu, obiekt <classname>document</classname> odnosi się do bieżącego dokumentu, a obiekt <classname>view</classname> odnosi się do bieżącego widoku.</para>

<note><para>Typy argumentów nie są w chwili obecnej stosowane w JavaScript, przedstawione są tylko dla zilustrowania jakiego rodzaju wartości dana funkcja oczekuje.</para></note>

<variablelist id="advanced-editing-tools-scripting-global">
<title>Funkcje globalne</title>
<varlistentry>
<term><function>debug( <parameter><replaceable>string</replaceable></parameter>) [funkcja]</function></term>
<listitem>
<itemizedlist>
<title>parametry</title>
<listitem><para><parameter>string</parameter> napis do wypisania</para>
</listitem>
</itemizedlist>
<para>Przekazuje napis na standardowe wyjście <acronym>STDERR</acronym> wykorzystując funkcję <function>kdDebug()</function>. Wykorzystywany jest specjalnie przydzielony obszar do wyświetlania komunikatów, oznaczony przedrostkiem <computeroutput>Kate (KJS Scripts):</computeroutput> </para>
</listitem>
</varlistentry>
</variablelist>

<variablelist id="advanced-editing-tools-scripting-document">
<title>Charakterystyka interfejsu programisty (API) dla klasy <classname>document</classname></title>

<varlistentry>
<term><function>document.attribute( <parameter><replaceable>wiersz</replaceable> </parameter>, <parameter><replaceable>kolumna</replaceable></parameter> ); [funkcja]</function></term>
<listitem>
<itemizedlist>
<title>Parametry</title>
<listitem><para><parameter>uint wiersz</parameter> Numer wiersza, dla którego będzie wyszukiwany atrybut.</para></listitem>
<listitem><para><parameter>uint kolumna</parameter> Numer kolumny, dla której będzie poszukiwany atrybut.</para></listitem>
</itemizedlist>
<para>Zwraca kod ID atrybutu znajdującego się w określonej pozycji dokumentu [<parameter>wiersz</parameter>,<parameter>kolumna</parameter>]. Atrybut reprezentuje wygląd tekstu lub styl tekstu, i wykorzystywany jest do podświetlania składni określonego fragmentu tekstu, co jest wykorzystywane w formatach mieszanych takich jak np.: HTML lub PHP.</para>
</listitem>
</varlistentry>

<varlistentry>
<term><function>document.canBreakAt( <parameter>Char c</parameter>, <parameter>uint atrybut</parameter> ); [funkcja]</function></term>
<listitem>
<itemizedlist>
<title>Parametry</title>
<listitem><para><parameter>c</parameter> Znak do sprawdzenia</para></listitem>
<listitem><para><parameter>atrybut</parameter> Atrybut w pozycji znaku <parameter>c</parameter>.</para></listitem>
</itemizedlist>
<para>Zwraca informację, dotyczącą możliwości łamania wiersza dla znaku "c" i atrybutu "atrybut". Wynik działania funkcji zależy od reguł podświetlania, określających możliwość łamania wiersza dla danego znaku i atrybutu.</para>
</listitem>
</varlistentry>

<varlistentry>
<term><function>document.canComment( <parameter>uint atrybut_początkowy</parameter>, <parameter>uint atrybut_końcowy</parameter> ); [funkcja]</function></term>
<listitem>
<itemizedlist>
<title>Parametry</title>
<listitem><para><parameter>atrybut_początkowy</parameter> Atrybut rozpoczynający obszar określony do przekształcenia w komentarz.</para></listitem>
<listitem><para><parameter>atrybut_końcowy</parameter> Atrybut kończący obszar określony do przekształcenia w komentarz.</para></listitem>
</itemizedlist>
<para>Zwraca informację o tym, czy atrybut_początkowy i atrybut_końcowy są zgodne z bieżącymi regułami podświetlania składni. Jeżeli tak, to możliwe jest wtedy przekształcenie tego fragmentu w komentarz. </para>
<example>
<title>Wykorzystanie funkcji canComment</title>
<programlisting>if ( document.canComment( document.attribute(1,0), document.attribute(5,0) ) ) {
    // 1,0 oraz 5,0 należą do tego samego systemu reguł podświetlania składni
}
</programlisting>
</example>
</listitem>
</varlistentry>

<varlistentry>
<term><function>document.clear(); [funkcja]</function></term>
<listitem><para>Usuwa zawartość dokumentu.</para></listitem>
</varlistentry>

<varlistentry>
<term><function>document.commentStart( <parameter>uint atrybut</parameter> ); [funkcja]</function></term>
<listitem>
<itemizedlist>
<title>Parametry</title>
<listitem><para><parameter>atrybut</parameter> Atrybut tekstu, dla którego zostanie zwrócony napis rozpoczęcia komentarza.</para></listitem>
</itemizedlist>
<para>Zwraca napis wymagany do rozpoczęcia wielowierszowego komentarza dla tekstu o określonym atrybucie, lub napis pusty, jeżeli komentarze wielowierszowe nie są obsługiwane dla tego typu dokumentu.</para>
</listitem>
</varlistentry>

<varlistentry>
<term><function>document.commentMarker( <parameter>uint atrybut</parameter> ); [funkcja]</function></term>
<listitem>
<itemizedlist>
<title>Parametry</title>
<listitem><para><parameter>atrybut</parameter> Atrybut tekstu, dla którego zostanie pobrany znacznik komentarza</para></listitem>
</itemizedlist>
<para>Zwraca napis, wykorzystywany do komentowania wiersza dokumentu, lub pusty napis jeżeli komentarze dla całych wierszy nie są dostępne dla tego typu dokumentu.</para>
</listitem>
</varlistentry>

<varlistentry>
<term><function>document.commentEnd( <parameter>uint atrybut</parameter> ); [funkcja]</function></term>
<listitem>
<itemizedlist>
<title>Parametry</title>
<listitem><para><parameter>atrybut</parameter> Atrybut tekstu, dla którego zostanie zwrócony napis zakończenia komentarza</para></listitem>
</itemizedlist>
<para>Zwraca napis wymagany do zakończenia wielowierszowego komentarza dla tekstu o określonym atrybucie, lub napis pusty, jeżeli komentarze wielowierszowe nie są obsługiwane dla tego typu dokumentu.</para>
</listitem>
</varlistentry>

<varlistentry>
<term><function>document.editBegin(); [funkcja]</function></term>
<listitem>
<para>Rozpoczyna grupę operacji edycyjnych. Wszystkie działania wykonane do momentu uruchomienia funkcji editEnd() będą zgrupowane w jedną operację cofania.</para>
</listitem>
</varlistentry>

<varlistentry>
<term><function>document.editEnd(); [funkcja]</function></term>
<listitem>
<para>Kończy grupę operacji edycyjnych.</para>
</listitem>
</varlistentry>

<varlistentry>
<term><function>document.highlightMode; [właściwość:tylko do odczytu]</function></term>
<listitem>
<para>Zawiera nazwę trybu reguł podświetlania dla bieżącego dokumentu (np. "JavaScript" lub "C++"). Jeżeli dokument nie ma zdefiniowanego trybu podświetlania składni, zostanie zwrócona wartość "None". Konieczne jest korzystanie z nazwy w języku angielskim, w przypadkach gdy różni się ona od nazwy przetłumaczonej.</para>
</listitem>
</varlistentry>

<varlistentry>
<term><function>document.indentMode; [właściwość:tylko do odczytu]</function></term>
<listitem>
<para>Nazwa trybu automatycznych wcięć dla bieżącego dokumentu (np.:<literal>normal</literal> lub <literal>cstyle</literal>). Jeżeli tryb automatycznych wcięć jest wyłączony, to zwrócona zostanie wartość <literal>none</literal>. </para>
</listitem>
</varlistentry>

<varlistentry>
<term><function>document.indentWidth; [właściwość:tylko do odczytu]</function></term>
<listitem>
<para>Szerokość wcięć ustawiona dla dokumentu, wykorzystywana jeżeli włączone są wcięcia za pomocą znaku spacji.</para>
</listitem>
</varlistentry>

<varlistentry>
<term><function>document.insertLine( <parameter>uint wiersz</parameter>, <parameter>string tekst</parameter> ); [funkcja]</function></term>
<listitem>
<itemizedlist>
<title>Parametry</title>
<listitem><para><parameter>wiersz</parameter> numer wiersza dokumentu</para>
</listitem>
<listitem><para><parameter>tekst</parameter> tekst do wprowadzenia</para></listitem>
</itemizedlist>
<para>Wstawia nowy wiersz o zawartości <parameter>tekst</parameter> w wierszu o numerze <parameter>wiersz</parameter>.</para>
</listitem>
</varlistentry>

<varlistentry>
<term><function>document.insertText( <parameter>uint wiersz</parameter>, <parameter>uint kolumna</parameter>, <parameter>string tekst</parameter> ); [funkcja]</function></term>
<listitem>
<itemizedlist>
<title>Parametry</title>
<listitem><para><parameter>wiersz</parameter> numer wiersza dokumentu</para></listitem>
<listitem><para><parameter>kolumna</parameter> numer kolumny w dokumencie</para></listitem>
<listitem><para><parameter>tekst</parameter> tekst do wprowadzenia</para></listitem>
</itemizedlist>
<para>Wstawia do dokumentu <parameter>tekst</parameter> w wierszu <parameter>wiersz</parameter> i kolumnie <parameter>kolumna</parameter>.</para>
</listitem>
</varlistentry>

<varlistentry>
<term>document.length(); [funkcja]</term>
<listitem>
<para>Zwraca rozmiar dokumentu w bajtach.</para>
</listitem>
</varlistentry>

<varlistentry>
<term><function>document.lines(); [funkcja]</function></term>
<listitem>
<para>Zwraca liczbę wierszy w dokumencie.</para>
</listitem>
</varlistentry>

<varlistentry>
<term>document.mixedIndent; [właściwość:tylko do odczytu]</term>
<listitem>
<para>Wartość prawda/fałsz informująca czy tryb mieszanych wcięć dla dokumentu jest włączony. Jeżeli tak, to wcięcia są optymalizowane, tak że zawierają mieszankę znaków tabulacji i spacji (podobnie jak w edytorze Emacs).</para>
</listitem>
</varlistentry>

<varlistentry>
<term>document.removeLine( <parameter>uint wiersz</parameter> ); [funkcja]</term>
<listitem>
<itemizedlist>
<title>Parametry</title>
<listitem><para><parameter>wiersz</parameter> numer wiersza dokumentu</para></listitem>
</itemizedlist>
<para>Usuwa wiersz z dokumentu.</para>
</listitem>
</varlistentry>

<varlistentry>
<term><function>document.removeText( <parameter>uint wiersz_początku</parameter>, <parameter>uint kolumna_początku</parameter>, <parameter>uint wiersz_końca</parameter>, <parameter>uint kolumna_końca</parameter> ); [funkcja]</function></term>
<listitem>
<itemizedlist>
<title>Parametry</title>
<listitem><para><parameter>wiersz_początku</parameter> określa początkowy wiersz dokumentu</para></listitem>
<listitem><para><parameter>kolumna_początku</parameter> określa początkową kolumnę dokumentu</para></listitem>
<listitem><para><parameter>wiersz_końca</parameter> określa ostatni wiersz</para></listitem>
<listitem><para><parameter>kolumna_końca</parameter> określa ostatnią kolumnę</para></listitem>
</itemizedlist>
<para>Usuwa tekst w dokumencie od wiersza <parameter>wiersz_początku</parameter> i kolumny <parameter>kolumna_początku</parameter> do wiersza<parameter>wiersz_końca</parameter> i kolumny <parameter>kolumna_końca</parameter>. </para>
</listitem>
</varlistentry>

<varlistentry>
<term><function>document.setText( <parameter>string tekst</parameter> ); [funkcja]</function></term>
<listitem>
<itemizedlist>
<title>Parametry</title>
<listitem><para><parameter>tekst</parameter> treść dokumentu</para></listitem>
</itemizedlist>
<para>Ustawia zawartość całego dokumentu na <parameter>tekst</parameter>.</para>
</listitem>
</varlistentry>

<varlistentry>
<term><function>document.spaceIndent; [właściwość:tylko do odczytu]</function></term>
<listitem>
<para>Wartość prawda/fałsz określająca czy tryb wcinania spacjami jest włączony. Jeżeli tak, to wcięcia w dokumencie są generowane odpowiednią, zdefiniowaną przez "indentWidth", liczbą spacji. W przeciwnym wypadku, wcięcia dokonywane są za pomocą znaków tabulacji (jeden znak na jeden poziom wcięcia).</para>
</listitem>
</varlistentry>

<varlistentry>
<term><function>document.textFull(); [funkcja]</function></term>
<listitem>
<para>Zwraca pełną zawartość dokumentu. Jeżeli dokument zawiera wiele wierszy, to rozdzielane są one znakiem końca wiersza: <constant>\n</constant>.</para>
</listitem>
</varlistentry>

<varlistentry>
<term><function>document.textLine( uint wiersz ); [funkcja]</function></term>
<listitem>
<itemizedlist>
<title>Parametry</title>
<listitem><para><parameter>wiersz</parameter> numer wiersza</para></listitem>
</itemizedlist>
<para>Zwraca tekst wiersza o numerze <parameter>wiersz</parameter>.</para>
</listitem>
</varlistentry>

<varlistentry>
<term><function>document.textRange( <parameter>uint wiersz_początku</parameter>, <parameter>uint kolumna_początku</parameter>, <parameter>uint wiersz_końca</parameter>, <parameter>uint kolumna_końca</parameter> ); [funkcja]</function></term>
<listitem>
<itemizedlist>
<title>Parametry</title>
<listitem><para><parameter>wiersz_początku</parameter> określa początkowy wiersz dokumentu</para></listitem>
<listitem><para><parameter>kolumna_początku</parameter> określa początkową kolumnę dokumentu</para></listitem>
<listitem><para><parameter>wiersz_końca</parameter> określa ostatni wiersz</para>
</listitem>
<listitem><para><parameter>kolumna_końca</parameter> określa ostatnią kolumnę</para></listitem>
</itemizedlist>
<para>Zwraca zdefiniowany zakres tekstu dokumentu. Jeżeli zawiera on wiele wierszy, to rozdzielane są one znakiem końca wiersza: <constant>\n</constant>.</para>
</listitem>
</varlistentry>

</variablelist><!--/ document API -->

<variablelist id="advanced-editing-tools-scripting-view">
<title>Interfejs programisty (API) dla klasy <classname>view</classname></title>

<varlistentry>
<term><function>view.clearSelection(); [funkcja]</function></term>
<listitem>
<para>Usuwa zaznaczenie z tekstu.</para>
</listitem>
</varlistentry>

<varlistentry>
<term><function>view.cursorColumn(); [funkcja]</function></term>
<listitem>
<para>Zwraca numer kolumny, w której znajduje się kursor (znaki tabulacji są rozwijane do odpowiedniej liczby spacji).</para>
</listitem>
</varlistentry>

<varlistentry>
<term><function>view.cursorColumnReal(); [funkcja]</function></term>
<listitem>
<para>Zwraca rzeczywisty numer kolumny, w której znajduje się kursor (znaki tabulacji traktowane są jako jeden znak).</para>
</listitem>
</varlistentry>

<varlistentry>
<term><function>view.cursorLine(); [funkcja]</function></term>
<listitem>
<para>Zwraca numer wiersza, w którym znajduje się kursor.</para>
</listitem>
</varlistentry>

<varlistentry>
<term><function>view.hasSelection(); [funkcja]</function></term>
<listitem>
<para>Zwraca wartość <constant>true</constant> (logiczna prawda), jeżeli widok zawiera zaznaczenie, lub <constant>false</constant> (logiczny fałsz), gdy w widoku brak zaznaczenia.</para>
</listitem>
</varlistentry>

<varlistentry>
<term><function>view.removeSelectedText(); [funkcja]</function></term>
<listitem>
<para>Usuwa zaznaczony fragment, w przypadku gdy zaznaczenie w tekście istnieje.</para>
</listitem>
</varlistentry>

<varlistentry>
<term><function>view.selectAll(); [funkcja]</function></term>
<listitem>
<para>Zaznacza cały dokument.</para>
</listitem>
</varlistentry>

<varlistentry>
<term><function>view.selection(); [funkcja]</function></term>
<listitem>
<para>Zwraca zaznaczony fragment. Jeżeli zawiera on wiele wierszy, to rozdzielane są one znakiem końca wiersza: <constant>\n</constant>.</para>
</listitem>
</varlistentry>

<varlistentry>
<term><function>view.selectionEndColumn; [właściwość:tylko do odczytu]</function></term>
<listitem>
<para>Zwraca numer ostatniej kolumny zaznaczenia.</para>
</listitem>
</varlistentry>

<varlistentry>
<term><function>view.selectionEndLine; [właściwość:tylko do odczytu]</function></term>
<listitem>
<para>Zwraca numer ostatniego wiersza zaznaczenia.</para>
</listitem>
</varlistentry>

<varlistentry>
<term><function>view.selectionStartColumn; [właściwość:tylko do odczytu]</function></term>
<listitem>
<para>Zwraca numer pierwszej kolumny zaznaczenia.</para>
</listitem>
</varlistentry>

<varlistentry>
<term><function>view.selectionStartLine; [właściwość:tylko do odczytu]</function></term>
<listitem>
<para>Zwraca numer pierwszego wiersza zaznaczenia.</para>
</listitem>
</varlistentry>

<varlistentry>
<term><function>view.setCursorPosition( <parameter>uint wiersz</parameter>, <parameter>uint kolumna</parameter> ); [funkcja]</function></term>
<listitem>
<itemizedlist>
<title>Parametry</title>
<listitem><para><parameter>wiersz</parameter> numer wiersza pozycji kursora.</para></listitem>
<listitem><para><parameter>kolumna</parameter> numer kolumny pozycji kursora.</para></listitem>
</itemizedlist>
<para>Ustawia kursor w widoku w pozycji [<parameter>wiersz</parameter>, <parameter>kolumna</parameter>]. Pozycja zostaje ustalona wizualnie, czyli znaki tabulacji rozwijane są na odpowiednią (określoną przez <replaceable>tabwidth</replaceable>) liczbę spacji w zależności od pozycji w wierszu. Kursor staje się widoczny. Parametry wiersz i kolumna rozpoczynają się od zera.</para>
</listitem>
</varlistentry>

<varlistentry>
<term><function>view.setCursorPositionReal( <parameter>uint wiersz</parameter>, <parameter>uint kolumna</parameter> ); [funkcja]</function></term>
<listitem>
<itemizedlist>
<title>Parametry</title>
<listitem><para><parameter>wiersz</parameter> numer wiersza pozycji kursora.</para></listitem>
<listitem><para><parameter>kolumna</parameter> numer kolumny pozycji kursora.</para></listitem>
</itemizedlist>
<para>Ustawia kursora w pozycji podanej przez <parameter>wiersz</parameter> i <parameter>kolumnę</parameter>. Argumenty określają pozycję w tekście, czyli znaki tabulacji traktowane są jako jeden znak. Kursor stanie się widoczny. Numery wiersza i kolumny rozpoczynają się od zera.</para>
</listitem>
</varlistentry>

<varlistentry>
<term><function>view.setSelection( <parameter>uint wiersz_początku</parameter>, <parameter>uint kolumna_początku</parameter>, <parameter>uint wiersz_końca</parameter>, <parameter>uint kolumna_końca</parameter> ); [funkcja]</function></term>
<listitem>
<itemizedlist>
<title>Parametry</title>
<listitem><para><parameter>wiersz_początku</parameter> określa początkowy wiersz dokumentu</para></listitem>
<listitem><para><parameter>kolumna_początku</parameter> określa początkową kolumnę dokumentu</para></listitem>
<listitem><para><parameter>wiersz_końca</parameter> określa ostatni wiersz</para></listitem>
<listitem><para><parameter>kolumna_końca</parameter> określa ostatnią kolumnę</para></listitem>
</itemizedlist>
<para>Zaznacza fragment tekstu począwszy od wiersza <parameter>wiersz_początku</parameter> i kolumny <parameter>kolumna_początku</parameter> do wiersza <parameter>wiersz_końca</parameter> i kolumny <parameter>kolumna_końca</parameter>.</para>
</listitem>
</varlistentry>

</variablelist>

<example id="advanced-editing-tools-scripting-example">

<title>Przykładowy skrypt</title>
<para>Przedstawiony poniżej skrypt, przerabia wszystkie litery w zaznaczonym fragmencie na duże. Pierwszym krokiem jest sprawdzenie istnienia zaznaczenia, następnie pobranie zaznaczonego tekstu, zamienienie wielkości znaków oraz wstawienie zmienionego tekstu do dokumentu. Zapis programu wygląda następująco:</para>

<programlisting>if ( view.hasSelection() )
{
  // zmień na duże litery
  column = view.selectionStartColumn;
  line = view.selectionStartLine;

  selection = view.selection().toUpperCase();

  document.editBegin();
  view.removeSelectedText();
  document.insertText( line, column, selection );
  document.editEnd();
}
</programlisting>

<para>Zgrupowanie poleceń edycyjnych tak, aby można je było wycofać jednym poleceniem <guimenuitem>Cofnij</guimenuitem>, polega na objęciu poleceń<programlisting>view.removeSelectedText()</programlisting> i <programlisting>document.insertText()</programlisting> poleceniami <programlisting>document.editBegin()</programlisting> oraz <programlisting>document.editEnd()</programlisting>.</para>

</example>

<example id="advanced-editing-tools-desktop-example">
<title>Przykładowy plik <filename>.desktop</filename></title>

<para>Poniżej przedstawiono zawartość przykładowego pliku .desktop powiązanego z powyższym skryptem.</para>

<programlisting># Example of a .desktop file
[Desktop Entry]
Encoding=UTF-8
Name=Kate Part JavaScript Uppercase
Comment=Skrypt zamieniający treść zaznaczenia na duże litery
X-Kate-Command=uppercase-selection
X-Kate-Help=&lt;p&gt;Pomoc: &lt;code&gt;uppercase-selection&lt;/code&gt;&lt;/p&gt;
</programlisting>

<para>W pliku tym, możliwe jest zdefiniowanie kodowania znaków (Encoding), nazwy skryptu (Name), komentarza (Comment), tekstu pomocy (X-Kate-Help) i polecenia linii poleceń (X-Kate-Command). Jeżeli plik .desktop znajdzie się w repozytoriach SVN środowiska KDE, to parametry: Name, Comment i X-Kate-Help będą automatycznie tłumaczone na inne języki przez zespoły tłumaczy KDE.</para>

</example>

<sect3>
<title>Wykorzystanie skryptów</title>

<para>Program &kate; przeszuka katalogi ze skryptami (patrz <link linkend="advanced-editing-tools-scripting-introduction">wyżej</link>) w poszukiwaniu plików o nazwie <filename>*.js</filename>. Dla każdego znalezionego pliku sprawdzane jest istnienie odpowiadającego mu pliku <filename>.desktop</filename> (np. dla skryptu: uppercase.js, poszukiwany będzie plik uppercase.desktop). </para>
<para>Jeżeli plik <filename>.desktop</filename> nie zostanie znaleziony, to skrypt zostanie zarejestrowany przez linię poleceń edytora pod nazwą pliku bez rozszerzenia .js. W opisywanym przykładzie będzie to <literal>uppercase</literal>. Jeżeli taka nazwa skryptu odpowiada użytkownikowi oraz nie ma potrzeby korzystania z innych możliwości, jakie daje plik <filename>.desktop</filename>, to wtedy użycie pliku <filename>.desktop</filename> nie jest wymagane. </para>
<para>Jeżeli istnieje plik <filename>.desktop</filename>, edytor odczyta nazwę skryptu z tego pliku z pozycji X-Kate-Command, na przykład: X-Kate-Command=uppercase-selection.</para>

</sect3>

</sect2>

</sect1>

</chapter>