# Підручник з &rocs;

## Вступ

У цьому розділі наведено короткий огляд основних можливостей та прийомів роботи у &rocs;. Користувачам, які хочуть негайно перейти до навчання принципам роботи у &rocs;, ми пропонуємо перейти до читання розділу introduction-nutshell, користуючись настановами розділу scripting щодо написання алгоритмів.

### Мета, цільова аудиторія програми та процес роботи з нею

&rocs; — комплексне середовище розробки для теорії графів, призначене для всіх, хто цікавиться розробкою та аналізом алгоритмів, пов’язаних з графами. Це зокрема

- викладачі, які хочуть продемонструвати роботу алгоритмів, пов’язаних з графами, студентам,

- студенти, які бажають краще зрозуміти теорію і розібратися у роботі алгоритмів,

- та всі, хто цікавиться структурами даних та алгоритмами.

Для всіх цих користувачів у &rocs; передбачено простий у користуванні редактор графів для створення структур даних, потужний рушій обробки скриптів для виконання алгоритмів та декілька допоміжних інструментів для імітацій та експериментів.

Зазвичай, спочатку слід створити граф у візуальному редакторі графів. Ви можете зробити це або вручну, тобто додаванням вузлів та з’єднуванням цих вузлів, або за допомогою одного з автоматичних породжувачів структур даних (якщо такі визначено у модулі поточної структури даних), пункти яких можна знайти у меню Документ графу Інструменти Створити граф. Далі, ви можете пов’язати з елементами структури значення вручну або за допомогою пункту меню Документ графу Інструменти Додавання значень. Нарешті, ви можете описати власний алгоритм мовою JavaScript і виконати його для щойно створеної структури даних. Зміни, внесені до вашого алгоритму, буде негайно відтворено на панелі візуального редактора графів.

Знімок вікна &rocs;. Знімок вікна &rocs;.

### Ядро &rocs;

У цьому розділі наведено стислий огляд основних елементів &rocs;. Надано пояснення щодо важливих понять структур даних, модулів структур та типів елементів. Ці знання є корисними для покращення розуміння принципів створення структур даних та внесення до них змін у &rocs;.

Загалом, &rocs; працює з проектами: під час запуску &rocs; створюється порожній проект. Ви можете замінити цей порожній проект завантаженням або імпортуванням іншого проекту. Сам проект складається з документів графів та скрипти.

#### Модулі документів графів та структур даних

Документ графу відповідає вмісту панелі візуального редактора графів. Таким чином, документ графу може містити декілька структур даних одночасно, але використовувати лише один модуль обробки структури даних. Передбачено модулі обробки структур даних для декількох типів графів (загальні графи, лінійні списки, кореневі дерева). Модулі забезпечують доступ до додаткових функціональних можливостей певного типу графів. Серед цих можливостей автоматичне розташовування елементів графу, особливі набори піктограм або розширені набори функцій скриптів, якими можна скористатися у алгоритмах. Докладніший опис наведено у відповідному розділі підручника. Ви можете змінити модуль обробки структури даних для документа графу, але це може призвести до втрати даних (наприклад, ребра циклу загального графу не може бути додано до дерева, якщо перемкнетеся на використання модуля кореневого дерева).

Документи графів є основою визначення типів вказівників та даних.

#### Структури даних

Структури даних є основою всіх дій, які може виконувати &rocs;. Ви можете додати одну або декілька структур до документа графу, додати елементи даних (вузли, значення) та вказівники до структури. Також можна вносити зміни до структур даних за допомогою скриптів. Доступ до структур даних зі скриптів здійснюється за допомогою унікальної назви структури даних. Вибір поточного модуля обробки структури даних дещо обмежує можливість внесення змін до структур даних (наприклад, у дереві не може міститися циклів). Модуль обробки структури даних визначається на рівні документа, який містить відповідну структуру даних.

#### Типи вказівників

