NAME

Tickit::Window - a window for drawing operations

SYNOPSIS

DESCRIPTION

Provides coordination of widget drawing activities. A Window represents a region of the screen that a widget occupies.

Windows cannot directly be constructed. Instead they are obtained by sub-division of other windows, ultimately coming from the root window associated with the terminal.

Normally all windows are visible, but a window may be hidden by calling the hide method. After this, the window will not respond to any of the drawing methods, until it is made visible again with the show method. A hidden window will not receive focus or input events. It may still receive geometry change events if it is resized.

Sub Windows and Floating Windows

A division of a window made by calling make_sub obtains a window that represents some portion of the drawing area of the parent window. All sibling subdivisions are considered equal; if they happen to overlap then it is undefined how input events on overlapping regions are handled among them, or how drawing may interact. It is recommended that make_sub be used to obtain only windows that cover non-overlapping areas of the parent; such as to distribute space within a container.

By comparison, any window created by make_float is considered to sit "above" the area of its parent. It will always handle input events before other siblings, and any drawing that happens within it overwrites that of its non-floating siblings. Any drawing on a non-floating sibling that happens within the area of a float is obscured by the contents of the floating window. It is recommended that use of floating windows be kept to a minimum, as each one imposes a small processing-time overhead in any drawing operations on other window. These may be useful for implementing pop-up menus or other temporary interactions.

METHODS

$sub = $win->make_sub( $top, $left, $lines, $cols )

Constructs a new sub-window starting at the given coordinates of this window. It will be sized to the given limits.

$float = $win->make_float( $top, $left, $lines, $cols )

Constructs a new floating child window starting at the given coordinates of this window. It will be sized to the given limits.

$parentwin = $win->parent

Returns the parent window; i.e. the window on which make_sub or make_float was called to create this one

$rootwin = $win->root

Returns the root window

$term = $win->term

Returns the Tickit::Term instance of the terminal on which this window lives.

Returns the Tickit instance with which this window is associated.

$win->show

Makes the window visible. Allows drawing methods to output to the terminal. Calling this method also exposes the window, invoking the on_expose handler. Shows the cursor if this window currently has focus.

$win->hide

Makes the window invisible. Prevents drawing methods outputting to the terminal. Hides the cursor if this window currently has focus.

$visible = $win->is_visible

Returns true if the window is currently visible.

$win->resize( $lines, $cols )

Change the size of the window.

$win->reposition( $top, $left )

Move the window relative to its parent.

$win->change_geometry( $top, $left, $lines, $cols )

A combination of resize and reposition, to atomically change all the coordinates of the window. Will only invoke on_geom_changed once, rather than twice as would be the case calling the above methods individually.

$win->set_on_geom_changed( $on_geom_changed )

Set the callback to invoke whenever the window is resized or repositioned; i.e. whenever its geometry changes.

 $on_geom_changed->( $win )

$win->set_on_key( $on_key )

Set the callback to invoke whenever a key is pressed while this window, or one of its child windows, has the input focus.

 $handled = $on_key->( $win, $type, $str, $key )

$type will be text for normal unmodified Unicode, or key for special keys or modified Unicode. $str will be the UTF-8 string for text events, or the textual description of the key as rendered by Term::TermKey for key events. $key will be the underlying Term::TermKey::Key event structure.

The invoked code should return a true value if it considers the keypress dealt with, or false to pass it up to its parent window.

Before passing it to its parent, a window will also try any other non-focused sibling windows of the currently-focused window in order of creation (though note this order is not necessarily the order the child widgets that own those windows were created or added to their container).

If no window actually handles the keypress, then every window will eventually be consulted about it, preferring windows closer to the focused one.

This broadcast-like behaviour allows widgets to handle keypresses that should make sense even though their window does not actually have the keyboard focus. This feature should be used sparingly, to only capture one or two keypresses that really make sense; for example to capture the PageUp and PageDown keys in a scrolling list, or a numbered function key that performs some special action.

$win->set_on_mouse( $on_mouse )

Set the callback to invoke whenever a mouse event is received within the window's rectangle.

 $handled = $on_mouse->( $win, $ev, $buttons, $line, $col )

$ev will be press, drag or release. The button number will be in $button, though may not be present for release events. $line and $col are 0-based. Behaviour of events involving more than one mouse button is not well-specified by terminals.

