This shows you the differences between two versions of the page.
Both sides previous revision Previous revision | |||
geda:devel-tips.ru [2013/01/28 00:02] vzh Add a link |
geda:devel-tips.ru [2014/04/26 06:33] (current) vzh Updated using po4a |
||
---|---|---|---|
Line 1: | Line 1: | ||
+ | //Эта страница доступна также на следующих языках:// [[devel-tips|English]] | ||
+ | |||
====== Советы, подсказки и хитрости для разработчиков gEDA ====== | ====== Советы, подсказки и хитрости для разработчиков gEDA ====== | ||
Line 5: | Line 7: | ||
Внутри gaf схема представляется набором | Внутри gaf схема представляется набором | ||
[[http://ru.wikipedia.org/wiki/Связный_список|двусвязных списков]]. | [[http://ru.wikipedia.org/wiki/Связный_список|двусвязных списков]]. | ||
- | Центральным типом связи в списках является OBJECT. Он может быть представлением | + | Центральным типом связи в списках является OBJECT. Он может быть |
- | какого-нибудь символа, строки текста, графического примитива, соединения или | + | представлением какого-нибудь символа, строки текста, графического примитива, |
- | атрибута. | + | соединения или атрибута. |
Обзор структуры данных схемы можно найти | Обзор структуры данных схемы можно найти | ||
[[http://www.brorson.com/gEDA/gEDA_Structures_20050108.pdf|здесь]]. Этот | [[http://www.brorson.com/gEDA/gEDA_Structures_20050108.pdf|здесь]]. Этот | ||
набросок сделан Стюартом Брорсоном (Stuart Brorson) в 2005 году. | набросок сделан Стюартом Брорсоном (Stuart Brorson) в 2005 году. | ||
+ | |||
+ | |||
Line 18: | Line 22: | ||
===== Комментарии и стили Doxygen ===== | ===== Комментарии и стили Doxygen ===== | ||
- | **Doxygen** представляет собой утилиту для извлечения документации по API из | + | **Doxygen** представляет собой утилиту для извлечения документации по API из комментариев в исходном коде. В комментариях может указываться разметка, которая впоследствии может быть преобразована программой Doxygen в код HTML или LaTeX. Это позволяет, к примеру, одной функции сослаться на другую, связанную с ней, а также даёт возможность приводить документацию об аргументах и возвращаемых значениях. |
- | комментариев в исходном коде. В комментариях может указываться разметка, | + | |
- | которая впоследствии может быть преобразована программой Doxygen в код HTML или | + | |
- | LaTeX. Это позволяет, к примеру, одной функции сослаться на другую, связанную | + | |
- | с ней, а также даёт возможность приводить документацию об аргументах и возвращаемых | + | |
- | значениях. | + | |
Некоторые части исходных текстов gaf уже подготовлены для работы с | Некоторые части исходных текстов gaf уже подготовлены для работы с | ||
- | **doxygen**. Сейчас сюда входят libgeda, gschem, gnetlist, gsymcheck и gattrib. | + | **doxygen**. Сейчас сюда входят libgeda, gschem, gnetlist, gsymcheck и |
- | Файлы Makefile этих утилит в каталоге //''docs''// содержат цель "doxygen". | + | gattrib. Файлы Makefile этих утилит в каталоге //''docs''// содержат цель |
- | Или же вывод doxygen можно посмотреть | + | «doxygen». Или же вывод doxygen можно посмотреть |
- | [[http://www.xs4all.nl/~ljh4timm/gaf/dox.html|на этой странице]], подготовленной | + | [[http://www.xs4all.nl/~ljh4timm/gaf/dox.html|на этой странице]], |
- | Бертом Тиммерманом (Bert Timmerman). | + | подготовленной Бертом Тиммерманом (Bert Timmerman). |
Если вы хотите узнать заложенные в Doxygen идеи о том, как надо | Если вы хотите узнать заложенные в Doxygen идеи о том, как надо | ||
Line 36: | Line 35: | ||
[[http://www.stack.nl/~dimitri/doxygen/docblocks.html|веб-сайт Doxygen]]. | [[http://www.stack.nl/~dimitri/doxygen/docblocks.html|веб-сайт Doxygen]]. | ||
Отдельные команды документированы | Отдельные команды документированы | ||
- | [[http://www.stack.nl/~dimitri/doxygen/commands.html|здесь]]. По | + | [[http://www.stack.nl/~dimitri/doxygen/commands.html|здесь]]. По Doxygen |
- | Doxygen есть также несколько очень удобных | + | есть также несколько очень удобных |
- | [[http://www.digilife.be/quickreferences/QRC/Doxygen%20Quick%20Reference.pdf|кратких | + | [[http://www.digilife.be/quickreferences/QRC/Doxygen Quick |
- | справочных страниц]]. | + | Reference.pdf|кратких справочных страниц]]. |
В следующих разделах предлагается вводная информация о том, как обычно | В следующих разделах предлагается вводная информация о том, как обычно | ||
- | документируются gschem и libgeda. Обратите внимание, что для | + | документируются gschem и libgeda. Обратите внимание, что для комментариев, |
- | комментариев, разрешённых в Doxygen, предпочтительным является стиль | + | разрешённых в Doxygen, предпочтительным является стиль QT вида **%%/*! здесь |
- | QT вида **%%/*! здесь идут комментарии */%%**. | + | идут комментарии */%%**. |
==== Документирование файлов ==== | ==== Документирование файлов ==== | ||
- | При создании нового файла в нём, очевидно, должен быть обычный текст | + | При создании нового файла в нём, очевидно, должен быть обычный текст лицензии GNU. После лицензии нужно включить комментарий о файле с описанием того, для чего этот файл, и с любым другим текстом, относящимся ко всему файлу как целому((Здесь и далее в коде всё конечно же должно быть по-английски. --- //Прим. перев.// )). |
- | лицензии GNU. После лицензии нужно включить комментарий о файле с | + | |
- | описанием того, для чего этот файл, и с любым другим текстом, | + | |
- | относящимся ко всему файлу как целому((Здесь и далее в коде всё | + | |
- | конечно же должно быть по-английски. --- //Прим. перев.// )). | + | |
<code c> | <code c> | ||
/*! \file <filename.ext> | /*! \file <filename.ext> | ||
Line 63: | Line 58: | ||
==== Документирование переменных/определений/описаний типов ==== | ==== Документирование переменных/определений/описаний типов ==== | ||
- | Глобальные переменные в файле можно документировать с помощью команды **\var** | + | Глобальные переменные в файле можно документировать с помощью команды |
- | или просто написав комментарий с помощью команды **\brief** прямо перед | + | **\var** или просто написав комментарий с помощью команды **\brief** прямо |
- | определением. | + | перед определением. |
<code c> | <code c> | ||
Line 75: | Line 70: | ||
Функции можно документировать точно так же, как и переменные и т. д. | Функции можно документировать точно так же, как и переменные и т. д. | ||
- | Достаточно вставить блок комментария выше документируемой им функции | + | Достаточно вставить блок комментария выше документируемой им функции и |
- | и начать его командой **\brief**. | + | начать его командой **\brief**. |
Обычно для длинного описания назначения функции используется дополнительный | Обычно для длинного описания назначения функции используется дополнительный | ||
- | параграф **Function Description**. | + | параграф **Function Description**. Также, для определения того, будут ли |
- | Также, для определения того, будут ли параметры функции изменяться в | + | параметры функции изменяться в ней самой, в командах **\param** используются |
- | ней самой, в командах **\param** используются атрибуты [in] или [out]. | + | атрибуты [in] или [out]. |
<code c> | <code c> | ||
Line 98: | Line 93: | ||
Структуры документируются так же, как указано в предыдущих разделах. | Структуры документируются так же, как указано в предыдущих разделах. | ||
- | Учтите, что комментарии для членов структур могут как быть встроенными | + | Учтите, что комментарии для членов структур могут как быть встроенными в их |
- | в их собственные строки, так и указываться с помощью того же | + | собственные строки, так и указываться с помощью того же синтаксиса |
- | синтаксиса **\brief**, что и для переменных. Для встраивания | + | **\brief**, что и для переменных. Для встраивания документации в строку в её |
- | документации в строку в её конце должен помещаться комментарий особого | + | конце должен помещаться комментарий особого вида, начинающийся с |
- | вида, начинающийся с **%%/*!<%%**. | + | **%%/*!<%%**. |
<code c> | <code c> | ||
Line 123: | Line 118: | ||
</code> | </code> | ||
- | ==== Команды Bug/Todo ==== | ||
- | **\bug** и **\todo** полезны для отметки мест с недостатками или | ||
- | отсутствующими возможностями в коде. Эти команды могут быть вставлены | ||
- | в любое место внутри комментариев Doxygen, и служат они для создания | ||
- | записей на специальных страницах в документации, позволяющих легко | ||
- | найти соответствующее место. | ||
+ | ==== Команды Bug/Todo ==== | ||
+ | |||
+ | **\bug** и **\todo** полезны для отметки мест с недостатками или отсутствующими возможностями в коде. Эти команды могут быть вставлены в любое место внутри комментариев Doxygen, и служат они для создания записей на специальных страницах в документации, позволяющих легко найти соответствующее место. | ||
===== Диалоговые окна: дизайн и поведение ===== | ===== Диалоговые окна: дизайн и поведение ===== | ||
+ | |||
+ | |||
==== Создание диалоговых окон ==== | ==== Создание диалоговых окон ==== | ||
Есть прекрасный документ от ребят из gnome под названием | Есть прекрасный документ от ребят из gnome под названием | ||
- | [[http://library.gnome.org/devel/hig-book/ | Gnome HIG]]. | + | [[http://library.gnome.org/devel/hig-book/ | Gnome HIG]]. Насчёт дизайна |
- | Насчёт дизайна диалоговых окон и насчёт того, как они должны себя вести, | + | диалоговых окон и насчёт того, как они должны себя вести, предложений |
- | предложений несколько. | + | несколько. |
**Дизайн диалоговых окон --- это, в общем-то, дело вкуса:** | **Дизайн диалоговых окон --- это, в общем-то, дело вкуса:** | ||
Line 150: | Line 144: | ||
==== Модальные и немодальные диалоговые окна ==== | ==== Модальные и немодальные диалоговые окна ==== | ||
- | Модальное окно диалога требуется во всех тех случаях, когда данные для | + | Модальное окно диалога требуется во всех тех случаях, когда данные для окна |
- | окна обеспечиваются основным приложением. | + | обеспечиваются основным приложением. |
Пример: | Пример: | ||
Line 157: | Line 151: | ||
с данными этого списка. | с данными этого списка. | ||
- | Модальное окно подходит также тогда, когда диалог вызывается очень | + | Модальное окно подходит также тогда, когда диалог вызывается очень редко. |
- | редко. Диалоговое окно открытия файла могло бы быть немодальным, так | + | Диалоговое окно открытия файла могло бы быть немодальным, так как для него |
- | как для него не требуется ввод никаких данных из приложения. | + | не требуется ввод никаких данных из приложения. |
- | Модальное окно не подходит, если пользователь много | + | Модальное окно не подходит, если пользователь много взаимодействует с этим |
- | взаимодействует с этим окном. Хороший пример --- выбор компонентов. | + | окном. Хороший пример --- выбор компонентов. |
==== Где размещать диалоговое окно ==== | ==== Где размещать диалоговое окно ==== | ||
- | Диалоговое окно можно поместить в различные места экрана. | + | Диалоговое окно можно поместить в различные места экрана. Список возможных |
- | Список возможных мест можно найти в | + | мест можно найти в |
- | [[http://library.gnome.org/devel/gtk/unstable/gtk3-Standard-Enumerations.html#GtkWindowPosition | GtkReference]] | + | [[http://library.gnome.org/devel/gtk/unstable/gtk3-Standard-Enumerations.html#GtkWindowPosition |
+ | | GtkReference]] | ||
- | В настоящее время диалоги помещаются или в позиции мыши (GTK_WIN_POS_MOUSE) или ни в какой предустановленной позиции (GTK_WIN_POS_NONE). | + | В настоящее время диалоги помещаются или в позиции мыши (GTK_WIN_POS_MOUSE) |
- | В Gnome HID по этой теме ничего не сказано. | + | или ни в какой предустановленной позиции (GTK_WIN_POS_NONE). В Gnome HID по |
+ | этой теме ничего не сказано. | ||
Настройкой по умолчанию для GtkWindow является GTK_WIN_POS_NONE, см. [[ | Настройкой по умолчанию для GtkWindow является GTK_WIN_POS_NONE, см. [[ | ||
http://developer.gnome.org/doc/API/2.0/gtk/GtkWindow.html#GtkWindow--window-position | http://developer.gnome.org/doc/API/2.0/gtk/GtkWindow.html#GtkWindow--window-position | ||
- | | GtkWindow]]. | + | | GtkWindow]]. Настройкой по умолчанию для GtkDialog является |
- | Настройкой по умолчанию для GtkDialog является GTK_WIN_POS_CENTER_ON_PARENT | + | GTK_WIN_POS_CENTER_ON_PARENT |
([[http://git.gnome.org/browse/gtk+/tree/gtk/gtkdialog.c | taken from the | ([[http://git.gnome.org/browse/gtk+/tree/gtk/gtkdialog.c | taken from the | ||
GtkDialog source]]). | GtkDialog source]]). | ||
==== Помещение диалоговых окон перед их родительскими окнами ==== | ==== Помещение диалоговых окон перед их родительскими окнами ==== | ||
- | Большинство диалоговых окон размещается перед их родительскими окнами с помощью | + | Большинство диалоговых окон размещается перед их родительскими окнами с |
- | свойства transient_for (см. | + | помощью свойства transient_for (см. |
[[http://developer.gnome.org/doc/API/2.0/gtk/GtkWindow.html#gtk-window-set-transient-for | [[http://developer.gnome.org/doc/API/2.0/gtk/GtkWindow.html#gtk-window-set-transient-for | ||
| GtkReference]]). Это свойство должно быть установлено для всех модальных | | GtkReference]]). Это свойство должно быть установлено для всех модальных | ||
Line 188: | Line 184: | ||
Для немодальных диалоговых окон установка свойства transient_for не | Для немодальных диалоговых окон установка свойства transient_for не | ||
- | очевидна. В то время как, например, в gschem диалоговое окно координат должно | + | очевидна. В то время как, например, в gschem диалоговое окно координат |
- | находиться над родительским окном, окно журнала вешать перед ним нужды нет. | + | должно находиться над родительским окном, окно журнала вешать перед ним |
+ | нужды нет. | ||
- | **Примечание:** Существует более старый механизм, удерживающий эти | + | **Примечание:** Существует более старый механизм, удерживающий эти окна перед gschem. Если переменная //raise-dialog-boxes-on-expose// устанавливается в //enabled// в одном из файлов настроек gschem, она может вызвать проблемы с некоторыми оконными менеджерами. |
- | окна перед gschem. Если переменная //raise-dialog-boxes-on-expose// | + | Если диалоговые окна мерцают при 100%-ной загрузке CPU, запретите эту настройку. |
- | устанавливается в //enabled// в одном из файлов настроек gschem, она может | + | |
- | вызвать проблемы с некоторыми оконными менеджерами. | + | |
- | Если диалоговые окна мерцают при 100%-ной загрузке CPU, запретите эту | + | |
- | настройку. | + | |
<code lisp> | <code lisp> | ||
; raise-dialog-boxes-on-expose string | ; raise-dialog-boxes-on-expose string | ||
Line 211: | Line 204: | ||
Порядок кнопок внизу диалогового окна зависит от используемой операционной | Порядок кнопок внизу диалогового окна зависит от используемой операционной | ||
- | системы. | + | системы. GTK обрабатывает это автоматически, но требует, чтобы разработчики |
- | GTK обрабатывает это автоматически, но требует, чтобы разработчики установили | + | установили альтернативный порядок кнопок. Более подробно об этом написано в |
- | альтернативный порядок кнопок. Более подробно об этом написано в | + | |
документации по GTK | документации по GTK | ||
[[http://library.gnome.org/devel/gtk/unstable/GtkDialog.html#gtk-dialog-set-alternative-button-order|здесь]]. | [[http://library.gnome.org/devel/gtk/unstable/GtkDialog.html#gtk-dialog-set-alternative-button-order|здесь]]. | ||
- | Альтернативный порядок кнопок задаётся только с помощью одного вызова | + | Альтернативный порядок кнопок задаётся только с помощью одного вызова GTK-функции: |
- | GTK-функции: | + | |
<code C> | <code C> | ||
/* Настройка альтернативного порядка кнопок (ok, no, cancel, help) для других систем */ | /* Настройка альтернативного порядка кнопок (ok, no, cancel, help) для других систем */ | ||
Line 229: | Line 220: | ||
</code> | </code> | ||
- | Это должно быть сделано перед запуском каждого нового создаваемого диалогового окна. | + | Это должно быть сделано перед запуском каждого нового создаваемого |
+ | диалогового окна. | ||
==== Дизайн текущих диалогов ==== | ==== Дизайн текущих диалогов ==== | ||
Line 239: | Line 231: | ||
==== Шаблон исходного кода для простых диалоговых окон ==== | ==== Шаблон исходного кода для простых диалоговых окон ==== | ||
- | Этот шаблон не предназначен для компиляции, но отсюда легко | + | Этот шаблон не предназначен для компиляции, но отсюда легко скопировать |
- | скопировать нужный вам блок кода. | + | нужный вам блок кода. |
<code c> | <code c> | ||
Line 376: | Line 368: | ||
* размещение окон: в позиции мыши или в непредопределённой позиции? | * размещение окон: в позиции мыши или в непредопределённой позиции? | ||
* диалоговые окна не запоминают своего последнего размера, положения и содержимого | * диалоговые окна не запоминают своего последнего размера, положения и содержимого | ||
- | * отсутствуют "горячие клавиши" | + | * отсутствуют «горячие клавиши» |
**Здесь список вещей, которые могли бы быть улучшены:** | **Здесь список вещей, которые могли бы быть улучшены:** | ||
Line 400: | Line 392: | ||
==Свойства линии== | ==Свойства линии== | ||
- | * отсутствуют "горячие клавиши" | + | * отсутствуют «горячие клавиши» |
* иконки для типов линии | * иконки для типов линии | ||
== Тип заполнения == | == Тип заполнения == | ||
- | * отсутствуют "горячие клавиши" | + | * отсутствуют «горячие клавиши» |
* иконки для типов заполнения | * иконки для типов заполнения | ||
Line 412: | Line 404: | ||
==Менеджер страниц== | ==Менеджер страниц== | ||
* неправильный порядок кнопок? Зависит от того, считаете ли вы кнопку обновления основной действующей кнопкой или просто дополнительной кнопкой | * неправильный порядок кнопок? Зависит от того, считаете ли вы кнопку обновления основной действующей кнопкой или просто дополнительной кнопкой | ||
- | * может быть клавиша "Return" должна вызывать обновление | + | * может быть клавиша «Return» должна вызывать обновление |
==Выбор компонентов== | ==Выбор компонентов== | ||
Line 430: | Line 422: | ||
==Параметры дуги== | ==Параметры дуги== | ||
* Добавить в диалоговое окно диаметр, но выбирать поле ввода начального угла (increment = grid) | * Добавить в диалоговое окно диаметр, но выбирать поле ввода начального угла (increment = grid) | ||
- | * пусть "ee" вызывает диалог, если выделена только одна дуга | + | * пусть «ee» вызывает диалог, если выделена только одна дуга |
* может быть добавить метку раздела | * может быть добавить метку раздела | ||
Line 441: | Line 433: | ||
==Найти текст...== | ==Найти текст...== | ||
- | * манипулирует указателем мыши (может быть виновником является код изменения масштаба). Просто нажать "Return" чтобы вызвать FindNext (найти следующий) | + | * манипулирует указателем мыши (может быть виновником является код изменения масштаба). Просто нажать «Return» чтобы вызвать FindNext (найти следующий) |
* если вы выбираете поиск по иерархии и найденный текст находится на другой схеме, то имя файла в заголовке окна не обновляется | * если вы выбираете поиск по иерархии и найденный текст находится на другой схеме, то имя файла в заголовке окна не обновляется | ||
- | * может быть добавить опцию: "Выделить все соответствующие выражению текстовые объекты", запретить иерархию для этого случая! | + | * может быть добавить опцию: «Выделить все соответствующие выражению текстовые объекты», запретить иерархию для этого случая! |
* FIXME gschem виснет, если это диалоговое окно используется с иерархической схемой, в которой есть циклические зависимости (например, автонумерация тестовой схемы) | * FIXME gschem виснет, если это диалоговое окно используется с иерархической схемой, в которой есть циклические зависимости (например, автонумерация тестовой схемы) | ||
- | * добавить опцию "поиск только в видимом тексте" | + | * добавить опцию «поиск только в видимом тексте» |
* может быть для поиска текста вместо части строки использовать регулярные выражения | * может быть для поиска текста вместо части строки использовать регулярные выражения | ||
Line 453: | Line 445: | ||
==Показать текст...== | ==Показать текст...== | ||
* использовать регулярные выражения вместо начала строки | * использовать регулярные выражения вместо начала строки | ||
- | * может быть объединить это окно с окном "Скрыть текст..." | + | * может быть объединить это окно с окном «Скрыть текст...» |
==Автонумерация...== | ==Автонумерация...== | ||
- | * может быть запретить опцию пропуска, если областью перенумерации является "Выделенные объекты". Другие варианты пропуска ("Текущая страница" и "Вся иерархия") чесслово глупые. | + | * может быть запретить опцию пропуска, если областью перенумерации является «Выделенные объекты». Другие варианты пропуска («Текущая страница» и «Вся иерархия») чесслово глупые. |
==Размер текста== | ==Размер текста== |