За допомогою типів вказівників ви можете визначити різноманітні вказівники, які використовуватимуться у структурах даних. Кожен тип вказівника має особливий формат компонування (зокрема колір). Доступ до вказівника певного типу можна легко отримати за допомогою скрипту. Типовими випадками використання вказівників може бути реалізація метаребер у ваших структурах даних, які візуалізуватимуть зв’язки між елементами даних (наприклад візуалізуватимуть зацікавленість у спілкуванні). Крім того, якщо вашим скриптам потрібно ідентифікувати ребра певного типу (наприклад, ребра та перехресті дерева у алгоритмі пошуку вглибину), типи вказівників можуть бути чудовим способом реалізації ідентифікації.

#### Типи даних

У декількох задачах обробки структур даних набір елементів даних має бути поділено на групи різних типів (наприклад, у задачах з кластеризації та покриття). Типи можуть бути корисними для виконання алгоритмів, у яких для визначення певного типу використовується тип елемента структури даних (наприклад, у алгоритмі пошуку у ширину). Якщо вам потрібно саме це, скористайтеся визначенням типів даних. Кожному типу даних відповідає власна піктограма. Доступ до певних типів даних можна зовсім просто здійснювати зі скриптів.

#### Динамічні властивості

Кожен елемент даних і кожен вказівник можуть мати довільну кількість властивостей. Деякі з цих властивостей є типовим і визначаються модулем структур даних. Докладніше про ці властивості можна дізнатися з документації до модуля структур даних. Додаткові властивості до елементів даних і вказівників можна додати за допомогою динамічних властивостей. Кожна динамічна властивість визначається назвою і може містити пов’язане з нею значення. Назва має починатися з літери латинки (a-z або A-Z) і може складатися лише з літер, цифр і символів «_». Якщо ви спробуєте використати у назві властивості некоректний символ, властивість не буде додано.

Додати динамічну властивість можна за допомогою діалогових вікон Властивості елемента даних та Властивості вказівника, доступ до яких здійснюється за допомогою контекстних меню відповідних елементів, або функцій скриптів, описаних у розділі scripting-data-structure.

Крім того, ви можете використовувати скрипти. Вам достатньо скористатися кодом `add_property` з назвою і значенням потрібної вам властивості. Після цього ви зможете скористатися node/pointer.назваВластивості для встановлення або отримання її значень.

Нижче наведено приклад використання динамічних властивостей за допомогою модуля структури даних «Граф».

    nodes = myGraph.list_nodes()
    for (var i = 0; i < nodes.length; ++i ){
        nodes[i].add_property("MyProperty", 0)
    }
    nodes[0].MyProperty = 2
    nodes[1].MyProperty = nodes[0].MyProperty + 2

### Покрокові настанови

У цьому розділі наведено опис прикладу проекту з метою ознайомлення з деякими найважливішими функціональними можливостями &rocs;. Метою є створення графу і скрипту, за допомогою яких може бути проілюстровано простий алгоритм «наближеного» розв’язання для задачі мінімального вершинного покриття. Задача мінімального вершинного покриття полягає у відшуканні підмножини вузлів графу, C, мінімального розміру, такої, що кожне ребро графу з’єднано принаймні з одним вузлом у C. Відомо, що ця задача є NP-повною. Ми намагатимемося проілюструвати спосіб відшукання наближення, кількість вузлів у якому не буде перевищувати подвоєну кількість вузлів у мінімальному покритті, за допомогою пошуку відповідностей у вказаному графі (надалі використовуватимемо загальні терміни алгоритмів для графів: граф називатимемо структурою даних, вузли — елементами даних, ребра — вказівниками).

Нашою метою буде візуалізації зв’язку між відповідностями і мінімальним вершинним покриттям. Для цього ми визначимо два типи вказівників: один для показу відповідних ребер і ще один для показу звичайних ребер; а також два типи даних, за допомогою яких відрізнятимемо вузли, що належать до C, і вузли, що не належать до C.

#### Створення графу

