Context Navigation

txwhelp.c

Revision 14, 26.9 kB (checked in by jvw, 2 years ago)
HEX/ASCII (sector) editor control added

Line
1	//
2	// TxWin, Textmode Windowing Library
3	//
4	// Original code Copyright (c) 1995-2005 Fsys Software and Jan van Wijk
5	//
6	// ==========================================================================
7	//
8	// This file contains Original Code and/or Modifications of Original Code as
9	// defined in and that are subject to the GNU Lesser General Public License.
10	// You may not use this file except in compliance with the License.
11	// BY USING THIS FILE YOU AGREE TO ALL TERMS AND CONDITIONS OF THE LICENSE.
12	// A copy of the License is provided with the Original Code and Modifications,
13	// and is also available at http://www.dfsee.com/txwin/lgpl.htm
14	//
15	// This library is free software; you can redistribute it and/or modify
16	// it under the terms of the GNU Lesser General Public License as published
17	// by the Free Software Foundation; either version 2.1 of the License,
18	// or (at your option) any later version.
19	//
20	// This library is distributed in the hope that it will be useful,
21	// but WITHOUT ANY WARRANTY; without even the implied warranty of
22	// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
23	// See the GNU Lesser General Public License for more details.
24	//
25	// You should have received a copy of the GNU Lesser General Public License
26	// along with this library; (lgpl.htm) if not, write to the Free Software
27	// Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
28	//
29	// Questions on TxWin licensing can be directed to: txwin@fsys.nl
30	//
31	// ==========================================================================
32	//
33	// TX windows help manager
34	//
35	// Author: J. van Wijk
36	//
37	// JvW 12-09-2001 Initial version
38
39	#include <txlib.h> // public interface
40	#include <txwpriv.h> // private window interface
41
42	#define TXWH_IDCHAR '#' // helpid character in text
43
44	#define TXWH_INFILE 0x00000000 // item is in a file
45	#define TXWH_INMEM 0x00000001 // item is in memory
46
47	#define TXWH_HELPHELP 0xfffffffe // help-id help-on-help
48	#define TXWH_WID_HELP 0xff01 // window id help screen
49
50	typedef struct txwhelp_item
51	{
52	ULONG helpid; // helpid for this item
53	ULONG linenr; // line-nr for the item
54	ULONG flags; // status flags
55	union
56	{
57	char **text; // in memory text array
58	ULONG offset; // offset in file for section
59	};
60	TXTM title; // short item title
61	} TXWHELP_ITEM; // end of struct "txwhelp_item"
62
63
64	static ULONG txwh_alloc = 0; // allocated items
65	static ULONG txwh_items = 0; // used items
66
67	static TXWHELP_ITEM *txwh_index = NULL; // allocated array of items
68
69	static char *helphelp[] =
70	{
71	"",
72	" This is the help for the TxWindows userinterface and its help system",
73	"",
74	" TxWindows is a windowing system a bit like the operating system GUI's",
75	" as MS-Windows, OS/2 or the Mac. Unlike these GRAPHICAL interfaces,",
76	" TxWindows is based on textmode displays only. This allows usage in",
77	" simple systems and even from (DOS or OS/2) bootdiskettes.",
78	"",
79	#if defined (HAVEMOUSE)
80	" Allthough keyboard oriented, most windows and (menu)lists can be",
81	" operated using a mouse as well. The supported mouse actions are:",
82	"",
83	" Button1 click Will move the FOCUS to the window under the mouse",
84	" (left) pointer when possible, and if succesfull operate",
85	" the corresponding control, like selecting from a",
86	" (menu)list, press a button, toggle a checkbox or",
87	" radiobutton, or any other appropriate action ...",
88	"",
89	" Button1 drag When holding the button down after clicking on a",
90	" window title-bar, the whole window can be moved",
91	" by dragging the mouse-cursor. It will be resized",
92	" when the drag starts from the lower-right corner",
93	"",
94	" Button2 click Will display the HELP window related to the window",
95	" (right) window under the mouse (context sensitive)",
96	"",
97	" Button3 click Available to application, no action by the UI itself",
98	" Button-3 is often combined with the mouse wheel.",
99	"",
100	" Key modifiers Button actions combined with Ctrl, Alt or Shift",
101	" keys are recognized, but currently not used by",
102	" the UI itself. The application may use them.",
103	"",
104	" Mouse chord Mouse-chords, multiple buttons down at the same",
105	" have no special meaning, and the behaviour when",
106	" using them is undefined.",
107	"",
108	" Wheel up/down When supported by the mouse and mouse driver, the",
109	#if defined (WIN32)
110	" wheel can be used to scroll UP/DOWN or LEFT/RIGHT",
111	" This works by direct translation to ARROW keys and",
112	" the PgUp/PgDn keys, so the position of the mouse",
113	" is NOT significant. The Ctrl/Alt/Shift keys will",
114	" modify the wheel behaviour as follows:",
115	"",
116	" None Wheel will scroll one LINE at a time (UP/DOWN key)",
117	" Shift Wheel will scroll one PAGE at a time (PgUp/PgDn)",
118	" Alt Wheel will scroll one CHAR at a time (LEFT/RIGHT)",
119	" Ctrl Wheel will scroll the SCROLLBUFFER (text output)",
120	" instead of the currently active window",
121	"",
122	" Combinations of the above work as expected, except for Alt+Shift",
123	#else
124	" wheel can be used to scroll UP/DOWN per line or",
125	" per page, depending on the mouse driver logic.",
126	#endif
127	"",
128	" You can activate/deactive the menu by clicking on the DESKTOP BORDER",
129	" (title/footer), the top lines of the text output window, inside the",
130	" command-line entryfield if the menu is up, or using the <F10> key.",
131	"",
132	" Many dialogs can be closed by clicking on the [X] close button in the",
133	" upper right corner of the window border (same as using Escape/Cancel.",
134	"",
135	" In large text windows (like HELP) or large lists, scroll-indicators",
136	" will appear in the right hand side of the window border, apart from",
137	" using the keyboard, you can also click these to scroll up and down",
138	" one line at a time, or one page at a time. The indicators used are:",
139	"",
140	" ÄÄÄÄÄÄÄÄÄÄ¿ ÄÄÄÄÄÄÄÄÄÄ¿",
141	" scroll up, 1 line (Up) -",
142	" text or
143	scroll up, 1 page (PgUp) text or U",
144	" list ³ list ³",
145	" window ³ window ³",
146	" CP-437 scroll down, 1 page (PgDn) ASCII D",
147	" scroll down, 1 line (Down) +",
148	" ÄÄÄÄÄÄÄÄÄÄÙ ÄÄÄÄÄÄÄÄÄÄÙ",
149	"",
150	#else
151	" Note: In the current implementation TxWindows can be controlled using",
152	" the keyboard only, mouse-support will be added at a later time.",
153	"",
154	#endif
155	" The screen for a TxWindows application always uses a DESKTOP window",
156	" as background, other windows displayed will allways be on top of it.",
157	" Most applications use a large scrolling output window (SCROLLBUFFER)",
158	" that receives outputlines from the application which is scrolled up",
159	" when the screen fills up. This scrollbuffer is usually very large and",
160	" older output can be viewed using navigation keys like PgUp/PgDn",
161	"",
162	" User input is either in the form of COMMANDS that are entered in an",
163	" input field usually near the bottom of the screen, or in the form of",
164	" DIALOG-windows that may have fields, buttons, lists and so on ...",
165	"",
166	" A special form of dialog is the MENU BAR, it can be activated using",
167	" the F10 function key or clicking the desktop/scrollbuffer title.",
168	" The menu supports selection of actions from several pulldown menus.",
169	" You can get specific help on each item in the menu by pressing the",
170	" F1 functionkey while the item is selected, or by clicking it using",
171	" mouse button-2 (usually the most right button).",
172	"",
173	"",
174	" The following keys are the most important ones to control TxWindows:",
175	"",
176	" Tab / Backtab Move to the next or previous selectable window, like",
177	" between the input-field and scrollbuffer, or between",
178	" the control-windows in an input dialog.",
179	"",
180	" Esc End or abort the current dialog, often equivalent to",
181	" CANCELING it. Many applications also use the Esc-key",
182	" to abort long-running commands like searching.",
183	"",
184	" Enter End current input dialog, making the entered value(s)",
185	" available to the application for processing.",
186	"",
187	" Arrow-keys Navigate within an inputfield, scroll textlines in a",
188	" text-window like help or move to the next or previous",
189	" controlwindow in a dialog (buttons, fields ...)",
190	"",
191	" PgUp / PgDn Scroll textlines in a window one page at a time",
192	" Home / End Move to begin/end of an inputfield, or output text",
193	" Ctrl-Home/End Move to first/last line of a text output window",
194	"",
195	" Ctrl + Arrow Scroll the text in the SCROLLBUFFER in the direction",
196	" of the arrow when possible. In an inputfield the left",
197	" and right arrow will move the cursor over one word.",
198	"",
199	" Ctrl PgUp/Dn Scoll the SCROLLBUFFER up or down, one page at a time",
200	"",
201	" Note: SCROLLBUFFER movement even works from OTHER windows!",
202	"",
203	"",
204	" F1 Get help on the current window, inputfield, button ...",
205	" A second F1 will give more generic help, like on the",
206	" complete dialog, and a third will present the help on",
207	" the TxWindows system (this text).",
208	"",
209	" F3 Usually end the current dialog, canceling input, or",
210	" end the application itself when on the commandline",
211	"",
212	" F4 End the current dialog, ACCEPTING the input",
213	" (like an [ OK ] button)",
214	"",
215	" F10 Toggle the main-menu ON or OFF",
216	"",
217	" F11 Present command history in a selection popup list",
218	"",
219	" Alt + F2 Send COMPLETE help-file to the SCROLLBUFFER (screen)",
220	"",
221	" Alt + F5 Restore resized, minimized or maximized window to its",
222	" previous size. (initial, or just before min/maximize)",
223	"",
224	" Alt + F10 Maximize the current window to the size of its parent",
225	" client-window. (usually the SCROLLBUFFER or desktop).",
226	"",
227	" Alt + F9 Minimize the current window to just its titlebar, or",
228	" F12 make it completely invisible when no titlebar present.",
229	" This allows you to look under or behind the window.",
230	" When the main inputfield is active, the whole DESKTOP",
231	" will be minimized revealing the previous screen.",
232	"",
233	" Alt + F12 Cycle through available SCROLLBUFFER color-schemes:",
234	" NORMAL: White on black background, use all FG colors",
235	" BRIGHT: White on black background, bright colors only",
236	" INVERT: Black on white background, no bright colors",
237	" Select the scheme with best readability",
238	"",
239	" Ctrl + l Repaint ALL windows on the desktop, can be usefull in",
240	" Ctrl + r very rare cases to correct screen-painting problems.",
241	""
242	" Alt + c Change appearance of the user interface using:",
243	" - Arrow-key UP/DOWN: change overall color scheme",
244	" - Arrow-key LEFT/RIGHT: change output-window colors",
245	" - Page Up / Page Down: change line-style scheme",
246	"",
247	" Alt + m Move or Resize the currently displayed window:",
248	" - Arrow-keys: Move or Resize thw window",
249	" - Insert-key: Switch between Move and Resize",
250	"",
251	#if defined (DUMP)
252	" Alt + / Cycle through available TRACE settings: OFF, TITLEBAR",
253	" or SCREEN/LOGFILE (depending on other trace settings).",
254	"",
255	#endif
256	" Other available (function) keys might be displayed in the bottom line",
257	" for a dialog window.",
258	"",
259	" For entryfields the following editing keys are available:",
260	"",
261	" Insert Toggle between Insert and replace mode",
262	" Delete Delete the character at the cursor position",
263	" Backspace Delete the character before the cursor position",
264	" Home Move cursor to the start of the entryfield",
265	" End Move cursor to the end of the entryfield",
266	" Ctrl + Backspace Clear entry-field completely, making it empty",
267	" Ctrl + E Clear entry-field from cursor to end-of-field",
268	" Ctrl + Right Arrow Move one word to the right in the field",
269	" Ctrl + Left Arrow Move one word to the left in the field",
270	"",
271	" When the field supports a history buffer (like a command field would):",
272	"",
273	" Ctrl + D Delete current line from history, if full match",
274	" Ctrl + K Add current line to the history, no execute",
275	" Up [prefix] Recall previous (older) command from history",
276	" Down [prefix] Recall next (newer) command from history",
277	" F11 [prefix] Show history contents in a selection popup list",
278	" On each of these, the prefix is the part of the",
279	" commandline BEFORE the cursor that will be used",
280	" to FILTER the result of the requested action",
281	"",
282	" Other keys are either inserted/replaced in the entryfield content,",
283	" like letters, digits and interpunction, or simply ignored",
284	"",
285	"",
286	"",
287	" The HELP system",
288	"",
289	" Help can be called from many places, using a help-id to specify",
290	" the subject for wich help is required. This can be a specific part",
291	" of the user-interface like a button or a window, or it can be a",
292	" subject known to the application like a command.",
293	"",
294	" The help subjects can be called by pressing a [Help] button, using",
295	" the <F1> function key, or any other application specified method.",
296	"",
297	" Once help is displayed, it can be navigated using the following keys:",
298	"",
299	" PgUp / PgDn Scroll help window up/down by one page",
300	" Left / Right Scroll help window left/right",
301	" Up / Down Scroll help window up / down",
302	" Home / End Scroll help window to left/right margin",
303	"",
304	" Esc Quit help, return to previous active window",
305	" F1 Get more generic help, usually related to the item",
306	" currently displayed (the 'owner' window) and when",
307	" pressed a 3rd time, help on TxWindows (these pages)",
308	"",
309	" Alt + F2 Send COMPLETE help-file to the SCROLLBUFFER (screen)",
310	" Note that this may be thousands of lines!",
311	"",
312	" Since the help window is MODAL, you cannot switch to other",
313	" application windows using the <Tab> key",
314	"",
315	"",
316	NULL
317	};
318
319	static char *notfound[] =
320	{
321	"",
322	" The requested help item could not be found.",
323	"",
324	" Please report this to your support contact for this software",
325	" and include the help-id number as specified below, as well as.",
326	" information on how to reproduce this possible error",
327	"",
328	NULL,
329	NULL
330	};
331
332	#define TXWH_NOTFOUND_LINE 7 // insert text at line ...
333
334	// to be refined, add sort and binary-search functions (linear search now)
335	// to be refined, add txwRegisterHelpFile (with multiple sections)
336
337	// Add extra space for new help items
338	static BOOL txwAddItemSpace
339	(
340	ULONG items // IN nr of extra items
341	);
342
343	// Find a help item by its helpid (simple linear search)
344	static TXWHELP_ITEM *txwFindItemId // RET ref to item or NULL
345	(
346	ULONG helpid // IN helpid
347	);
348
349
350	/*****************************************************************************/
351	// Display standard help dialog with text for specified help-id
352	/*****************************************************************************/
353	ULONG txwHelpDialog
354	(
355	ULONG helpid // IN id for helpitem
356	)
357	{
358	ULONG rc; // function return
359	TXWHELP_ITEM *hi;
360	char **display = notfound; // text to display
361	ULONG topline = 0; // starting line number
362	TXTM title;
363	TXTM info;
364
365	ENTER();
366	TRACES(("helpid:%8.8lx = %lu\n", helpid, helpid));
367	TRWINS("1");
368
369	if (helpid != TXWH_NO_MORE_HELP)
370	{
371	strcpy( title, " Help item: "); // start of help title
372	if ((hi = txwFindItemId(helpid)) != NULL) // is item registred ?
373	{
374	display = hi->text;
375	topline = hi->linenr;
376	strcat( title, hi->title);
377	}
378	else if (helpid == TXWH_HELPHELP) // help on help
379	{
380	display = helphelp;
381	strcat( title, "TxWindows and the helpsystem itself");
382	}
383	else // prepare notfound help-page
384	{
385	display = notfound;
386	strcat( title, "not found");
387
388	sprintf( info, " The requested help-id is: 0x%8.8lx = %lu",
389	helpid, helpid);
390
391	notfound[ TXWH_NOTFOUND_LINE] = info;
392	}
393	strcat( title, " ");
394
395	if (txwIsWindow( TXHWND_DESKTOP)) // is there a desktop ?
396	{
397	TXRECT position; // reference size/position
398	TXWHANDLE hframe; // help frame
399	TXWHANDLE hview; // help view text
400	TXWINDOW window; // frame window data
401	ULONG ownerhelp = TXWH_HELPHELP;
402	ULONG focushelp = TXWH_HELPHELP;
403	TXWINDOW *win;
404
405	txwQueryWindowRect( TXHWND_DESKTOP, FALSE, &position);
406	TRECTA( "desktop size", (&position));
407
408	if ((txwValidateHandle((TXWHANDLE) txwa->focus, &win)) != NULL)
409	{
410	focushelp = win->helpid;
411	if ((txwValidateHandle((TXWHANDLE) txwa->focus->owner, &win)) != NULL)
412	{
413	ownerhelp = win->helpid;
414	if ((focushelp == TXWH_HELPHELP) && (ownerhelp == TXWH_HELPHELP))
415	{
416	ownerhelp = TXWH_NO_MORE_HELP; // stop recursive help on help
417	}
418	if (((win->client.left < 10) && (win->client.top < 5)) \|\|
419	((win->client.left + 78 < txwa->screen.right ) &&
420	(win->client.top + 22 < txwa->screen.bottom) ) )
421	{
422	position = win->client; // owners position
423	}
424	}
425	}
426	TRECTA( "pos ", (&position));
427
428	position.left += 2; // cascade the new window
429	position.top += 1;
430	if (position.left + 76 < txwa->screen.right)
431	{
432	position.right = 76;
433	}
434	else
435	{
436	position.right = txwa->screen.right - position.left;
437	}
438	position.bottom = txwa->screen.bottom - position.top;
439	if (position.bottom > 25)
440	{
441	position.bottom -= 4; // allow some room
442	}
443	TRECTA( "size", (&position));
444
445	TRACES(("focus help-id = %8.8lx = %lu\n", focushelp, focushelp));
446	TRACES(("owner help-id = %8.8lx = %lu\n", ownerhelp, ownerhelp));
447
448	txwSetupWindowData(
449	position.top, position.left, position.bottom, position.right,
450	TXWS_CANVAS \| TXWS_CAST_SHADOW \| TXWS_MOVEABLE,
451	TXWH_HELPHELP, // help-on-help id
452	' ', ' ', TXWSCHEME_COLORS, "", "",
453	&window);
454	window.dlgFocusID = TXWH_WID_HELP; // focus to help-text viewer
455	hframe = txwCreateWindow( TXHWND_DESKTOP, TXW_FRAME, 0, 0, &window, NULL);
456
457	txwSetupWindowData(
458	0, 0, position.bottom, position.right,
459	TXWS_FRAMED \| // borders (scroll indicator)
460	TXCS_CLOSE_BUTTON \| // include a close button [X]
461	TXWS_HCHILD_SIZE \| // resize with parent
462	TXWS_VCHILD_SIZE,
463	ownerhelp, // help-on-help = owner
464	' ', ' ', TXWSCHEME_COLORS,
465	title, txwstd_footer,
466	&window);
467	window.tv.topline = topline;
468	window.tv.leftcol = 0;
469	window.tv.maxtop = TXW_INVALID;
470	window.tv.maxcol = TXW_INVALID;
471	window.tv.buf = display;
472	hview = txwCreateWindow( hframe, TXW_TEXTVIEW, hframe, 0, &window,
473	txwDefWindowProc);
474	txwSetWindowUShort( hview, TXQWS_ID, TXWH_WID_HELP);
475
476	rc = txwDlgBox( TXHWND_DESKTOP, 0, txwDefDlgProc, hframe, NULL);
477	}
478	}
479	RETURN (rc);
480	} // end 'txwHelpDialog'
481	/---------------------------------------------------------------------------/
482
483
484	/*****************************************************************************/
485	// Register a helptext of one section with multiple items
486	/*****************************************************************************/
487	ULONG txwRegisterHelpText
488	(
489	ULONG baseid, // IN base id type/section
490	char *title, // IN section title
491	char *text[] // IN help text array
492	)
493	{
494	ULONG rc = NO_ERROR; // function return
495	ULONG nr = 1; // nr of items / linenr
496	TXWHELP_ITEM *hi; // item pointer
497	char **tx; // text array pointer
498	char *s;
499
500	ENTER();
501	TRACES(("adding base id : %lu = 0x%8.8lx\n", baseid, baseid));
502
503	for (tx = text; tx && *tx; tx++)
504	{
505	if (*tx[0] == TXWH_IDCHAR)
506	{
507	nr++; // count items
508	}
509	}
510	if (txwAddItemSpace( nr))
511	{
512	hi = &(txwh_index[ txwh_items++]); // add default 1st item
513	hi->helpid = baseid;
514	hi->linenr = 0;
515	hi->flags = TXWH_INMEM;
516	hi->text = text;
517	strncpy( hi->title, title, TXMAXTM);
518
519	for ( nr = 0, tx = text;
520	(tx) && (*tx);
521	nr++, tx++)
522	{
523	s = *tx; // point to current line
524	if (*s == TXWH_IDCHAR)
525	{
526	hi = &(txwh_index[ txwh_items++]); // add next item from text
527	hi->helpid = baseid + TxaParseNumber( s+1, TX_RADIX_STD_CLASS, NULL);
528	TRACES(("adding help id : %lu = 0x%8.8lx\n", hi->helpid, hi->helpid));
529	hi->linenr = nr;
530	hi->flags = TXWH_INMEM;
531	hi->text = text;
532	if ((s = strchr( *tx, ' ')) != NULL)
533	{
534	strncpy( hi->title, s+1, TXMAXTM);
535	}
536	}
537	}
538	}
539	else
540	{
541	rc = TX_ALLOC_ERROR;
542	}
543	RETURN (rc);
544	} // end 'txwRegisterHelpText'
545	/---------------------------------------------------------------------------/
546
547
548	/*****************************************************************************/
549	// Free helpmanager resources
550	/*****************************************************************************/
551	void txwTerminateHelpManager
552	(
553	void
554	)
555	{
556	ENTER();
557
558	if (txwh_index != NULL)
559	{
560	free( txwh_index);
561	txwh_index = NULL;
562	txwh_alloc = 0;
563	txwh_items = 0;
564	}
565	VRETURN ();
566	} // end 'txwTerminateHelpManager'
567	/---------------------------------------------------------------------------/
568
569
570	/*****************************************************************************/
571	// Add extra space for new help items
572	/*****************************************************************************/
573	static BOOL txwAddItemSpace
574	(
575	ULONG items // IN nr of extra items
576	)
577	{
578	BOOL rc = FALSE; // function return
579	char m = (char ) txwh_index;
580
581	if (items > 0)
582	{
583	m = realloc( m, (size_t) (txwh_alloc + items) * sizeof(TXWHELP_ITEM));
584	if (m != NULL)
585	{
586	memset( m + ( txwh_alloc * sizeof(TXWHELP_ITEM)),
587	0, ((size_t)(items * sizeof(TXWHELP_ITEM))) );
588
589	txwh_index = (TXWHELP_ITEM *) m;
590	txwh_alloc += items;
591	rc = TRUE;
592	}
593	}
594	return (rc);
595	} // end 'txwAddItemSpace'
596	/---------------------------------------------------------------------------/
597
598
599	/*****************************************************************************/
600	// Find a help item by its helpid (simple linear search)
601	/*****************************************************************************/
602	static TXWHELP_ITEM *txwFindItemId // RET ref to item or NULL
603	(
604	ULONG helpid // IN helpid
605	)
606	{
607	TXWHELP_ITEM *rc = NULL; // function return
608	TXWHELP_ITEM *hi;
609	ULONG i;
610
611	ENTER();
612	TRACES(("#items:% 4lu helpid: %8.8lx = %lu\n", txwh_items, helpid, helpid));
613
614	for (i = 0, hi = txwh_index; hi && (i < txwh_items); i++, hi++)
615	{
616	TRACES(("items#:% 4d helpid: %8.8lx = %lu\n", i, hi->helpid, hi->helpid));
617	if (hi->helpid == helpid)
618	{
619	rc = hi; // found the item
620	break;
621	}
622	}
623	RETURN (rc);
624	} // end 'txwFindItemId'
625	/---------------------------------------------------------------------------/

Note: See TracBrowser for help on using the browser.

Context Navigation

root/trunk/txlib/txwhelp.c

Download in other formats: