Blog literacki, portal erotyczny - seks i humor nie z tej ziemi
+#K$ Tworzenie plików pomocy dla Windows
System pomocy Windows został stworzony aby ułatwić użytkownikom uzyskanie bezpośredniej pomocy dotyczącej działania
danej aplikacji lub sposobu wykonania określonego działania bez konieczności odrywania się pracy z ową aplikacją. System pomocy
Windows składa się z zestawu plików pomocy HELP oraz programu WINHELP.EXE - zarządzającego tymi plikami.
W niniejszej pracy zajmiemy się bardzo pobieżnie tworzeniem plików pomocy, oraz wykorzystaniem ich we własnych
aplikacjach.
Spis treści:
Ogólnie o plikach HELP
Tworzenie plików tematycznych (*.RTF)
Tworzenie pliku Help Project File (*.HPJ)
Kompilacja gotowego pliku pomocy (*.HLP)
Wykorzystywanie plików pomocy we własnych aplikacjach
Informacje o autorze
+#$K Ogólnie o plikach HELP
Pliki pomocy zorganizowane są w postaci stron tematycznych - każdy temat umieszczony jest na jednej stronie o dowolnej
długości, której zawartość można przeglądać używając paska przewijania. Strony mogą zawierać elementy sterujące - takie jak pole
skoku do innej strony lubpole skoku do okienka informacyjnego .
Pole skoku do innej strony
Pole skoku do okienka informacyjnego
Pliki HELP są to skompilowane pliki danych zawierające tekst, grafikę oraz znaczniki kontrolne, dlatego też próba zajrzenia do
środka takiego pliku za pomocą zwykłego edytora tekstu, kończy się na widoku mieszaniny znaków ASCII, nie mających większego
sensu. Aby uzyskać dostęp do zawartości plików pomocy trzeba odwołać się do standardowej aplikacji będącej na wyposażeniu
Windows - WINHELP.EXE.
Wykorzystywanie plików pomocy we własnych aplikacjach
Aby stworzyć własny plik pomocy należy utworzyć plik zawierający dane dla stron tematycznych (*.RTF) - takie pliki tworzy
się edytorem umożliwiającym zapis w formacie RTF (np. Ami Pro, Microsoft Word, czy Word Perfect). Następnie tworzymy plik
nagłówkowy (*.HPJ) zawierający informacje co do sposobu kompilacji i plików składowych wynikowego pliku pomocy (*.HLP). Do tego
celu możemy użyć dowolnego edytora umożliwiającego zapis w formacie ASCII (choćby NotePad). Następnie posługując się
specjalnym kompilatorem (Help Compiler - zawartym w takich pakietach jak Borland C++, Microsoft Visual Basic, Microsoft C, np.
kompilatorem HC31.EXE z pakietu Borland C++ 3.1) dochodzimy do produktu wyjściowego, jakim jest plik pomocy HELP (*.HLP)
Tworzenie plików tematycznych (*.RTF)
Tworzenie pliku Help Project File (*.HPJ)
Kompilacja gotowego pliku pomocy (*.HLP)
+#$K Tworzenie plików tematycznych (*.RTF)
Plik tematyczny zawiera tekst będący treścią naszego help'u. W pliku tym możemy używać różnorodnych rodzajów, kolorów i
rozmiarów czcionek (jednakże czcionki użyte do pisania help'u muszą być dostępne na platformie, na której help będzie odtwarzany; w
przeciwnym wypadku czcionka niedostępna zostanie zastąpiona inną, domyślną), możemy dołączać elementy grafiki w formatach:
BMP, WMF, MRB, SHG - monochromatyczne bądź w 16 kolorach (tryb 256-kolorowy nie jest dostępny dla plików pomocy), możemy
używać tekstu lub grafiki jako elementów sterujących poruszeniem się po zawartości help'u.
Dalej przedstawimy przykładowy proces tworzenia pliku tematycznego w formacie RTF (Rich Text Format) za pomocą edytora
Microsoft Word 2.0 pl
Na początku każdej strony musimy umieścić specjalne przypisy definiujące daną stronę help'u. Wykonujemy to poprzez
wybranie z menu WSTAW opcji PRZYPIS. Musimy użyć odpowiedniego odnośnika dla określenia właściwości strony. Znaki
odnośników są z góry ustalone dla plików pomocy i spełniają następujące funkcje:
# - Identyfikator strony
$ - Tekst w opcji SZUKAJ podczas korzystania z pomocy
K - Tekst w opcji SZUKAJ po wybraniu opcji WYŚWIETL TEMATY
+ - Identyfikator kolejności przeglądania stron
Dalej piszemy swój tekst, który będzie wyświetlany na ekranie. Możemy tutaj wstawić grafikę aby podnieść walory wizualne naszego
help'u. Czynimy to wybierając z menu WSTAW opcję GRAFIKĘ, a następnie wyszukujemy na dysku obrazek w formacie BMP, który
chcemy wstawić. W tekście możemy także umieścić elementy sterujące:
Pole skoku do innej strony
Pole skoku do okienka informacyjnego
Na końcu tekstu danej strony umieszczamy znak końca strony - z menu WSTAW wybieramy opcję ZNAK KOŃCA i argument
STRONY. Następnie przechodzimy do strony następnej i tworzymy ją w analogiczny sposób.
Tworzenie pliku Help Project File (*.HPJ)
#$ Pole skoku do innej strony
Polem skoku do innej strony może być zarówno tekst jak i grafika. Problem polega na tym, żeby fragment tekstu bądź
grafika były odpowiednio oznaczone.
Jeżeli chcemy aby dany kawałek tekstu, bądź grafika była polem skoku do innej strony musimy go podkreślić PODWÓJNE
(z menu FORMAT wybieramy opcję ZNAK i ustawiamy podkreślenie PODWÓJNE), następnie zaraz za tym tekstem piszemy
identyfikator strony, do której chcemy skoczyć. Ten tekst musi być tekstem ukrytym (z menu FORMAT wybieramy opcję ZNAK i
ustawiamy atrybut UKRYTY). Podobnie postępujemy kiedy chcemy wykorzystać grafikę jako taki element sterujący. Wstawiamy
obrazek (z menu WSTAW opcja GRAFIKA) bezpośrednio w tekst (nie należy używać do tego celu RAMKI), następnie zaznaczamy
wstawioną grafikę, nadajemy jej atrybut podwójnego podkreślenia a za grafiką, tekstem ukrytym piszemy, identyfikator strony, do której
ma się odbyć skok.
Poniżej dwa przykłady pół skoku do innej strony - jeden jako linijka tekstu, drugi jako grafika.
Przykładowe pole skoku do innej strony (jako tekst)
Wróć do:
Ogólnie o plikach HELP
Tworzenie plików tematycznych (*.RTF)
#$ Pole skoku do okienka informacyjnego
Okienko informacyjne ze względu na sposób tworzenia niewiele różni się od strony tematycznej, różnica polega na sposobie
objawiania się użytkownikowi. Służy ono do przekazywania krótkich informacji o danym zagadnieniu. Po uaktywnieniu przez
użytkownika pola skoku do okienka informacyjnego, nie następuje przejście do innej strony, a na stronie bieżącej, pojawia się,
automatycznie dopasowane wielkością do zawartej treści, okienko. Po naciśnięciu klawisza myszy, samoczynnie znika. Okienko
informacyjne, podobnie jak strona, okienko może zawierać tekst, grafikę i pola skoku do strony bądź okienka. Różnica w tworzeniu
polega na tym, że w przypisach definiujących to okienko, określamy jedynie identyfikator okienka (#), nie określamy identyfikatorów
służących do odnalezienia okienka w spisie treści, bo i po co, skoro ma to być jedynie krótka informacja dotycząca danej strony?
Pole skoku do okienka informacyjnego definiuje się zasadniczo tak samo jak pole skoku do innej strony. Różnica polega na
tym, że używa się podkreślenia POJEDYNCZEGO zamiast PODWÓJNEGO. Po bliższe informacje, jak tworzyć pola skoku, proponuję
przejść do poniższego tematu:
Pole skoku do innej strony
Poniżej dwa przykłady pół skoku do okienka informacyjnego - jeden jako linijka tekstu, drugi jako grafika.
Przykładowe pole skoku do okienka informacyjnego (jako tekst)
Wróć do:
Ogólnie o plikach HELP
Tworzenie plików tematycznych (*.RTF)
#$ Przykładowa strona
To jest przykładowa strona help'u.
Możemy tu używać różnorodnych krojów pisma np:
Arial
Courier New
Times New Roman
Różnych wielkości znaków danej czcionki
Oraz różnych kolorów danego tekstu
Nie ma także problemów z umieszczaniem grafiki
Wróć do poprzedniej strony
# Przykładowe okienko informacyjne
W okienku także można używać różnych rodzajów czcionek
oraz wstawiać grafikę.
# Identyfikator (#)
Służy do identyfikacji strony lub okienka przez system pomocy WINHELP.EXE. Jest także używany pośrednio jako identyfikator
podczas wykorzystywania plików pomocy we własnych aplikacjach. Musi to być jeden ciąg znaków nie zawierający spacji, unikalny dla
całego help'u.
Na przykład: IDENTYFIKATOR_STRONY_1
# Identyfikator (K)
Jest to tekst w opcji SZUKAJ po wybraniu opcji WYŚWIETL TEMATY podczas korzystania z pomocy. Wybranie tego tematu z listy
spowoduje wyświetlenie tej strony. Jest to jedna linijka tekstu, mogąca zawierać spacje.
Na przykład: Spis treści
# Identyfikator ($)
Jest to tekst w opcji SZUKAJ podczas korzystania z pomocy. Określa temat informacji na liście tematów. Jest to jedna linijka,
mogąca zawierać spacje.
Na przykład: ASCII: format pliku
# Identyfikator (+)
Jest to identyfikator określający kolejność przeglądania stron w danej sekcji. Sekcja taka może zawierać różne strony w dowolnej
kolejności. Aby mieć możliwość przeglądania stron według ustalonej kolejności, autor help'u musi zadbać o klawisze przeglądania. W
tym celu należy w pliku (*.HPJ) w części [CONFIG] umieścić makro BrowseButtons(). Nazwa sekcji nie powinna zawierać spacji i
powinna być unikalna dla całego dokumentu.
Na przykład: SEKCJA:001
+#$K Kompilacja gotowego pliku pomocy (*.HLP)
Kiedy mamy już gotowy plik tematyczny (*.RTF) oraz plik nagłówkowy (*.HPJ), możemy przystąpić do kompilacji gotowego
pliku pomocy (*.HLP). W tym celu musimy posłużyć się Help Compiler'em (np. HC31.EXE, dodawanym do pakietu Borland C++ 3.1).
Aby ułatwić sobie życie, zgrywamy wszystkie potrzebne pliki (*.HPJ, *.RTF, HC31.EXE) do jednego katalogu. Program HC31 nie
posiada interface'u użytkownika i obsługuje się go z linii poleceń DOS. Aby dokonać kompilacji wystarczy uruchomić program HC31 z
naszym plikiem (*.HPJ) jako parametr.
Na przykład: C:>MYHELP\HC31.EXE myhelp.hpj
Kompilator nie zadając żadnych pytać sam skompiluje pliki (*.HPJ) i (*.RTF) do postaci (*.HLP), co najwyżej wyświetli komunikaty
ostrzeżenia jeżeli coś nie będzie się zgadzało (np. gdy zostanie wykonany skok do nie istniejącej strony).
+#$ Informacje o autorze
ProjektTworzenie plików pomocy dla Windows został napisany w celu przybliżenia użytkownikom problemu pisania plików
pomocy oraz wykorzystywania ich we własnych aplikacjach, przy braku jakiejkolwiek literatury na rynku w obecnym czasie. Jest to
tylko ogólny zarys sposobu tworzenia help'ów i ich wykorzystywania. Podczas pisania tego projektu bazowałem na strzępkach
dokumentacji Microsoft Windows i Borland C++, analogicznym, nieco jednak uboższym projekcie panów: Tomasza Tury i Rafała
Wałęski z kwietnia 1996r, przykładem CHELP dodanym do pakietu Borland C++ 3.1 oraz własnymi spostrzeżeniami i
doświadczeniami. Jest to praca jak najbardziej amatorska nie mogąca pretendować do miana pracy naukowej, więc autor nie ponosi
odpowiedzialności za nieścisłości i rozbieżności pomiędzy treścią tu zawartą a stanem faktycznym, jakkolwiek gwarantuje, że help
stworzony zgodnie z zawartymi tu wskazówkami będzie działał.
Robert Trzewiczek
kl. IV i T - TZN 1995/96
Dąbrowa Górnicza - czerwiec - 1996
+#$K Tworzenie plików Help Project File (*.HPJ)
PliHelp Project File jest konieczny do kompilacji pliku help. W nim zawarte są niezbędne informacje co do sposobu
kompilacji. To właśnie ten plik podajemy, jako parametr Help Compiler'a. Jest to zwykły plik ASCII, podobny do plików (*.INI) Windows.
Plik taki składa się z jednej lub kilku sekcji, których nazwy zawarte są w nawiasach kwadratowych [ ].
Opis poszczególnych sekcji:
[OPTIONS] - Wyszczególnia opcje kontrolne procesu kompilacji.
[FILES] - Wyszczególnia jakie pliki zostaną dołączone podczas kompilacji.
[BUILDTAGS] - Wyszczególnia znaczniki kompilacji.
[CONFIG] - Wyszczególnia makra definiujące niestandardowe klawisze i menu.
[BITMAPS] - Wyszczególnia pliki graficzne dołączane podczas kompilacji.
[MAP] - Przyporządkowuje ciągi znaków odpowiednim identyfikatorom kontekstowym.
[WINDOWS] - Definiuje charakterystyki pierwszego okna i okien następnych.
Obowiązkowa jest tylko sekcja [FILES], pozostałe mogą być użyte ale nie muszą. Z uwagi na objętość tej pracy, omówimy pobieżnie
budowę tylko najbardziej istotnych sekcji i ich elementów:
[OPTIONS]
Sekcja ta jest opcjonalna, ale jeśli zostanie użyta, powinna być umieszczona jako pierwsza. Zawiera następujące identyfikatory:
TITLE - określa tytuł okna, w którym będzie nasz help.
Na przykład:
TITLE = Przykład mojego HELP'u
CONTENTS - określa, która strona będzie przyporządkowana klawiszowi spisu treści. Zawiera identyfikator strony (#) ze spisem treści.
Strona ta ukazuje się jako pierwsza.
Na przykład:
CONTENTS = spis_treści
COMPRESS - określa stopień kompresji. Może przyjąć następujące wartości:
HIGH - wysoki stopień
MEDIUM - średni stopień
NO - bez kompresji
Na przykład:
COMPRESS = NO
ICON - określa nazwę pliku ikony, jaka zostanie przyłączona do pliku help.
Na przykład:
ICON = my_icon.ico
FORCEFONT - określa nazwę czcionki, jaką będzie pisany nasz help.
Na przykład:
FORCEFONT = Arial CE
[FILES]
Wyszczególnia pliki które zostaną wykorzystane w procesie kompilacji. Tutaj musi być umieszczona nazwa pliku (*.RTF) z treścią
help'u.
Na przykład:
[FILES]
mój_help.rtf
Wykorzystywanie plików pomocy we własnych aplikacjach
+K$# Wykorzystywanie plików pomocy we własnych aplikacjach
System pomocy Windows umożliwia użytkownikom wywoływanie plików pomocy z poziomu własnych aplikacji. We własnych
aplikacjach HELP można wykorzystywać w dwojaki sposób:
- wywołując pomoc bezpośrednio (np. za pomocą polecenia menu, lub klawisza)
- wywołując pomoc w sposób kontekstowy (np. wywołać pomoc dla danego menu)
Gdy chcemy wykorzystać nasz help w pierwszy sposób (wywołując go samodzielnie z programu) powinniśmy zrobić to w sposób mniej
więcej taki:
case WM_COMMAND:
switch (wParam)
{
case IDM_HELP_CONTENTS:
{
WinHelp(hwnd, "my_help.hlp", HELP_CONTENTS, 0L);
break;
}
...
}
break;
Lepszym sposobem wywoływania pomocy jest używanie identyfikatorów kontekstowych. Jeżeli chcemy, aby nasza aplikacja
pokazywała pomoc dla konkretnej opcji menu, po podświetleniu tej opcji i naciśnięciu klawisza F1, powinniśmy podjąć następujące
kroki:
Przypisać identyfikatorom stron tematycznych (#) (tych, które będą używane od opisu opcji menu) unikalne wartości liczbowe (najlepiej
z zakresu 100-999) i zapisać je w pliku (*.H). Poniżej przykład takiego pliku:
#define STRONA_1 600
#define STRONA_2 601
#define STRONA_3 602
Plik taki (zwany dalej helpmap.h) należy dołączyć poleceniem #include
[MAP] pliku Help Project File (*.HPJ).
Następnie musimy napisać funkcję obsługującą komunikat Windows WM_ENTERIDLE - wysyłany w momencie kiedy menu lub
okienko dialogowe jest w stanie bezczynnym - nie ma w kolejce żadnych komunikatów, po obsłużeniu ostatniego. Stan taki pojawia się
w momencie, kiedy podświetlimy jakąś opcję menu, ale jeszcze jej nie wywołamy klawiszem ENTER bądź kliknięciem myszy. Musimy
wtedy sprawdzić czy został naciśnięty klawisz F1, odnotować to w zmiennej pomocniczej, a następnie wysłać komunikat
uaktywniający to menu (np. wysłać komunikat o naciśnięciu klawisza ENTER). Dalej czekamy na komunikat że zostało uaktywnione
menu, sprawdzamy zminną pomocniczą, czy został naciśniety klawisz F1 i w przypadku, kiedy został, wywołujemy WinHelp z
identyfikatorem kontekstowym danej opcji menu, a jeżeli nie wciśnięto F1, zamieszczamy normalną funkcję obsługującą tą opcję
menu.
Przykład funkcji obsługującej komunikat WM_ENTERIDLE:
BOOL keyf1 = FALSE;
...
case WM_ENTERIDLE:
{
if ((wParam == MSGF_MENU) && ((GetKeyState(VK_F1) & 0x8000) != 0))
{
keyf1 = TRUE;
PostMessage(hwnd, WM_KEYDOWN, VK_RETURN, 0L);
}
break;
...
Przykład funkcji obsługującej uaktywnienie opcji z menu:
case WM_COMMAND:
switch (wParam)
{
case IDM_MENUITEM:
{
if (keyf1 == TRUE)
{
WinHelp(hwnd, "myhelp.hlp", HELP_CONTEXT, STRONA_1);
keyf1 = FALSE;
}
else
{
menuitem();
}
break;
}
}
...
Powyżej zamieściłem najprostszy sposób wykorzystywania help'ów we własnych aplikacjach. Można to robić w inny sposó, używając
innych funkcji obsługi, a nawet innych, pokrewnych komunikatów. Inaczej sprawa przedstawia się w przypadku korzystania z Object
Windows Library. Jak już zaznaczyłem, ta praca jest tylko zarysem tematu o plikach pomocy. Dociekliwi będą musieli poszukać w
obszerniejszych źródłach.
--------------------
Gdzie:
IDM_HELP_CONTENTS - to identyfikator wywołanego menu
my_help.hlp - to nasz plik pomocy
HELP_CONTENTS - to parametr wewnętrzny polecenia WinHelp