The invoked code should return a true value if it considers the mouse event dealt with, or false to pass it up to its parent window. The mouse event is passed as defined by Tickit::Term's on_mouse event, except that the line and column counts will be relative to the window, not to the screen.

$win->set_on_expose( $on_expose )

Set the callback to invoke whenever a region of the window is exposed by the expose event.

 $on_expose->( $win, $rect )

Will be passed a Tickit::Rect representing the exposed region.

$win->expose

Marks the window as having been exposed, to invoke the on_expose event handler on itself, and all its child windows. The window's own handler will be invoked first, followed by all the child windows, in screen order (top to bottom, then left to right).

The on_expose event handler isn't invoked immediately; instead, the Tickit later method is used to invoke it at the next round of IO event handling. Until then, any other window could be exposed. Duplicates are suppressed; so if a window and any of its ancestors are both queued for expose, the actual handler will only be invoked once.

$top = $win->top

$left = $win->left

Returns the coordinates of the start of the window, relative to the parent window.

$top = $win->abs_top

$left = $win->abs_left

Returns the coordinates of the start of the window, relative to the root window.

$cols = $win->cols

$lines = $win->lines

Obtain the size of the window

$rect = $win->rect

Returns a Tickit::Rect containing representing the window's extent relative to its parent

$pen = $win->pen

Returns the current Tickit::Pen object associated with this window

$win->set_pen( $pen )

Replace the current Tickit::Pen object for this window with a new one. The object reference will be stored, allowing it to be shared with other objects. If undef is set, then a new, blank pen will be constructed.

$val = $win->getpenattr( $attr )

Returns a single attribue from the current pen

%attrs = $win->getpenattrs

Retrieve the current pen settings for the window.

This method is now deprecated and should not be used; instead use

 $win->pen->getattrs

$pen = $win->get_effective_pen

Returns a new Tickit::Pen containing the effective pen attributes for the window, combined by those of all its parents.

$val = $win->get_effective_penattr( $attr )

Returns the effective value of a pen attribute. This will be the value of this window's attribute if set, or the effective value of the attribute from its parent.

%attrs = $win->get_effective_penattrs

Retrieve the effective pen settings for the window. This will be the settings of the window and all its parents down to the root window, merged together.

This method is now deprecated and should not be used; instead use

 $win->get_effective_pen->getattrs

$win->goto( $line, $col )

Moves the cursor to the given position within the window. Both $line and $col are 0-based.

$win->print( $text, $pen )

$win->print( $text, %attrs )

Print the given text to the terminal at the current cursor position using the pen of the window, possibly overridden by any extra attributes in the given Tickit::Pen instance, or directly in the given hash, if one is provided.

$win->erasech( $count, $moveend, $pen )

$win->erasech( $count, $moveend, %attrs )

Erase $count columns forwards. If $moveend is true, the cursor will be placed at the end of the erased region. If defined but false, it will not move from its current location. If undefined, the terminal will take which ever option it can implement most efficiently.

If a Tickit::Pen or pen attributes are provided, they are used to override the background colour for the erased region.

$success = $win->scrollrect( $top, $left, $lines, $cols, $downward, $rightward )

$success = $win->scrollrect( ..., $pen )

$success = $win->scrollrect( ..., %attrs )

Attempt to scroll the rectangle of the window defined by the first four parameters by an amount given by the latter two. Since most terminals cannot perform arbitrary rectangle scrolling, this method returns a boolean to indicate if it was successful. The caller should test this return value and fall back to another drawing strategy if the attempt was unsuccessful.

Optionally, a Tickit::Pen instance or hash of pen attributes may be provided, to override the background colour used for erased sections behind the scroll.

The cursor may move as a result of calling this method; its location is undefined if this method returns successful. The terminal pen, in particular the background colour, may be modified by this method even if it fails to scroll the terminal (and returns false).

$success = $win->scroll( $downward, $rightward )

A shortcut for calling scrollrect on the entire region of the window.

$win->focus( $line, $col )

Put the cursor at the given position in this window. Ensures the cursor remains at this position after drawing.

$win->restore

Restore the state of the terminal to its idle state. Places the cursor back at the focus position, and restores the pen.

$win->clearline( $line )

Erase the entire content of one line of the window

$win->clear

Erase the entire content of the window and reset it to the current background colour.

AUTHOR

Paul Evans <leonerd@leonerd.org.uk>

cpanm Tickit

perl -MCPAN -e shell
install Tickit