contrib/texinfo/info/window.h

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