Как сделать справку приложения в Calc?

[eeigor]

Как вы разрабатываете справку приложения в Calc? У меня Linux.
Ранее в Excel (Windows) я использовал, например, справку приложения на листе с выводом разделов в окне диалога. По советам Уокенбаха. Но и там были нюансы.
Элемент управления Frame позволяет организовать прокрутку текста раздела справки, поскольку надпись (Label) встроенной прокрутки не имеет.
Информация выводилась в объекте Label, который помещался в объект Frame и подстраивался под его размер.
Плюс можно было изменить мышкой размер окна (реализовано, действительно, интересно: на скриншоте 1 "Справка-в-окне-диалога.png" виден это символ (Marlett) в правом нижнем углу окна). Всё выглядело вполне профессионально.

Пример VBA кода:

Private Const MResizer = "ResizeGrab"
Private WithEvents objResizer As MSForms.Label

'  Purpose: Adds a resizing control to bottom right corner of userform
'  Used by: UserForm_Initialize"
Private Sub AddResizer()
   Set objResizer = Me.Controls.Add("Forms.label.1", MResizer, True)
   With objResizer
       With .Font
           .Name = "Marlett"
           .Charset = 2
           .Size = 16
           .Bold = True
       End With
<...>

Итог: окно расширяется (с захватом мышкой), элементы управления и текст подстраиваются под размер окна, шрифт можно сделать больше (кнопка _АА в центре)... Как всё это реализовать здесь, пока не представляю.

Upd1:
Кто имеет опыт? Или здесь всё относительно просто/сложно?
Можно ли прокручивать текст, можно ли изменять размеры окна и элементов управления, а также другие свойства в ходе исполнения (run-time)... В общем, все вопросы, которые я осветил. Как вариант, воспроизвести то же самое.

Upd2:
Загружен скриншот 3

[economist]

Siemens в 2016 г. на семинаре по юзабилити справки/доков приводили многолетние метрики скорости и точности действий оператора, который они намониторили со своих и чужих SCADA-систем (это десятки тыс. инсталляций). Если кратко то:

1) Документацию даже немцы не читают, пока не случится конкретной беды/брака/аварии

2) Однооконнный интерфейс со вспл. подсказками - лучше любой справки F1 в новых окнах, т.к. оказывается юзер сразу теряет контекст ошибки. Всегда видимые на полях help-ы, инфа в статусбаре - тоже неэффективны. Модальные инфо-окна они тоже называли злом (типа оставьте их для ахтунгов);

3) Контекстная Справка, Документация Оператора и Техническое описание - три разные обязательные справочные системы. Сделать их достойно - едва ли не труднее, чем всю программу написать. Техписатели должны и кодить, и юзать прогу - только тогда они адекватны. Если их нет вообще - на их роль правильнее искать юзеров с опытом написания "мурзилок", а не кодеров.

Из личного опыта - писали большое ПО на VBA для упр учета и анализа холдинга, 160 тыс. строк кода, 1500 msgbox-ов, 50 пошаговых визардов, книжка на 300 стр. впридачу.

Так вот, наилучший эффект, высокий балл на аттестациях и лучшие отзывы от юзеров - дала онлайн справка на вики-движке Dokuwiki/Mediawiki, т.к.

- красиво выглядит, шрифты очень приятно читаемы, чистое "шаманство"!

- актуализируется влёт, жмем на "карандаш" и правим (сделать может почти любой)

- вкладка "обсуждение" статей Help-a - давала пользы больше чем весь QA

- воспринимается серьезнее, чем лист табличного редактора, контекст не теряется (уж не знаю почему, но люди говорили именно так)

- легко (расширением) добавить Тест на усвоение материала статьи и голосовалку Помогло/Нет. Благодаря этому хотя бы понимаешь - есть ли смысл писать статьи и какие. Он есть, но далеко не каждая статья полезна.

Из плюсов движка Dokuwiki (это PHP) - portable установка, нет БД - не нужны администраторы, все статьи - в незаблокированных на запись текстовых файлах (можно формировать процедурно), работает просто реактивно, индексирует в полнотекстовый поиск не только все статьи, но и вложения pdf/doc/odf итп.

У LO 7 вики-справка стала выглядеть лучше, но все равно не дотягивает до википедйной/докувишной по легкочитаемости. Плюс справка просто недописана, мало перекр. ссылок, примеров, картинок.

В свое время русская Справка по VBA к MSO XP сделала фурор в РФ именно из-за того, что там не было ни одной статьи без примера кода (а то и 3-5 примеров).

[eeigor]

Да, комментарии от @economist – это песня.
Кого заинтересовал Докувики, сразу сюда...

[sokol92]

