1/* window.h -- Structure and flags used in manipulating Info windows.
2   $Id: window.h,v 1.3 2004/04/11 17:56:46 karl Exp $
3
4   This file is part of GNU Info, a program for reading online documentation
5   stored in Info format.
6
7   Copyright (C) 1993, 1997, 2004 Free Software Foundation, Inc.
8
9   This program is free software; you can redistribute it and/or modify
10   it under the terms of the GNU General Public License as published by
11   the Free Software Foundation; either version 2, or (at your option)
12   any later version.
13
14   This program is distributed in the hope that it will be useful,
15   but WITHOUT ANY WARRANTY; without even the implied warranty of
16   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
17   GNU General Public License for more details.
18
19   You should have received a copy of the GNU General Public License
20   along with this program; if not, write to the Free Software
21   Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA.
22
23   Written by Brian Fox (bfox@ai.mit.edu). */
24
25#ifndef INFO_WINDOW_H
26#define INFO_WINDOW_H
27
28#include "infomap.h"
29#include "nodes.h"
30
31/* Smallest number of visible lines in a window.  The actual height is
32   always one more than this number because each window has a modeline. */
33#define WINDOW_MIN_HEIGHT 2
34
35/* Smallest number of screen lines that can be used to fully present a
36   window.  This number includes the modeline of the window. */
37#define WINDOW_MIN_SIZE (WINDOW_MIN_HEIGHT + 1)
38
39/* The exact same elements are used within the WINDOW_STATE structure and a
40   subsection of the WINDOW structure.  We could define a structure which
41   contains this elements, and include that structure in each of WINDOW_STATE
42   and WINDOW.  But that would lead references in the code such as
43   window->state->node which we would like to avoid.  Instead, we #define the
44   elements here, and simply include the define in both data structures. Thus,
45   if you need to change window state information, here is where you would
46   do it.  NB> The last element does NOT end with a semi-colon. */
47#define WINDOW_STATE_DECL \
48   NODE *node;          /* The node displayed in this window. */ \
49   int pagetop;         /* LINE_STARTS[PAGETOP] is first line in WINDOW. */ \
50   long point           /* Offset within NODE of the cursor position. */
51
52/* Structure which defines a window.  Windows are doubly linked, next
53   and prev. The list of windows is kept on WINDOWS.  The structure member
54   window->height is the total height of the window.  The position location
55   (0, window->height + window->first_row) is the first character of this
56   windows modeline.  The number of lines that can be displayed in a window
57   is equal to window->height - 1. */
58typedef struct window_struct
59{
60  struct window_struct *next;      /* Next window in this chain. */
61  struct window_struct *prev;      /* Previous window in this chain. */
62  int width;            /* Width of this window. */
63  int height;           /* Height of this window. */
64  int first_row;        /* Offset of the first line in the_screen. */
65  int goal_column;      /* The column we would like the cursor to appear in. */
66  Keymap keymap;        /* Keymap used to read commands in this window. */
67  WINDOW_STATE_DECL;    /* Node, pagetop and point. */
68  char *modeline;       /* Calculated text of the modeline for this window. */
69  char **line_starts;   /* Array of printed line starts for this node. */
70  int line_count;       /* Number of lines appearing in LINE_STARTS. */
71  int flags;            /* See below for details. */
72} WINDOW;
73
74typedef struct {
75  WINDOW_STATE_DECL;            /* What gets saved. */
76} WINDOW_STATE;
77
78/* Structure defining the current state of an incremental search. */
79typedef struct {
80  WINDOW_STATE_DECL;    /* The node, pagetop and point. */
81  int search_index;     /* Offset of the last char in the search string. */
82  int direction;        /* The direction that this search is heading in. */
83  int failing;          /* Whether or not this search failed. */
84} SEARCH_STATE;
85
86#define W_UpdateWindow  0x01    /* WINDOW needs updating. */
87#define W_WindowIsPerm  0x02    /* This WINDOW is a permanent object. */
88#define W_WindowVisible 0x04    /* This WINDOW is currently visible. */
89#define W_InhibitMode   0x08    /* This WINDOW has no modeline. */
90#define W_NoWrap        0x10    /* Lines do not wrap in this window. */
91#define W_InputWindow   0x20    /* Window accepts input. */
92#define W_TempWindow    0x40    /* Window is less important. */
93
94extern WINDOW *windows;         /* List of visible Info windows. */
95extern WINDOW *active_window;   /* The currently active window. */
96extern WINDOW *the_screen;      /* The Info screen is just another window. */
97extern WINDOW *the_echo_area;   /* THE_ECHO_AREA is a window in THE_SCREEN. */
98
99/* Global variable control redisplay of scrolled windows.  If non-zero, it
100   is the desired number of lines to scroll the window in order to make
101   point visible.  A user might set this to 1 for smooth scrolling.  If
102   set to zero, the line containing point is centered within the window. */
103extern int window_scroll_step;
104
105 /* Make the modeline member for WINDOW. */
106extern void window_make_modeline (WINDOW *window);
107
108/* Initalize the window system by creating THE_SCREEN and THE_ECHO_AREA.
109   Create the first window ever, and make it permanent.
110   You pass WIDTH and HEIGHT; the dimensions of the total screen size. */
111extern void window_initialize_windows (int width, int height);
112
113/* Make a new window showing NODE, and return that window structure.
114   The new window is made to be the active window.  If NODE is passed
115   as NULL, then show the node showing in the active window.  If the
116   window could not be made return a NULL pointer.  The active window
117   is not changed.*/
118extern WINDOW *window_make_window (NODE *node);
119
120/* Delete WINDOW from the list of known windows.  If this window was the
121   active window, make the next window in the chain be the active window,
122   or the previous window in the chain if there is no next window. */
123extern void window_delete_window (WINDOW *window);
124
125/* A function to call when the screen changes size, and some windows have
126   to get deleted.  The function is called with the window to be deleted
127   as an argument, and it can't do anything about the window getting deleted;
128   it can only clean up dangling references to that window. */
129extern VFunction *window_deletion_notifier;
130
131/* Set WINDOW to display NODE. */
132extern void window_set_node_of_window (WINDOW *window, NODE *node);
133
134/* Tell the window system that the size of the screen has changed.  This
135   causes lots of interesting things to happen.  The permanent windows
136   are resized, as well as every visible window.  You pass WIDTH and HEIGHT;
137   the dimensions of the total screen size. */
138extern void window_new_screen_size (int width, int height);
139
140/* Change the height of WINDOW by AMOUNT.  This also automagically adjusts
141   the previous and next windows in the chain.  If there is only one user
142   window, then no change takes place. */
143extern void window_change_window_height (WINDOW *window, int amount);
144
145/* Adjust the pagetop of WINDOW such that the cursor point will be visible. */
146extern void window_adjust_pagetop (WINDOW *window);
147
148/* Tile all of the windows currently displayed in the global variable
149   WINDOWS.  If argument DO_INTERNALS is non-zero, tile windows displaying
150   internal nodes as well. */
151#define DONT_TILE_INTERNALS 0
152#define TILE_INTERNALS      1
153extern void window_tile_windows (int style);
154
155/* Toggle the state of line wrapping in WINDOW.  This can do a bit of fancy
156   redisplay. */
157extern void window_toggle_wrap (WINDOW *window);
158
159/* For every window in CHAIN, set the flags member to have FLAG set. */
160extern void window_mark_chain (WINDOW *chain, int flag);
161
162/* For every window in CHAIN, clear the flags member of FLAG. */
163extern void window_unmark_chain (WINDOW *chain, int flag);
164
165/* Make WINDOW start displaying at PERCENT percentage of its node. */
166extern void window_goto_percentage (WINDOW *window, int percent);
167
168/* Build a new node which has FORMAT printed with ARG1 and ARG2 as the
169   contents. */
170extern NODE *build_message_node (char *format, void *arg1, void *arg2);
171
172/* Useful functions can be called from outside of window.c. */
173extern void initialize_message_buffer (void);
174
175/* Print FORMAT with ARG1,2 to the end of the current message buffer. */
176extern void printf_to_message_buffer (char *format, void *arg1, void *arg2,
177    void *arg3);
178
179/* Convert the contents of the message buffer to a node. */
180extern NODE *message_buffer_to_node (void);
181
182/* Return the length of the most recently printed line in message buffer. */
183extern int message_buffer_length_this_line (void);
184
185/* Pad STRING to COUNT characters by inserting blanks. */
186extern int pad_to (int count, char *string);
187
188/* Make a message appear in the echo area, built from FORMAT, ARG1 and ARG2.
189   The arguments are treated similar to printf () arguments, but not all of
190   printf () hair is present.  The message appears immediately.  If there was
191   already a message appearing in the echo area, it is removed. */
192extern void window_message_in_echo_area (char *format, void *arg1, void *arg2);
193
194/* Place a temporary message in the echo area built from FORMAT, ARG1
195   and ARG2.  The message appears immediately, but does not destroy
196   any existing message.  A future call to unmessage_in_echo_area ()
197   restores the old contents. */
198extern void message_in_echo_area (char *format, void *arg1, void *arg2);
199extern void unmessage_in_echo_area (void);
200
201/* Clear the echo area, removing any message that is already present.
202   The echo area is cleared immediately. */
203extern void window_clear_echo_area (void);
204
205/* Quickly guess the approximate number of lines to that NODE would
206   take to display.  This really only counts carriage returns. */
207extern int window_physical_lines (NODE *node);
208
209/* Calculate a list of line starts for the node belonging to WINDOW.  The line
210   starts are pointers to the actual text within WINDOW->NODE. */
211extern void calculate_line_starts (WINDOW *window);
212
213/* Given WINDOW, recalculate the line starts for the node it displays. */
214extern void recalculate_line_starts (WINDOW *window);
215
216/* Return the number of characters it takes to display CHARACTER on the
217   screen at HPOS. */
218extern int character_width (int character, int hpos);
219
220/* Return the number of characters it takes to display STRING on the
221   screen at HPOS. */
222extern int string_width (char *string, int hpos);
223
224/* Return the index of the line containing point. */
225extern int window_line_of_point (WINDOW *window);
226
227/* Get and return the goal column for this window. */
228extern int window_get_goal_column (WINDOW *window);
229
230/* Get and return the printed column offset of the cursor in this window. */
231extern int window_get_cursor_column (WINDOW *window);
232
233/* Get and Set the node, pagetop, and point of WINDOW. */
234extern void window_get_state (WINDOW *window, SEARCH_STATE *state);
235extern void window_set_state (WINDOW *window, SEARCH_STATE *state);
236
237/* Count the number of characters in LINE that precede the printed column
238   offset of GOAL. */
239extern int window_chars_to_goal (char *line, int goal);
240
241#endif /* not INFO_WINDOW_H */
242