1Tickit::Window(3pm) User Contributed Perl Documentation Tickit::Window(3pm)
2
6 "Tickit::Window" - a window for drawing operations
7
9 use Tickit;
10 use Tickit::Pen;
11 my $tickit = Tickit->new;
13 my $rootwin = $tickit->rootwin;
15 $rootwin->bind_event( expose => sub {
17 my ( $win, undef, $info ) = @_;
18 my $rb = $info->rb;
20 $rb->clear;
22 $rb->text_at(
24 int( $win->lines / 2 ), int( ($win->cols - 12) / 2 ),
25 "Hello, world"
26 );
27 });
28 $rootwin->bind_event( geomchange => sub { shift->expose } );
29 $rootwin->set_pen( Tickit::Pen->new( fg => "white" ) );
30 $rootwin->expose;
32 $tickit->run;
33
35 Provides coordination of widget drawing activities. A "Window"
36 represents a region of the screen that a widget occupies.
37 Windows cannot directly be constructed. Instead they are obtained by
39 sub-division of other windows, ultimately coming from the root window
40 associated with the terminal.
41 Normally all windows are visible, but a window may be hidden by calling
43 the "hide" method. After this, the window will not respond to any of
44 the drawing methods, until it is made visible again with the "show"
45 method. A hidden window will not receive focus or input events. It may
46 still receive geometry change events if it is resized.
47 Sub Windows
49 A division of a window made by calling "make_sub" or "make_float"
50 obtains a window that represents some portion of the drawing area of
51 the parent window. Child windows are stored in order; "make_sub" adds
52 a new child to the end of the list, and "make_float" adds one at the
53 start.
54 Higher windows (windows more towards the start of the list), will
56 always handle input events before lower siblings. The extent of windows
57 also obscures lower windows; drawing on lower windows may not be
58 visible because higher windows are above it.
59 Deferred Child Window Operations
61 In order to minimise the chances of ordering-specific bugs in window
62 event handlers that cause child window creation, reordering or
63 deletion, the actual child window list is only mutated after the event
64 processing has finished, by using a Tickit "later" block.
65
67 close
68 $win->close
69 Removes the window from its parent and clears any event handlers set
71 using bind_event. Also recursively closes any child windows.
72 Currently this is an optional method, as child windows are stored as
74 weakrefs, so should be destroyed when the last reference to them is
75 dropped. Widgets should make sure to call this method anyway, because
76 this will be changed in a future version.
77 make_sub
79 $sub = $win->make_sub( $top, $left, $lines, $cols )
80 Constructs a new sub-window of the given geometry, and places it at the
82 end of the child window list; below any other siblings.
83 make_hidden_sub
85 $sub = $win->make_hidden_sub( $top, $left, $lines, $cols )
86 Constructs a new sub-window like "make_sub", but the window starts
88 initially hidden. This avoids having to call "hide" separately
89 afterwards.
90 make_float
92 $float = $win->make_float( $top, $left, $lines, $cols )
93 Constructs a new sub-window of the given geometry, and places it at the
95 start of the child window list; above any other siblings.
96 make_popup
98 $popup = $win->make_popup( $top, $left, $lines, $cols )
99 Constructs a new floating popup window starting at the given
101 coordinates relative to this window. It will be sized to the given
102 limits.
103 This window will have the root window as its parent, rather than the
105 window the method was called on. Additionally, a popup window will
106 steal all keyboard and mouse events that happen, regardless of focus or
107 mouse position. It is possible that, if the window has an "on_mouse"
108 handler, that it may receive mouse events from outwide the bounds of
109 the window.
110 bind_event
112 $id = $win->bind_event( $ev, $code, $data )
113 Installs a new event handler to watch for the event specified by $ev,
115 invoking the $code reference when it occurs. $code will be invoked with
116 the given window, the event name, an event information object, and the
117 $data value it was installed with. "bind_event" returns an ID value
118 that may be used to remove the handler by calling "unbind_event_id".
119 $ret = $code->( $win, $ev, $info, $data )
121 The type of $info will depend on the kind of event that was received,
123 as indicated by $ev. The information structure types are documented in
124 Tickit::Event.
125 bind_event (with flags)
127 $id = $win->bind_event( $ev, $flags, $code, $data )
128 The $code argument may optionally be preceded by an integer of flag
130 values. This should be zero to apply default semantics, or a bitmask of
131 constants. The constants are documented in "bind_event (with flags)" in
132 Tickit::Term.
133 unbind_event_id
135 $win->unbind_event_id( $id )
136 Removes an event handler that returned the given $id value.
138 raise
140 $win->raise
141 lower
143 $win->lower
144 Moves the order of the window in its parent one higher or lower
146 relative to its siblings.
147 raise_to_front
149 $win->raise_to_front
150 Moves the order of the window in its parent to be the front-most among
152 its siblings.
153 lower_to_back
155 $win->lower_to_back
156 Moves the order of the window in its parent to be the back-most among
158 its siblings.
159 parent
161 $parentwin = $win->parent
162 Returns the parent window; i.e. the window on which "make_sub" or
164 "make_float" was called to create this one
165 subwindows
167 @windows = $win->subwindows
168 Returns a list of the subwindows of this one. They are returned in
170 order, highest first.
171 root
173 $rootwin = $win->root
174 Returns the root window
176 term
178 $term = $win->term
179 Returns the Tickit::Term instance of the terminal on which this window
181 lives.
182 Note that it is not guaranteed that this method will return the same
184 Perl-level terminal instance that the root window was constructed with.
185 In particular, if the root window in fact lives on a mock terminal
186 created by Tickit::Test::MockTerm this method may "forget" this fact,
187 returning an object instance simply in the "Tickit::Term" class
188 instead. While the instance will still be useable as a terminal, the
189 fact it was a mock terminal may get forgotten.
190 tickit
192 $tickit = $win->tickit
193 Returns the Tickit instance with which this window is associated.
195 show
197 $win->show
198 Makes the window visible. Allows drawing methods to output to the
200 terminal. Calling this method also exposes the window, invoking the
201 "on_expose" handler. Shows the cursor if this window currently has
202 focus.
203 hide
205 $win->hide
206 Makes the window invisible. Prevents drawing methods outputting to the
208 terminal. Hides the cursor if this window currently has focus.
209 is_visible
211 $visible = $win->is_visible
212 Returns true if the window is currently visible.
214 resize
216 $win->resize( $lines, $cols )
217 Change the size of the window.
219 reposition
221 $win->reposition( $top, $left )
222 Move the window relative to its parent.
224 change_geometry
226 $win->change_geometry( $top, $left, $lines, $cols )
227 A combination of "resize" and "reposition", to atomically change all
229 the coordinates of the window. Will only invoke "on_geom_changed" once,
230 rather than twice as would be the case calling the above methods
231 individually.
232 expose
234 $win->expose( $rect )
235 Marks the given region of the window as having been exposed, to invoke
237 the "on_expose" event handler on itself, and all its child windows. The
238 window's own handler will be invoked first, followed by all the child
239 windows, in screen order (top to bottom, then left to right).
240 If $rect is not supplied it defaults to exposing the entire window
242 area.
243 The "on_expose" event handler isn't invoked immediately; instead, the
245 "Tickit" "later" method is used to invoke it at the next round of IO
246 event handling. Until then, any other window could be exposed.
247 Duplicates are suppressed; so if a window and any of its ancestors are
248 both queued for expose, the actual handler will only be invoked once
249 per unique region of the window.
250 getctl
252 setctl
253 $value = $win->getctl( $ctl )
254 $success = $win->setctl( $ctl, $value )
256 Accessor and mutator for window control options. $ctl should be one of
258 the following options:
259 cursor-blink (bool)
261 cursor-shape (int)
262 cursor-visible (bool)
263 Cursor properties to set for the terminal cursor when this window
264 has input focus.
265 focus-child-notify (bool)
267 Whether the window will also receive focus events about child
268 windows.
269 steal-input (bool)
271 Whether the window is currently stealing input from its siblings.
272 set_focus_child_notify
274 $win->set_focus_child_notify( $notify )
275 If set to a true value, the "on_focus" event handler will also be
277 invoked when descendent windows gain or lose focus, in addition to when
278 it gains or loses focus itself. Defaults to false; meaning the
279 "on_focus" handler only receives notifications about the window itself.
280 top
282 bottom
283 left
284 right
285 $top = $win->top
286 $bottom = $win->bottom
288 $left = $win->left
290 $right = $win->right
292 Returns the coordinates of the start of the window, relative to the
294 parent window.
295 abs_top
297 abs_left
298 $top = $win->abs_top
299 $left = $win->abs_left
301 Returns the coordinates of the start of the window, relative to the
303 root window.
304 cols
306 lines
307 $cols = $win->cols
308 $lines = $win->lines
310 Obtain the size of the window
312 selfrect
314 $rect = $win->selfrect
315 Returns a Tickit::Rect containing representing the window's extent
317 within itself. This will have "top" and "left" equal to 0.
318 rect
320 $rect = $win->rect
321 Returns a Tickit::Rect containing representing the window's extent
323 relative to its parent
324 pen
326 $pen = $win->pen
327 Returns the current Tickit::Pen object associated with this window
329 set_pen
331 $win->set_pen( $pen )
332 Replace the current Tickit::Pen object for this window with a new one.
334 The object reference will be stored, allowing it to be shared with
335 other objects. If "undef" is set, then a new, blank pen will be
336 constructed.
337 getpenattr
339 $val = $win->getpenattr( $attr )
340 Returns a single attribue from the current pen
342 get_effective_pen
344 $pen = $win->get_effective_pen
345 Returns a new Tickit::Pen containing the effective pen attributes for
347 the window, combined by those of all its parents.
348 get_effective_penattr
350 $val = $win->get_effective_penattr( $attr )
351 Returns the effective value of a pen attribute. This will be the value
353 of this window's attribute if set, or the effective value of the
354 attribute from its parent.
355 scrollrect
357 $success = $win->scrollrect( $rect, $downward, $rightward )
358 $success = $win->scrollrect( $top, $left, $lines, $cols, $downward, $rightward )
360 $success = $win->scrollrect( ..., $pen )
362 $success = $win->scrollrect( ..., %attrs )
364 Attempt to scroll the rectangle of the window (either given by a
366 "Tickit::Rect" or defined by the first four parameters) by an amount
367 given by the latter two. Since most terminals cannot perform arbitrary
368 rectangle scrolling, this method returns a boolean to indicate if it
369 was successful. The caller should test this return value and fall back
370 to another drawing strategy if the attempt was unsuccessful.
371 Optionally, a "Tickit::Pen" instance or hash of pen attributes may be
373 provided, to override the background colour used for erased sections
374 behind the scroll.
375 The cursor may move as a result of calling this method; its location is
377 undefined if this method returns successful. The terminal pen, in
378 particular the background colour, may be modified by this method even
379 if it fails to scroll the terminal (and returns false).
380 This method will enqueue all of the required expose requests before
382 returning, so in this case the return value is not interesting.
383 scroll
385 $success = $win->scroll( $downward, $rightward )
386 A shortcut for calling "scrollrect" on the entire region of the window.
388 scroll_with_children
390 $win->scroll_with_children( $downward, $rightward )
391 Similar to "scroll" but ignores child windows of this one, moving all
393 of the terminal content paying attention only to obscuring by newer
394 siblings of ancestor windows.
395 This method is experimental, intended only for use by
397 Tickit::Widget::ScrollBox. After calling this method, the terminal
398 content will have moved and the windows drawing them will be confused
399 unless the window position was also updated. "ScrollBox" takes care to
400 do this.
401 cursor_at
403 $win->cursor_at( $line, $col )
404 Sets the position in the window at which the terminal cursor will be
406 placed if this window has focus. This method does not force the window
407 to take the focus though; for that see "take_focus".
408 cursor_visible
410 $win->cursor_visible( $visible )
411 Sets whether the terminal cursor is visible on the window when it has
413 focus. Normally it is, but passing a false value will make the cursor
414 hidden even when the window is focused.
415 cursor_shape
417 $win->cursor_shape( $shape )
418 Sets the shape that the terminal cursor will have if this window has
420 focus. This method does not force the window to take the focus though;
421 for that see "take_focus". Valid values for $shape are the various
422 "CURSORSHAPE_*" constants from Tickit::Term.
423 take_focus
425 $win->take_focus
426 Causes this window to take the input focus, and updates the cursor
428 position to the stored active position given by "cursor_at".
429 focus
431 $win->focus( $line, $col )
432 A convenient shortcut combining "cursor_at" with "take_focus"; setting
434 the focus cursor position and taking the input focus.
435 is_focused
437 $focused = $win->is_focused
438 Returns true if this window currently has the input focus
440 is_steal_input
442 $steal = $win->is_steal_input
443 Returns true if this window is currently stealing input from its
445 siblings
446 set_steal_input
448 $win->set_steal_input( $steal )
449 Controls whether this window is currently stealing input from its
451 siblings
452
454 The following event types are emitted and may be observed by
455 "bind_event".
456 key
458 Emitted when a key on the keyboard is pressed while this window or one
459 of its child windows has the input focus, or is set to steal input
460 anyway.
461 The event handler should return a true value if it considers the
463 keypress dealt with, or false to pass it up to its parent window.
464 Before passing it to its parent, a window will also try any other non-
466 focused sibling windows of the currently-focused window in order of
467 creation (though note this order is not necessarily the order the child
468 widgets that own those windows were created or added to their
469 container).
470 If no window actually handles the keypress, then every window will
472 eventually be consulted about it, preferring windows closer to the
473 focused one.
474 This broadcast-like behaviour allows widgets to handle keypresses that
476 should make sense even though their window does not actually have the
477 keyboard focus. This feature should be used sparingly, to only capture
478 one or two keypresses that really make sense; for example to capture
479 the "PageUp" and "PageDown" keys in a scrolling list, or a numbered
480 function key that performs some special action.
481 mouse
483 Emitted when a mouse button is pressed or released, the cursor moved
484 while a button is held (a dragging event), or the wheel is scrolled.
485 The following event names may be observed:
487 press A mouse button has been pressed down on this cell
489 drag_start
491 The mouse was moved while a button was held, and was initially
492 in the given cell
493 drag The mouse was moved while a button was held, and is now in the
495 given cell
496 drag_outside
498 The mouse was moved outside of the window that handled the
499 "drag_start" event, and is still being dragged.
500 drag_drop
502 A mouse button was released after having been moved, while in
503 the given cell
504 drag_stop
506 The drag operation has finished. This event is always given
507 directly to the window that handled the "drag_start" event,
508 rather than the window on which the mouse release event
509 happened.
510 release A mouse button was released after being pressed
512 wheel The mouse wheel was moved. "button" will indicate the wheel
514 direction as a string "up" or "down".
515 The invoked code should return a true value if it considers the mouse
517 event dealt with, or false to pass it up to its parent window.
518 Once a dragging operation has begun via "drag_start", the window that
520 handled the event will always receive "drag", "drag_outside", and an
521 eventual "drag_stop" event even if the mouse moves outside that window.
522 No other window will receive a "drag_outside" or "drag_stop" event than
523 the one that started the operation.
524 geomchange
526 Emitted when the window is resized or repositioned; i.e. whenever its
527 geometry changes.
528 expose
530 Emitted when a region of the window is exposed by the expose method, or
531 implicitly because it or another window has changed size, been shown or
532 hidden, or the stacking order has been changed.
533 When invoked, render buffer passed in the event will have its origin
535 set to that of the window, and its clipping will be set to the damage
536 rectangle.
537 If any child windows overlap the region, these will be exposed first,
539 before the containing window.
540 focus
542 Emitted when the window gains or loses input focus.
543 If the "focus-child-notify" behavior is enabled, this callback is also
545 invoked for changes of focus on descendent windows. In this case, it is
546 passed an additional argument, being the immediate child window in
547 which the focus chain has now changed (which may or may not be the
548 focused window directly; it could itself be another ancestor).
549 When a window gains focus, any of its ancestors that have
551 "focus-child-notify" enabled will be informed first, from the outermost
552 inwards, before the window itself. When one loses focus, it is notified
553 first, and then its parents from the innermost outwards.
554
556 Paul Evans <leonerd@leonerd.org.uk>
557perl v5.38.0 2023-07-21 Tickit::Window(3pm)