У модулі структури даних &rocs; передбачено допоміжний інструмент для створення графів. Викликати його можна за допомогою пункту меню Документ графу Інструменти Створення графу. Створимо «Випадковий граф» з 30 вузлами, 90 ребрами та породжувачем 1 (породжувач впливає на послідовність псевдовипадкових чисел, на основі якої створюється граф; використання одного породжувача декілька разів призведе до повторного створення тих самих графів). Крім того, внесемо зміни до назви графу за допомогою панелі структури даних: назвемо граф `testgraph`.

#### Створення типів

Скористаємося кнопкою Властивості документа на панелі структури даних для відкриття діалогового вікна властивостей для типів даних і вказівників поточного документа графу. Додамо новий тип даних з назвою «C». Цей тип даних автоматично отримає ідентифікатор `1`. Виберемо для цього типу даних піктограму із зображенням сервера. Далі, перемкнемося на сторінку типів вказівників і додамо новий тип вказівника з назвою «matching» (відповідність). Цей тип автоматично отримає ідентифікатор `1`. Визначимо для нього синій колір.

#### Алгоритм

Нарешті, нам слід реалізувати алгоритм апроксимації. Для цього ми скористаємося таким кодом:

    var E = testgraph.list_edges(); // набір необроблених ребер
    var C = new Array();            // відповідні ребра
    while (E.length
    > 0) {
        var e = E[0];        // беремо перше ребро e={u,v}
        var u = e.start();
        var v = e.end();
        e.set_type(1);        // зробити ребро відповідним ребром
        E.shift();            // вилучити e (тобто E[0]) зі списку ребер
        C.push(u);            // додати u до C
        C.push(v);            // додати v до C

        // позначити u,v як вузли у C
        u.set_type(1);
        v.set_type(1);

        // вилучити з E всі ребра з кінцями в u або v
        var adjacent = u.adj_edges();
        for (var i=0; i < adjacent.length; i++) {
            var index = E.indexOf(adjacent[i]); // визначити індекс
            if (index!=-1) {
                E.splice(index, 1); // вилучити його, якщо знайдено
            }
        }
        var adjacent = v.adj_edges();
        for (var i=0; i < adjacent.length; i++) {
            var index = E.indexOf(adjacent[i]); // визначити індекс
            if (index!=-1) {
                E.splice(index, 1); // вилучити його, якщо знайдено
            }
        }
    }
    Console.log("Покриття вершин містить " + C.length + " вузлів.");

#### Виконання алгоритму

Нарешті, алгоритм слід виконати. Для цього ми розпочнемо його виконання натисканням кнопки Виконати на панелі керування скриптами.

## Інтерфейс користувача &rocs;

### Загальні елементи інтерфейсу користувача

Інтерфейс користувача програми поділено на декілька логічних частин, як це показано на наведеному нижче знімку.

Елементи графічного інтерфейсу &rocs;. Елементи графічного інтерфейсу &rocs;.

Вибір документа

- За допомогою розташованої у верхній частині вікна панелі меню ви можете вибрати поточний документ і структуру даних. Також за її допомогою можна створювати і вилучати структури даних та отримувати доступ до властивостей структур даних.

Візуальний редактор графів

- Це панель, на якій можна створювати і вносити зміни до структур даних. Відкрити контекстні меню панелі, елементів даних та вказівників можна за допомогою клацання правою кнопкою миші. Ви можете скористатися інструментами панелі візуального редактора графів для внесення змін до елементів панелі візуального редактора графів.

Панель візуального редактора графів

- На цій панелі передбачено всі інструмент для візуального редагування графів. За допомогою кнопок Додати елемент і Додати з’єднання ви можете створювати нові елементи або з’єднувати елементи, відповідно. Нові елементи даних додаватимуться до структури даних, яку позначено за допомогою панелі вибору документа. Зауважте, що для інструментів Додати елемент і Додати з’єднання передбачено меню для вибору типу нових створених елементів. Докладніше про це можна дізнатися з розділу user-interface-toolbars.

Бічна панель

