gnttextview.h

   1 /**
   2  * @file gnttextview.h Textview API
   3  * @ingroup gnt
   4  */
   5 /*
   6  * GNT - The GLib Ncurses Toolkit
   7  *
   8  * GNT is the legal property of its developers, whose names are too numerous
   9  * to list here.  Please refer to the COPYRIGHT file distributed with this
  10  * source distribution.
  11  *
  12  * This library is free software; you can redistribute it and/or modify
  13  * it under the terms of the GNU General Public License as published by
  14  * the Free Software Foundation; either version 2 of the License, or
  15  * (at your option) any later version.
  16  *
  17  * This program is distributed in the hope that it will be useful,
  18  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  19  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  20  * GNU General Public License for more details.
  21  *
  22  * You should have received a copy of the GNU General Public License
  23  * along with this program; if not, write to the Free Software
  24  * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA  02111-1301  USA
  25  */
  26
  27 #ifndef GNT_TEXT_VIEW_H
  28 #define GNT_TEXT_VIEW_H
  29
  30 #include "gntwidget.h"
  31 #include "gnt.h"
  32 #include "gntcolors.h"
  33 #include "gntkeys.h"
  34
  35 #define GNT_TYPE_TEXT_VIEW                              (gnt_text_view_get_gtype())
  36 #define GNT_TEXT_VIEW(obj)                              (G_TYPE_CHECK_INSTANCE_CAST((obj), GNT_TYPE_TEXT_VIEW, GntTextView))
  37 #define GNT_TEXT_VIEW_CLASS(klass)              (G_TYPE_CHECK_CLASS_CAST((klass), GNT_TYPE_TEXT_VIEW, GntTextViewClass))
  38 #define GNT_IS_TEXT_VIEW(obj)                   (G_TYPE_CHECK_INSTANCE_TYPE((obj), GNT_TYPE_TEXT_VIEW))
  39 #define GNT_IS_TEXT_VIEW_CLASS(klass)   (G_TYPE_CHECK_CLASS_TYPE((klass), GNT_TYPE_TEXT_VIEW))
  40 #define GNT_TEXT_VIEW_GET_CLASS(obj)    (G_TYPE_INSTANCE_GET_CLASS((obj), GNT_TYPE_TEXT_VIEW, GntTextViewClass))
  41
  42 #define GNT_TEXT_VIEW_FLAGS(obj)                                (GNT_TEXT_VIEW(obj)->priv.flags)
  43 #define GNT_TEXT_VIEW_SET_FLAGS(obj, flags)             (GNT_TEXT_VIEW_FLAGS(obj) |= flags)
  44 #define GNT_TEXT_VIEW_UNSET_FLAGS(obj, flags)   (GNT_TEXT_VIEW_FLAGS(obj) &= ~(flags))
  45
  46 typedef struct _GntTextView                     GntTextView;
  47 typedef struct _GntTextViewPriv         GntTextViewPriv;
  48 typedef struct _GntTextViewClass                GntTextViewClass;
  49
  50 typedef enum
  51 {
  52         GNT_TEXT_VIEW_NO_SCROLL     = 1 << 0,
  53         GNT_TEXT_VIEW_WRAP_CHAR     = 1 << 1,
  54         GNT_TEXT_VIEW_TOP_ALIGN     = 1 << 2,
  55 } GntTextViewFlag;
  56
  57 struct _GntTextView
  58 {
  59         GntWidget parent;
  60
  61         GString *string;
  62         GList *list;        /* List of GntTextLine */
  63
  64         GList *tags;       /* A list of tags */
  65         GntTextViewFlag flags;
  66 };
  67
  68 typedef enum
  69 {
  70         GNT_TEXT_FLAG_NORMAL      = 0,
  71         GNT_TEXT_FLAG_BOLD        = 1 << 0,
  72         GNT_TEXT_FLAG_UNDERLINE   = 1 << 1,
  73         GNT_TEXT_FLAG_BLINK       = 1 << 2,
  74         GNT_TEXT_FLAG_DIM         = 1 << 3,
  75         GNT_TEXT_FLAG_HIGHLIGHT   = 1 << 4,
  76 } GntTextFormatFlags;
  77
  78 struct _GntTextViewClass
  79 {
  80         GntWidgetClass parent;
  81
  82         void (*gnt_reserved1)(void);
  83         void (*gnt_reserved2)(void);
  84         void (*gnt_reserved3)(void);
  85         void (*gnt_reserved4)(void);
  86 };
  87
  88 G_BEGIN_DECLS
  89
  90 /**
  91  * @return  GType for GntTextView.
  92  */
  93 GType gnt_text_view_get_gtype(void);
  94
  95 /**
  96  * Create a new textview.
  97  *
  98  * @return The newly created textview.
  99  */
 100 GntWidget * gnt_text_view_new(void);
 101
 102 /**
 103  * Scroll the textview.
 104  * @param view     The textview to scroll.
 105  * @param scroll   scroll > 0 means scroll up, < 0 means scroll down, == 0 means scroll to the end.
 106  */
 107 void gnt_text_view_scroll(GntTextView *view, int scroll);
 108
 109 /**
 110  * Append new text in a textview.
 111  *
 112  * @param view   The textview.
 113  * @param text   The text to append to the textview.
 114  * @param flags  The text-flags to apply to the new text.
 115  */
 116 void gnt_text_view_append_text_with_flags(GntTextView *view, const char *text, GntTextFormatFlags flags);
 117
 118 /**
 119  * Append text in the textview, with some identifier (tag) for the added text.
 120  *
 121  * @param view   The textview.
 122  * @param text   The text to append.
 123  * @param flags  The text-flags to apply to the new text.
 124  * @param tag    The tag for the appended text, so it can be changed later (@see gnt_text_view_tag_change)
 125  */
 126 void gnt_text_view_append_text_with_tag(GntTextView *view, const char *text, GntTextFormatFlags flags, const char *tag);
 127
 128 /**
 129  * Move the cursor to the beginning of the next line and resets text-attributes.
 130  * It first completes the current line with the current text-attributes.
 131  *
 132  * @param view  The textview.
 133  */
 134 void gnt_text_view_next_line(GntTextView *view);
 135
 136 /**
 137  * Convert GNT-text formats to ncurses-text attributes.
 138  *
 139  * @param flags  The GNT text format.
 140  *
 141  * @return  Nucrses text attribute.
 142  */
 143 chtype gnt_text_format_flag_to_chtype(GntTextFormatFlags flags);
 144
 145 /**
 146  * Clear the contents of the textview.
 147  *
 148  * @param view  The textview.
 149  */
 150 void gnt_text_view_clear(GntTextView *view);
 151
 152 /**
 153  * The number of lines below the bottom-most visible line.
 154  *
 155  * @param view  The textview.
 156  *
 157  * @return  Number of lines below the bottom-most visible line.
 158  */
 159 int gnt_text_view_get_lines_below(GntTextView *view);
 160
 161 /**
 162  * The number of lines above the topmost visible line.
 163  *
 164  * @param view  The textview.
 165  *
 166  * @return  Number of lines above the topmost visible line.
 167  */
 168 int gnt_text_view_get_lines_above(GntTextView *view);
 169
 170 /**
 171  * Change the text of a tag.
 172  *
 173  * @param view   The textview.
 174  * @param name   The name of the tag.
 175  * @param text   The new text for the text. If 'text' is @c NULL, the tag is removed.
 176  * @param all    @c TRUE if all of the instancess of the tag should be changed, @c FALSE if
 177  *               only the first instance should be changed.
 178  *
 179  * @return  The number of instances changed.
 180  */
 181 int gnt_text_view_tag_change(GntTextView *view, const char *name, const char *text, gboolean all);
 182
 183 /**
 184  * Setup hooks so that pressing up/down/page-up/page-down keys when 'widget' is
 185  * in focus scrolls the textview.
 186  *
 187  * @param view    The textview.
 188  * @param widget  The trigger widget.
 189  */
 190 void gnt_text_view_attach_scroll_widget(GntTextView *view, GntWidget *widget);
 191
 192 /**
 193  * Setup appropriate hooks so that pressing some keys when the 'pager' widget
 194  * is in focus triggers the PAGER to popup with the contents of the textview
 195  * in it.
 196  *
 197  * The default key-combination to trigger the pager is a-v, and the default
 198  * PAGER application is $PAGER. Both can be changed in ~/.gntrc like this:
 199  *
 200  * @code
 201  * [pager]
 202  * key = a-v
 203  * path = /path/to/pager
 204  * @endcode
 205  *
 206  * @param view    The textview.
 207  * @param pager   The widget to trigger the PAGER.
 208  */
 209 void gnt_text_view_attach_pager_widget(GntTextView *view, GntWidget *pager);
 210
 211 /**
 212  * Setup appropriate hooks so that pressing some keys when 'widget'
 213  * is in focus triggers the EDITOR to popup with the contents of the textview
 214  * in it.
 215  *
 216  * The default key-combination to trigger the pager is a-e, and the default
 217  * EDITOR application is $EDITOR. Both can be changed in ~/.gntrc like this:
 218  *
 219  * @code
 220  * [editor]
 221  * key = a-e
 222  * path = /path/to/editor
 223  * @endcode
 224  *
 225  * @param view     The textview.
 226  * @param widget   The widget to trigger the EDITOR.
 227  */
 228 void gnt_text_view_attach_editor_widget(GntTextView *view, GntWidget *widget);
 229
 230 /**
 231  * Set a GntTextViewFlag for the textview widget.
 232  *
 233  * @param view  The textview widget
 234  * @param flag  The flag to set
 235  *
 236  * @since 2.0.0 (gnt), 2.1.0 (pidgin)
 237  */
 238 void gnt_text_view_set_flag(GntTextView *view, GntTextViewFlag flag);
 239
 240 G_END_DECLS
 241
 242 #endif /* GNT_TEXT_VIEW_H */