viewport Class Reference

Before directly using this class, you should consider reading text_windows. More...

#include <cursorwindow.h>

Inheritance diagram for viewport:
Inheritance graph
[legend]
Collaboration diagram for viewport:
Collaboration graph
[legend]

List of all members.

Classes

struct  repaint_handler
 Derive from repaint_handler to implement your repaint object which will be invoked whenever there is a resize event or if some other viewport is created or deleted or activated. Your repaint handler is expected to ask for the viewports size and completely repaint this region. The cmd passed to your repaint handler is one of the cmd_constant enum values. More...

Public Types

typedef OstreamableBuffer
< viewport, char,
std::char_traits< char > > 
buf_type
typedef char char_type
typedef traits_type::int_type int_type
typedef traits_type::off_type off_type
typedef traits_type::pos_type pos_type
enum  position {
  tiled,
  floating
}
 

A specification of how constrained the window position and size is.

More...
typedef std::char_traits< char > traits_type

Public Member Functions

void activate ()
 repaint the window and give it a command of 'activate'.
void beep ()
 Produce an audible alarm.
void box (int width, int height, bool filled, std::string title)
 Draw a box starting at the current cursor position that is width columns wide and height columns tall (running down from the current cursor position.
void box (int width, int height, bool filled, char const *title=0)
 Draw a box starting at the current cursor position that is width columns wide and height columns tall (running down from the current cursor position.
void box (int width, int height, bool filled, char const *title_string, unsigned length)
 Draw a box starting at the current cursor position that is width columns wide and height columns tall (running down from the current cursor position.
row_col curpos () const
 Get the current cursor position within the viewport.
void fill_to_eol (char c=' ')
 fill the rest of the current line, starting at the current cursor position, with a specified character -- defaulting to space.
void fill_to_eos (char c=' ')
repaint_handlerget_repaint_handler ()
std::auto_ptr< viewporthsplit (repaint_handler *)
 Split the viewport horizontally and return handle to the right half. The repaint_handler you specify is used to handle repaint requests there. Note that if the window is too small to handle the request, you will receive a new viewport completely overlaying this viewport. Note that this is meant to be used with tiled viewports -- but you can manually move a viewport using the 'move()' method.
void move (row_col where, row_col size)
 Move the viewport around within the CursorWindow. This call sets the position and size of the viewport. This will trigger a repaint of the whole cursor window when next input occurs -- with the cmd of 'resize'.
row_col origin () const
 Get the absolute position of the upper left corner of the viewport.
void ostreamable_helper (char c)
void refresh ()
void restore_curpos ()
 Make sure the cursor is in the correct position for this viewport.
void set_curpos (row_col rc)
 Move the cursor to the specified row and column within the viewport.
void set_curpos (int row, int col)
 Move the cursor to the specified row and column within the viewport.
void set_repaint_handler (repaint_handler *r)
void set_text_attribute (int)
 < Get the current text attribute of this viewport
row_col size () const
 Get the width in columns and the height in rows of the viewport. Note that you cannot force this information but must live with the size you get. Well, ok, you can call 'move' which will force the size but generally this will mess up screen layout -- only do it as part of the resize_handler logic.
int text_attribute () const
 < Fill the rest of the current VIEWPORT, starting at the current cursor position, with a specified character -- defaulting to space.
 viewport (port *)
 make a second viewport that uses the same port (safe but rarely needed )
 viewport (viewport const &)
 Not for general use! only meant to be used by get_viewports() but it has a container that requires it! Darn!
 viewport (CursorWindow *, repaint_handler *, position p=tiled)
 constructor
std::auto_ptr< viewportvsplit (repaint_handler *)
 Split the viewport vertically and return handle to the bottom half. The repaint_handler you specify is used to handle repaint requests there. Note that if the window is too small to handle the request, you will receive a new viewport completely overlaying this viewport. Note that this is meant to be used with tiled windows which are contiguous but you can move a viewport using the 'move()' method.
CursorWindowwindow ()
 Get the window on which this viewport is drawn.
void write (long c, int length=1)
 write specified number of characters to the window in the default text attribute at the current cursor position. The default repeat count is 1.
void write (std::string const &s, size_t length=1000000)
 Ditto.
void write (char const *s)
 Write a string in the current text attributes at the current cursor position and move the cursor -- all within the viewport.
void write (char const *, size_t length)
 Write a specified number of characters to the current cursor position and move the cursor -- all within the viewport.
template<class Iterator >
void write (Iterator first, Iterator last)
 Write text to the window.
 ~viewport ()
 destructor

Public Attributes

bool owned_
 indicates that when the viewport is destroyed, deleted the port. This is almost but not always true. The get_viewports() function sets this to false.
port * port_
 this variable should be private but my crufty old MSVC 6.0 compiler requires it to be public

Private Member Functions

viewportoperator= (viewport const &r)
 not implemented!

Friends

class CursorWindow

Detailed Description

Before directly using this class, you should consider reading text_windows.

A viewport is a simplistic representation of a subwindow of a CursorWindow. You can draw in it, position the cursor in it, etc. To use a view port, you must provide a repaint object which will repaint the window on command. Derive from viewport:: repaint_handler to implement yours. Each CursorWindow keeps a list of viewports. Only one may be active at any given time. You can manually activate a viewport, using the 'activate()' method of the viewport -- it will in tern invoke your repaint object's function call operator method. Attempts to write into a deactivated viewport will be ignored.

WARNING! Don't allow your repaint_handler's to go out of scope before your viewports that referring to them do! You have been warned!

You cannot get input from a viewport, per se. Instead, you can activate a viewport and position the one and only text cursor available in the viewport -- thus making it look like you are getting input there. In truth, all input comes from the cursor window as a whole -- so you are responsible for giving the user the hints you choose as to "where" the input seems to be going.

To use a viewport, you ask the CursorWindow to make you one. See the method, CursorWindow::new_viewport(). This function returns your viewport as an alt_tools::auto_ptr<viewport>.

When drawing into a viewport, the upper left of the viewport is 0,0. Attempts to draw outside the viewport will be silently ignored. Each viewport has its own text attributes.

Note that there is no read_input() method of a viewport. All input goes to the currently active viewport and needs to be handled as a global feature. You can call restore_curpos() to make sure that the cursor is in the current cursor position for this viewport.

When the user resizes his xterm window, the CursorWindow's resize_handler (see above) is responsible for scaling the viewports to account for the change. It can draw if it likes, but the viewport repaint_handlers will be invoked as well.

Note that a viewport, like a CursorWindow, is an Ostreamable object. That is, you can perform 'iostream' operations to it. But don't get too fancy, simple formatting is the best you can do. See Ostreamable for more details.

Note also that there are some builtin input mechanisms that use viewports. They are nested classes inside the viewport class. See viewport::Dialog, viewport::Selection, viewport::select_file.

When creating a viewport, you must specify the cursorwindow, the repaint handler, and you are optionally allowed to specify the position hint. The positions are as follows:

         viewport::tiled -- means that the window is part of the
                            "background" of the window and should
                            always be positioned in such a way as to
                            ensure that the windows touch one another
                            with no gaps.
      
         viewport::floating -- means that this is a pop-up style window
                               that can be anywhere and minor postion
                               round off errors should be ignored.  This
                               is typically only used for dialog windows.

The default value of the position is 'tiled'.

       Advice:  creating a viewport doesn't cause it to be painted -- or
                to become the active viewport.  Manually invoke the
                viewport's activate() method to force it to do both.
                Deactivation is fully automatic.  If you want a window to
                be active, call its activate method.  The currently active
                window will be deactivated automatically -- ie its
                repaint_handler will be invoked with cmd=deactivate.

The default mechanisms for handling viewport creation and destruction are:

          CursorWindow::new_viewport
          CursorWinddow::viewport::vsplit
          CursorWinddow::viewport::hsplit
          ~viewport

However these mechanisms should be viewed as tools for implementing an application specific behavior -- not defining a paradigm for proper use. The functions in the above list which return an auto_ptr<viewport> are returning a special kind of viewport which "owns" the physical screenspace. Deleting these viewport pointers also deletes the screen space (and invokes a resizing algorithm to cover the hole left by its deletion).

When you copy a viewport, however, you do not copy the screenspace, nor do you copy the ownership. That is, only the viewports returned by the above functions automatically clean up the screen space when the viewport is destructed. There is no way you can copy this feature. The destructor for copied viewports, constructed like this:

          extern alt_tools::auto_ptr<CursorWindow::viewport> realvp;
          viewport temp(*realvp.get());

do not clean up the screen space. However, the destruction of 'realvp' will free up the screen space.

In general, your application should make its own list of 'real' viewports and control the creation and destruction thereof to implement your own screen appearance. You can then treat the other viewports created via various queries as merely temporary objects to be used and then discarded without concern.

CursorWindow derives from Ostreamable -- which means that can be used as the target of operator<< for a small subset of the stream output operations. See Ostreamable for more details.

Definition at line 638 of file cursorwindow.h.


Member Typedef Documentation

typedef OstreamableBuffer<viewport , char , std::char_traits<char > > buf_type [inherited]

Definition at line 102 of file streamable.h.

typedef char char_type [inherited]

Definition at line 96 of file streamable.h.

typedef traits_type::int_type int_type [inherited]

Definition at line 98 of file streamable.h.

typedef traits_type::off_type off_type [inherited]

Definition at line 99 of file streamable.h.

typedef traits_type::pos_type pos_type [inherited]

Definition at line 100 of file streamable.h.

typedef std::char_traits<char > traits_type [inherited]

Definition at line 97 of file streamable.h.


Member Enumeration Documentation

enum position

A specification of how constrained the window position and size is.

Enumerator:
tiled 

Always align this window with others to establish a complete covering of the CursorWindow area.

floating 

let this window float around on the screen where it may

Definition at line 803 of file cursorwindow.h.


Constructor & Destructor Documentation

viewport ( CursorWindow ,
repaint_handler ,
position  p = tiled 
)

constructor

~viewport (  ) 

destructor

viewport ( viewport const &  r  ) 

Not for general use! only meant to be used by get_viewports() but it has a container that requires it! Darn!

Definition at line 3758 of file cursorwindow.cxx.

viewport ( port *   ) 

make a second viewport that uses the same port (safe but rarely needed )


Member Function Documentation

void activate (  ) 

repaint the window and give it a command of 'activate'.

Here is the caller graph for this function:

void beep (  ) 

Produce an audible alarm.

Here is the caller graph for this function:

void box ( int  width,
int  height,
bool  filled,
std::string  title 
)

Draw a box starting at the current cursor position that is width columns wide and height columns tall (running down from the current cursor position.

If the filled flag is true, the box will be filled with blanks before the border is drawn.

Draw the title string, if specified, inside the top border of the box to serve as a title.

Definition at line 960 of file cursorwindow.h.

Here is the call graph for this function:

void box ( int  width,
int  height,
bool  filled,
char const *  title = 0 
)

Draw a box starting at the current cursor position that is width columns wide and height columns tall (running down from the current cursor position.

If the filled flag is true, the box will be filled with blanks before the border is drawn.

Draw the title string, if specified, inside the top border of the box to serve as a title.

Definition at line 945 of file cursorwindow.h.

Here is the call graph for this function:

void box ( int  width,
int  height,
bool  filled,
char const *  title_string,
unsigned  length 
)

Draw a box starting at the current cursor position that is width columns wide and height columns tall (running down from the current cursor position.

If the filled flag is true, the box will be filled with blanks before the border is drawn.

If the string is not null, and the length is not 0, the string will be drawn inside the top border of the box to indicate that it is the 'title' of the box

Here is the caller graph for this function:

row_col curpos (  )  const

Get the current cursor position within the viewport.

Here is the caller graph for this function:

void fill_to_eol ( char  c = ' '  ) 

fill the rest of the current line, starting at the current cursor position, with a specified character -- defaulting to space.

Here is the caller graph for this function:

void fill_to_eos ( char  c = ' '  ) 

Here is the caller graph for this function:

CursorWindow::viewport::repaint_handler * get_repaint_handler (  ) 

Definition at line 3767 of file cursorwindow.cxx.

Here is the caller graph for this function:

std::auto_ptr<viewport> hsplit ( repaint_handler  ) 

Split the viewport horizontally and return handle to the right half. The repaint_handler you specify is used to handle repaint requests there. Note that if the window is too small to handle the request, you will receive a new viewport completely overlaying this viewport. Note that this is meant to be used with tiled viewports -- but you can manually move a viewport using the 'move()' method.

void move ( row_col  where,
row_col  size 
)

Move the viewport around within the CursorWindow. This call sets the position and size of the viewport. This will trigger a repaint of the whole cursor window when next input occurs -- with the cmd of 'resize'.

Here is the caller graph for this function:

viewport& operator= ( viewport const &  r  )  [private]

not implemented!

row_col origin (  )  const

Get the absolute position of the upper left corner of the viewport.

Here is the caller graph for this function:

void ostreamable_helper ( char  c  ) 

Definition at line 1026 of file cursorwindow.h.

Here is the call graph for this function:

void refresh (  ) 

Here is the caller graph for this function:

void restore_curpos (  ) 

Make sure the cursor is in the correct position for this viewport.

void set_curpos ( row_col  rc  ) 

Move the cursor to the specified row and column within the viewport.

void set_curpos ( int  row,
int  col 
)

Move the cursor to the specified row and column within the viewport.

Definition at line 857 of file cursorwindow.h.

Here is the caller graph for this function:

void set_repaint_handler ( repaint_handler r  ) 

Definition at line 3774 of file cursorwindow.cxx.

void set_text_attribute ( int   ) 

< Get the current text attribute of this viewport

Set the current text attribute of this view port.

Here is the caller graph for this function:

row_col size (  )  const

Get the width in columns and the height in rows of the viewport. Note that you cannot force this information but must live with the size you get. Well, ok, you can call 'move' which will force the size but generally this will mess up screen layout -- only do it as part of the resize_handler logic.

Here is the caller graph for this function:

int text_attribute (  )  const

< Fill the rest of the current VIEWPORT, starting at the current cursor position, with a specified character -- defaulting to space.

Here is the caller graph for this function:

std::auto_ptr<viewport> vsplit ( repaint_handler  ) 

Split the viewport vertically and return handle to the bottom half. The repaint_handler you specify is used to handle repaint requests there. Note that if the window is too small to handle the request, you will receive a new viewport completely overlaying this viewport. Note that this is meant to be used with tiled windows which are contiguous but you can move a viewport using the 'move()' method.

CursorWindow* window (  ) 

Get the window on which this viewport is drawn.

Here is the caller graph for this function:

void write ( long  c,
int  length = 1 
)

write specified number of characters to the window in the default text attribute at the current cursor position. The default repeat count is 1.

void write ( std::string const &  s,
size_t  length = 1000000 
)

Ditto.

Definition at line 909 of file cursorwindow.h.

Here is the call graph for this function:

void write ( char const *  s  ) 

Write a string in the current text attributes at the current cursor position and move the cursor -- all within the viewport.

Definition at line 901 of file cursorwindow.h.

Here is the call graph for this function:

void write ( char const *  ,
size_t  length 
)

Write a specified number of characters to the current cursor position and move the cursor -- all within the viewport.

void write ( Iterator  first,
Iterator  last 
)

Write text to the window.

Definition at line 891 of file cursorwindow.h.

Here is the caller graph for this function:


Friends And Related Function Documentation

friend class CursorWindow [friend]

Definition at line 1014 of file cursorwindow.h.


Member Data Documentation

bool owned_

indicates that when the viewport is destroyed, deleted the port. This is almost but not always true. The get_viewports() function sets this to false.

Definition at line 1009 of file cursorwindow.h.

port* port_

this variable should be private but my crufty old MSVC 6.0 compiler requires it to be public

Definition at line 1004 of file cursorwindow.h.


The documentation for this class was generated from the following files:
Generated on Wed Feb 29 22:54:05 2012 for CXXUtilities by  doxygen 1.6.3