- Праворуч розташовано бічну панель, за допомогою якої можна отримати доступ до декількох робочих інструментів:

  - Типи елементів: за допомогою цього віджета можна отримати безпосередній доступ до доступних типів вказівників і даних.

  - Журнал: у кожного з проектів є власний журнал, яким можна скористатися, наприклад, для занотовування завдань, результатів та спостережень.

  - Підручник: за допомогою цього віджета можна отримати безпосередній доступ до підручника та документації зі скриптів.

  - Програмний інтерфейс для роботи зі скриптами: за допомогою цього віджета можна отримати безпосередній доступ до документації зі скриптів.

Редактор скриптів

- У полі цього текстового редактора ви можете створювати скрипти алгоритмів у спосіб, описаний у розділі scripting. Ви можете працювати одночасно над декількома алгоритмами: для цього достатньо відкрити або створити декілька вкладок скриптів за допомогою головного меню програми. Якщо зміни, внесені на якійсь із вкладок це не збережено, програма показуватиме невеличкий символ диска на заголовку цієї вкладки.

Виведене скриптом

- До цього поля програма виводитиме діагностичні повідомлення або дані, виведені скриптом, залежно від перемикача у верхній частині цього віджета. Якщо під час виконання скрипту станеться помилка, програма негайно перемкнеться у режим діагностичних повідомлень.

Керування

- На цій панелі розташовано елементи керування виконанням скриптів. Ви можете наказати програмі виконати скрипт, відкритий у редакторів скриптів, натисканням кнопки Пуск. Якщо виконання скрипту ще не завершено, його можна зупинити натисканням кнопки Стоп. Зауважте, що у відповідь на натискання кнопки Один крок програма виконає скрипт до певного наступного ключового слова (див. розділ scripting).

### Панелі інструментів

На панелі візуального редактора графів передбачено декілька панелей інструментів, за допомогою яких ви зможете отримувати доступ до можливостей програми у одне клацання кнопкою миші. За типових налаштувань буде показано такі панелі інструментів:

- Головна панель інструментів

- Панель інструментів вирівнювання

#### Головна панель інструментів

На головній панелі інструментів буде показано вказані нижче кнопки дій. Натискання кнопки дії, означатиме, що вказівник миші виконуватиме відповідну дію на панелі візуального редактора графів:

- Пересунути: щоб позначити елементи, натисніть ліву кнопку миші на порожньому місці на графі, утримуйте кнопку натисненою і рухом вказівника миші створіть прямокутник, у якому міститимуться елементи даних та/або вказівники. Якщо треба позначити окремий елемент, просто клацніть лівою кнопкою миші на цьому елементі. Якщо ви наведете вказівник миші на позначений елемент або набір елементів, натиснете і утримуватимете натисненою ліву кнопку миші, а потім почнете рухати вказівник, разом з ним почнуть рухатися позначені елементи. Пересунути позначені елементи можна також за допомогою клавіш зі стрілочками.

- Додати елемент: клацніть у довільній точці панелі візуального редактора, щоб створити новий вузол, який належатиме поточній позначеній структурі даних. Якщо ви продовжите утримувати кнопку миші, програма покаже контекстне меню, за допомогою якого ви зможете вибрати тип даних нового елемента (якщо передбачено різні типи даних елементів).

- Додати з’єднання: наведіть вказівник миші на позицію першого вузла, натисніть і утримуйте натисненою ліву кнопку миші, перетягніть вказівник до позиції другого вузла, до якого має прямувати вказівник/ребро. Виконати цю дію можна буде, лише якщо у поточному графі можливе додавання такого ребра (наприклад, у незорієнтованому графі не можна додавати декілька ребер між двома вузлами). Якщо ви утримуватимете натисненою кнопку миші і далі, програма покаже меню, за допомогою якого можна буде вибрати тип вказівника (якщо типи вказівників передбачено поточним типом графу).

- Вилучити: клацніть на елементі графу, щоб його вилучити. Якщо ви вилучите вузол, всі ребра, які з ним з’єднано, також буде вилучено.