Справка на листе в стартовом сообщении смотрится нормально. Плюс оформительские возможности Calc вполне достаточны.
При рассмотрении любых дополнительных средств нужно думать о том, как они попадут на компьютер конечного пользователя. Правильный подход, с моей точки зрения, при тиражировании приложений - не вносить никаких изменений в настройки и не инсталлировать ничего дополнительного.

[economist]

Если инструкция условно "влезает на визитку" - тогда, конечно, на листе в ODS ей самое место.

Но если она большая или пишется "на ходу", отражая изменения в модулях Basic, внешних таблицах итд - то тогда web-сервис (или интранет) будут намного лучше, да и выглядит это профессиональнее.

Некогда популярные форматы внешних справок (HTA, CHM, HLP) - часто лочатся в доменах злыми одминами по причине наличия вековых уязвимостей, а вот браузер есть у всех и его не лочат никогда. Даже IE5 покажет современную страничку Doku/Mediawiki корректно.

[eeigor]

Какие будут соображения по поводу того, как сделать окно диалога расширяемым?
Как поставить иконку на кнопку? Чем лучше отредактировать? Какой размер? Тип файла GIF? Есть ли встроенная библиотека иконок и штатный редактор?

[economist]

Есть у меня одна поучительная метрика, измеренная в домене на 15-30 АРМ за 14 лет на MSO Excel 2007 - это "4,45 секунды". Ровно столько висит их хваленая полу-англоязычная справка на экране (самого популярного прикладного приложения в известной вселенной). Их "диалог" справки - тоже не открывается на весь экран, но расширяют его считанные единицы раз в году. Остальные - захлопывают (а ведь жали F1 неспроста - нужны была помощь!) 

Если нужно написать справку, которая будет полезной и которую будут читать - имхо, она должна быть реализована как угодно, но только не средствами диалогов LO. Модальные (да и не модальные) диалоги LO - обладают магической способностью не запоминаться (а то и стирать ранее полученные знания :-)

Если нужны иллюстрации из сотен форматов, карты ссылок, локальные секретные страницы помощи, сформированные, скажем, динамически из БД или из LDAP, ACL-система разноуровневого доступа к справке - то dokuwiki или другая вики способна обеспечить все хотелки на годы вперед. Главное - там ничего не надо кодить, только пиши саму справку, и поручить это можно штатным и латентным графоманам, которые всегда есть. А в случае со справкой в ODS - это только самому. По себе знаю - такую справку дописать до конца ни за что не получится, ибо обратная связь говорит о том что в неё не смотрят, несмотря на огромные кнопки размером с пол-экрана. Это страшно демотивирует.

[eeigor]

У меня простая справка. Результат (скриншот диалога) подгружен в стартовом сообщениии.
Не могу в режиме исполнения увеличить шрифт (дискретно по нажатию кнопки). Почему-то код ниже не работает, а в окне инспектора Xray это свойство равно 0:
oDlg.getControl("txtTopic").Model.FontHeight

Весь код занимает около сотни строк, а текст самой справки на листе. Ведь её можно и там читать (лист просто скрыт). Диалог, скорее, - элемент стиля оформления. Раз таким образом разработанный диалог позволяет быстро подключить минимальную справку к приложению. Такая справка не контекстно зависимая...

Но вопрос расширения мышкой окна более общий: как это делать в LO (на будущее)?

Upd:
Мой первый опыт знакомства с диалогами LO оставил положительное впечатление: возможностей достаточно.
"Споткнулся" один раз на combobox'е из-за отсутствия свойства ListIndex (решение ниже: ищем в цикле индекс выбранного пользователем элемента):

Код Выделить Развернуть

    With oDlg.getControl("cboTopics")
       For i = 0 To .ItemCount - 1
           If .Items(i) = .Text Then
               nCurrentTopic = i + 1  'picked item pos + 1
               Exit For
           End If
       Next
   End With

[sokol92]

а в окне инспектора Xray это свойство равно 0

Эти свойства модели (Font*) указываются в случае, когда они отличны от свойств по умолчанию, которые задаются в свойстве StyleSettings сервиса UnoControlEdit.

[eeigor]

@sokol92, спасибо. Заработало. Это было не очевидно.

Код Выделить Развернуть

   Dim nHeight%  'default

   nHeight = oDlg.getControl("txtTopic").StyleSettings.FieldFont.Height
   With oDlg.getControl("txtTopic").Model
       .FontHeight = IIf(.FontHeight, .FontHeight, nHeight) + 1  'увеличивает размер шрифта на 1
   End With

[sokol92]

Это было не очевидно

В LO главный инструмент познания - грабли.

[eeigor]

Окно уже не модальное.
Осталось сделать расширяемым.
Что-то здесь всё слишком сложно (супер кнопкой или клавишами со стрелками, а надо мышкой). Или здесь (окно в модальном окне)...
Надо, чтобы окно захватывалось мышкой (курсор изменялся соответственно), ну, хотя бы за правый нижний угол и всё. И при движении мыши окно изменяло размер. Настройку положения и размеров элементов управления сделать несложно.