- Масштаб: наведіть вказівник на панель візуального редактора, натисніть і утримуйте натисненою ліву кнопку миші, перетягніть вказівник так, щоб у отриманому прямокутнику містилися всі потрібні вам елементи, відпустіть кнопку миші. Панель візуального редактора буде масштабовано відповідно до вказаного вами прямокутника. Збільшити або зменшити масштаб можна за допомогою прокручування коліщатка миші. Подвійне клацання лівою кнопкою миші відновлює початковий масштаб.

#### Панель інструментів вирівнювання

Крім того, ви можете додати відкрити додаткову панель вирівнювання. Натискання кнопки дії на цій панелі призведе до негайного виконання дії над поточними позначеними вузлами.

- Вгору: вирівняти елементи даних за вертикальною позицією найвищого з них. Змінено буде лише вертикальні координати.

- Центр: вирівняти елементи даних за вертикальною позицією середнього значення вертикальних координат всіх позначених елементів даних. Змінено буде лише вертикальні координати.

- Основа: вирівняти елементи даних за вертикальною позицією найнижчого з них. Змінено буде лише вертикальні координати.

- Ліворуч: вирівняти вузли на горизонтальною позицією найлівішого елемента даних. Змінено буде лише горизонтальні координати.

- Центр: вирівняти вузли на горизонтальною позицією найвищого елемента даних. Змінено буде лише горизонтальні координати.

- Праворуч: вирівняти вузли на горизонтальною позицією найправішого елемента даних. Змінено буде лише горизонтальні координати.

- Коло: розташувати елементи даних на колі з діаметром, рівним максимальній відстані між елементами даних. Елементи даних на колі буде розташовано у такому самому порядку, у якому їх видно з центра мас елементів даних.

- Мінімізувати кількість перетинів ребер: застосувати алгоритм Фругтермана-Рейнґольда для мінімізації (наближено) кількості з’єднань, що перетинаються.

### Робота з документами графів

Проект &rocs; складається з одного або декількох документів графів, які можна редагувати за допомогою візуального редактора графів. Далі, кожен документ може складатися з довільної кількості структур даних. Для всіх структур даних певного документа використовується один модуль обробки структур даних. За допомогою цього розділу документації ви зможете довідатися, як перемикатися між документами та як створювати нові документи.

#### Панель вибору документа

За допомогою панелі вибору документів можна вибрати поточний документ графу і поточну структуру даних у ньому. Якщо ви скористаєтеся інструментами візуального редактора графів для створення елементів структур даних, ці елементи буде автоматично додано до новостворених елементів поточної структури даних. Крім того, за допомогою цієї панелі можна отримати безпосередній доступ до вилучення вже створених та створення нових структур даних у межах поточного документа.

- Створити: за допомогою цього пункту дії можна створити нову структуру даних з використанням автоматичного шаблона найменування, що визначається модулем структури даних. Створену структуру даних буде додано до поточного позначеного документа графу.

- Вилучити: за допомогою цієї дії можна вилучити структуру даних, яку позначено панелі структур даних поточного документа.

- Властивості для Документа графу: відкрити діалогове вікно доступу до властивостей документа та переліку типів даних та вказівників документа.

- Властивості для Структури даних: відкрити діалогове вікно доступу до властивостей структури даних.

Головна панель інструментів. Панель вибору документа.

#### Створення та імпортування документів графів

Щоб створити новий документ графу або додати вже створений документ до проекту, скористайтеся пунктами меню Файл Створити проект та Документ графу Імпортувати граф. Крім того, ви можете імпортувати документи графів зі сторонніх програм (докладніше про це можна дізнатися з розділу import-export).

## Написання та виконання алгоритмів у &rocs;

У &rocs; використовується рушій обробки скриптів QtScript, який працює з одним з діалектів JavaScript. Це означає, що всі алгоритми, які ви створюватимете, має бути написано мовою JavaScript. У цьому підручнику немає опису принципів роботи та способів написання скриптів JavaScript, хоча тут ви знайдете опис способів доступу до структур даних, елементів даних та вказівників ваших структур даних за допомогою рушія обробки скриптів. Оскільки ви не використовуватимете об’єкт основної структури даних напряму, працюючи з об’єктом, що надається поточним використаним модулем структури даних, функціональні можливості структури даних розширюються відповідним модулем, отже вам слід ознайомитися з відповідними функціональними можливостями. Зокрема, у модулях структур даних використовуються загальні терміни теорії (вузли (nodes) та ребра (edges) у графах, листя (leafs) і корені (roots) у деревах тощо).

Важливо розуміти, що зміни, внесені рушієм для обробки скриптів, безпосередньо відтворюються у властивостях панелі візуального редактора графів. Отже, скрипти безпосередньо змінюють структури даних.

### Керування виконанням скриптів

#### Включення файлів

Ваші документи скриптів можуть включати інші скрипти. Така можливість може бути корисною для зменшення розмірів документів скриптів та полегшення читання скриптів. За допомогою пункту меню Документ скрипту Можливі включення ви можете отримати список файлів скриптів, вже включених до пакунка &rocs;, якими ви можете скористатися. Включити файл скрипту можна такою командою:

    include_script(string path);            // відносний або абсолютний шлях до файла скрипту

#### Дані, виведені скриптами

Під час виконання алгоритму діагностичні повідомлення та повідомлення, виведені програмою, буде показано на панелі Вивід повідомлень. Якщо рушієм обробки скриптів буде виявлено синтаксичну помилку у вашому скрипті, відповідне повідомлення також буде показано серед діагностичних повідомлень. Зауважте, що всі повідомлення, виведені програмою, також буде показано і у списку діагностичних повідомлень (напівжирним шрифтом).

Керувати текстом, який буде виведено скриптом, можна за допомогою таких функцій:

    Console.log(string message);            // показати повідомлення як виведене скриптом
    Console.debug(string message);          // показати повідомлення як діагностичне

#### Керування виконанням скриптів

Передбачено різні режими виконання ваших скриптів.

Керувати текстом, який буде виведено скриптом, можна за допомогою таких функцій:

- Виконати: виконати скрипт, аж до завершення його роботи.

- Один крок: виконати скрипт до завершення одного кроку. Крок завершується, коли скриптом викликається функція `interrupt()`:

      interrupt();    // завершує крок

- Діагностика: виконати скрипт у режимі діагностики. Програма відкриє діалогове вікно діагностики QtScript.

- Стоп: припинити виконання скрипту (доступне, лише якщо виконується скрипт).

## Інтерфейс (API) роботи зі скриптами

Кожен модуль надає доступ до особливого набору функцій та властивостей для структури даних та її елементів. Крім того, кожен модуль надає доступ до властивостей та функцій, які визначаються для основної структури даних.

&apiDatastructure; &apiGraphstructure; &apiLinkedListstructure; &apiRootedTreestructure; &apiConsole;
&chapterImportExport;

## Подяки і ліцензія

&rocs;

Авторські права на програму:

- Авторські права на програму належать Ugo Sangiori (ugorox AT gmail.com), 2008

- Авторські права на програму належать Tomaz Canabrava (tcanabrava AT kde.org), 2008–2012

- Авторські права на програму належать Wagner Reck (wagner.reck AT gmail.com), 2008–2012

- Авторські права на програму належать Andreas Cord-Landwehr (cordlandwehr AT kde.org), 2011–2013

Авторські права на документацію:

- Авторські права на документацію належать &Anne-Marie.Mahfouf; &Anne-Marie.Mahfouf.mail;, 2009

- Авторські права на документацію належать Tomaz Canabrava tcanabrava at kde dot org, 2009

- Авторські права на документацію належать Andreas Cord-Landwehr (cordlandwehr AT kde.org), 2011–2013

Переклад українською: Юрій Чорноіван yurchor@ukr.net

&underFDL; &underGPL;

## Встановлення

### Як отримати &rocs;

&install.intro.documentation;

### Збирання і встановлення

&install.compile.documentation;
&documentation.index;