Метод, который изменяет размер окна, это .setPosSize, ниже размер меняется дискретно:

Код Выделить Развернуть

Sub SetDialogPosSize
   With oDlg.PosSize
       oDlg.setPosSize .X, .Y, .Width + 50, .Height + 50, 12  'sets size
   End With
End Sub
Нужно плавно при движении мыши.

Замысел такой. Добавляем элемент управления типа Label в правый угол диалога динамически (как в примере ниже при открытии формы) и подключаем события, но можно и не динамически. При наведении мыши на этот Label курсор изменяет вид (.MousePointer = fmMousePointerSizeNWSE), нажимаем кнопку (захват) и тянем... Окно диалога изменяет размер. Строка .Font.Name = "Marlett" вставляет символ в Label, который (в виде полосок) можно увидеть на скриншоте 1 в правом нижнем углу формы в стартовом сообщении.

VBA-аналог (минимальные размеры окна задаются при инициализации формы и равны исходным размерам спроектированной формы):

Код Выделить Развернуть

Private Const MResizer = "ResizeGrab"
Private WithEvents objResizer As MSForms.Label
Private msngLeftResizePos As Single
Private msngTopResizePos  As Single
Private msngFormWidthMin  As Single
Private msngFormHeightMin As Single

'===========================
' Resizer Procedures
'===========================

'  Purpose: Adds a resizing control to bottom right corner of userform
'  Used by: UserForm_Initialize
Private Sub AddResizer()
   Set objResizer = Me.Controls.Add("Forms.label.1", MResizer, True)
   With objResizer
       With .Font
           .Name = "Marlett"
           .Charset = 2
           .Size = 16
           .Bold = True
       End With
       
       .BackStyle = fmBackStyleTransparent '.BackColor = Me.BackColor
       .AutoSize = True
       .BorderStyle = fmBorderStyleNone
       .Caption = Chr$(111) '"o"
       .MousePointer = fmMousePointerSizeNWSE
       .ForeColor = RGB(100, 100, 100) 'Dark grey
       .ZOrder
       .Top = Me.InsideHeight - .Height
       .Left = Me.InsideWidth - .Width
   End With
End Sub

Private Sub objResizer_MouseDown(ByVal Button As Integer _
, ByVal Shift As Integer, ByVal X As Single, ByVal Y As Single)

   If Button = 1 Then
       msngLeftResizePos = X
       msngTopResizePos = Y
   End If
End Sub

' Requires: AjustControls
Private Sub objResizer_MouseMove(ByVal Button As Integer _
, ByVal Shift As Integer, ByVal X As Single, ByVal Y As Single)

   If Button = 1 Then
       Dim sngOffsetX As Single, sngOffsetY As Single
       
       sngOffsetX = X - msngLeftResizePos
       sngOffsetY = Y - msngTopResizePos
       
       If Me.Width + sngOffsetX < msngFormWidthMin Then
           sngOffsetX = msngFormWidthMin - Me.Width
       End If
       If Me.Height + sngOffsetY < msngFormHeightMin Then
           sngOffsetY = msngFormHeightMin - Me.Height
       End If
       
       If Not (sngOffsetX = 0 Or sngOffsetY = 0) Then
           With objResizer
               .Move .Left + sngOffsetX, .Top + sngOffsetY
               Me.Width = Me.Width + sngOffsetX
               Me.Height = Me.Height + sngOffsetY
               .Left = Me.InsideWidth - .Width
               .Top = Me.InsideHeight - .Height
           End With
           
           Call AjustControls(sngOffsetX, sngOffsetY)
       End If
   End If
End Sub

' Requires: AjustTopic
'  Used by: objResizer_MouseMove
Private Sub AjustControls(sngOffsetX As Single, sngOffsetY As Single)
   <...>

Код выше от какого-то австралийского умельца, любезно предоставленный Дж. Уокенбаху для его книги по Excel 2013.
Мы можем его как-то адаптировать под нашу модель?..

[eeigor]

Впрочем, пример по ссылке 2 в предыдущем сообщении производит впечатление... Профессионально! Только окно модальное.
Но надо попытаться открыть его методом не execute(), a setVisible()
Много информации... требуется время

[sokol92]

Спасибо за интересную ссылку!

Можно диалог, созданный методом, указанным в ссылке, открывать и через setVisible. Для этого нужно переменную oDialog описать как Global; в обработчике windowClosing вызов метода endExecute заменить на вызов dispose.

[eeigor]

@sokol92, хотелось бы с вашей помощью увидеть цельное решение в обобщенном виде. Вы это сделаете быстрее...

Предложение к модераторам форума:
Обсуждаемое здесь решение является типовым. Было бы неплохо иметь раздел для хранения таких наработок, как у наших "соседей".