1Tickit::Window(3pm)   User Contributed Perl Documentation  Tickit::Window(3pm)
2
3
4

NAME

6       "Tickit::Window" - a window for drawing operations
7

SYNOPSIS

9        use Tickit;
10        use Tickit::Pen;
11
12        my $tickit = Tickit->new;
13
14        my $rootwin = $tickit->rootwin;
15
16        $rootwin->bind_event( expose => sub {
17           my ( $win, undef, $info ) = @_;
18
19           my $rb = $info->rb;
20
21           $rb->clear;
22
23           $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
31        $rootwin->expose;
32        $tickit->run;
33

DESCRIPTION

35       Provides coordination of widget drawing activities. A "Window"
36       represents a region of the screen that a widget occupies.
37
38       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
42       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
48   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
55       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
60   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

METHODS

67   close
68          $win->close
69
70       Removes the window from its parent and clears any event handlers set
71       using bind_event. Also recursively closes any child windows.
72
73       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
78   make_sub
79          $sub = $win->make_sub( $top, $left, $lines, $cols )
80
81       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
84   make_hidden_sub
85          $sub = $win->make_hidden_sub( $top, $left, $lines, $cols )
86
87       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
91   make_float
92          $float = $win->make_float( $top, $left, $lines, $cols )
93
94       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
97   make_popup
98          $popup = $win->make_popup( $top, $left, $lines, $cols )
99
100       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
104       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
111   bind_event
112          $id = $win->bind_event( $ev, $code, $data )
113
114       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
120        $ret = $code->( $win, $ev, $info, $data )
121
122       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
126   bind_event (with flags)
127          $id = $win->bind_event( $ev, $flags, $code, $data )
128
129       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
134   unbind_event_id
135          $win->unbind_event_id( $id )
136
137       Removes an event handler that returned the given $id value.
138
139   raise
140          $win->raise
141
142   lower
143          $win->lower
144
145       Moves the order of the window in its parent one higher or lower
146       relative to its siblings.
147
148   raise_to_front
149          $win->raise_to_front
150
151       Moves the order of the window in its parent to be the front-most among
152       its siblings.
153
154   lower_to_back
155          $win->lower_to_back
156
157       Moves the order of the window in its parent to be the back-most among
158       its siblings.
159
160   parent
161          $parentwin = $win->parent
162
163       Returns the parent window; i.e. the window on which "make_sub" or
164       "make_float" was called to create this one
165
166   subwindows
167          @windows = $win->subwindows
168
169       Returns a list of the subwindows of this one. They are returned in
170       order, highest first.
171
172   root
173          $rootwin = $win->root
174
175       Returns the root window
176
177   term
178          $term = $win->term
179
180       Returns the Tickit::Term instance of the terminal on which this window
181       lives.
182
183       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
191   tickit
192          $tickit = $win->tickit
193
194       Returns the Tickit instance with which this window is associated.
195
196   show
197          $win->show
198
199       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
204   hide
205          $win->hide
206
207       Makes the window invisible. Prevents drawing methods outputting to the
208       terminal. Hides the cursor if this window currently has focus.
209
210   is_visible
211          $visible = $win->is_visible
212
213       Returns true if the window is currently visible.
214
215   resize
216          $win->resize( $lines, $cols )
217
218       Change the size of the window.
219
220   reposition
221          $win->reposition( $top, $left )
222
223       Move the window relative to its parent.
224
225   change_geometry
226          $win->change_geometry( $top, $left, $lines, $cols )
227
228       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
233   expose
234          $win->expose( $rect )
235
236       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
241       If $rect is not supplied it defaults to exposing the entire window
242       area.
243
244       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
251   getctl
252   setctl
253          $value = $win->getctl( $ctl )
254
255          $success = $win->setctl( $ctl, $value )
256
257       Accessor and mutator for window control options. $ctl should be one of
258       the following options:
259
260       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
266       focus-child-notify (bool)
267           Whether the window will also receive focus events about child
268           windows.
269
270       steal-input (bool)
271           Whether the window is currently stealing input from its siblings.
272
273   set_focus_child_notify
274          $win->set_focus_child_notify( $notify )
275
276       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
281   top
282   bottom
283   left
284   right
285          $top    = $win->top
286
287          $bottom = $win->bottom
288
289          $left   = $win->left
290
291          $right  = $win->right
292
293       Returns the coordinates of the start of the window, relative to the
294       parent window.
295
296   abs_top
297   abs_left
298          $top  = $win->abs_top
299
300          $left = $win->abs_left
301
302       Returns the coordinates of the start of the window, relative to the
303       root window.
304
305   cols
306   lines
307          $cols  = $win->cols
308
309          $lines = $win->lines
310
311       Obtain the size of the window
312
313   selfrect
314          $rect = $win->selfrect
315
316       Returns a Tickit::Rect containing representing the window's extent
317       within itself. This will have "top" and "left" equal to 0.
318
319   rect
320          $rect = $win->rect
321
322       Returns a Tickit::Rect containing representing the window's extent
323       relative to its parent
324
325   pen
326          $pen = $win->pen
327
328       Returns the current Tickit::Pen object associated with this window
329
330   set_pen
331          $win->set_pen( $pen )
332
333       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
338   getpenattr
339          $val = $win->getpenattr( $attr )
340
341       Returns a single attribue from the current pen
342
343   get_effective_pen
344          $pen = $win->get_effective_pen
345
346       Returns a new Tickit::Pen containing the effective pen attributes for
347       the window, combined by those of all its parents.
348
349   get_effective_penattr
350          $val = $win->get_effective_penattr( $attr )
351
352       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
356   scrollrect
357          $success = $win->scrollrect( $rect, $downward, $rightward )
358
359          $success = $win->scrollrect( $top, $left, $lines, $cols, $downward, $rightward )
360
361          $success = $win->scrollrect( ..., $pen )
362
363          $success = $win->scrollrect( ..., %attrs )
364
365       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
372       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
376       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
381       This method will enqueue all of the required expose requests before
382       returning, so in this case the return value is not interesting.
383
384   scroll
385          $success = $win->scroll( $downward, $rightward )
386
387       A shortcut for calling "scrollrect" on the entire region of the window.
388
389   scroll_with_children
390          $win->scroll_with_children( $downward, $rightward )
391
392       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
396       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
402   cursor_at
403          $win->cursor_at( $line, $col )
404
405       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
409   cursor_visible
410          $win->cursor_visible( $visible )
411
412       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
416   cursor_shape
417          $win->cursor_shape( $shape )
418
419       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
424   take_focus
425          $win->take_focus
426
427       Causes this window to take the input focus, and updates the cursor
428       position to the stored active position given by "cursor_at".
429
430   focus
431          $win->focus( $line, $col )
432
433       A convenient shortcut combining "cursor_at" with "take_focus"; setting
434       the focus cursor position and taking the input focus.
435
436   is_focused
437          $focused = $win->is_focused
438
439       Returns true if this window currently has the input focus
440
441   is_steal_input
442          $steal = $win->is_steal_input
443
444       Returns true if this window is currently stealing input from its
445       siblings
446
447   set_steal_input
448          $win->set_steal_input( $steal )
449
450       Controls whether this window is currently stealing input from its
451       siblings
452

EVENTS

454       The following event types are emitted and may be observed by
455       "bind_event".
456
457   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
462       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
465       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
471       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
475       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
482   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
486       The following event names may be observed:
487
488       press   A mouse button has been pressed down on this cell
489
490       drag_start
491               The mouse was moved while a button was held, and was initially
492               in the given cell
493
494       drag    The mouse was moved while a button was held, and is now in the
495               given cell
496
497       drag_outside
498               The mouse was moved outside of the window that handled the
499               "drag_start" event, and is still being dragged.
500
501       drag_drop
502               A mouse button was released after having been moved, while in
503               the given cell
504
505       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
511       release A mouse button was released after being pressed
512
513       wheel   The mouse wheel was moved. "button" will indicate the wheel
514               direction as a string "up" or "down".
515
516       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
519       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
525   geomchange
526       Emitted when the window is resized or repositioned; i.e. whenever its
527       geometry changes.
528
529   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
534       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
538       If any child windows overlap the region, these will be exposed first,
539       before the containing window.
540
541   focus
542       Emitted when the window gains or loses input focus.
543
544       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
550       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

AUTHOR

556       Paul Evans <leonerd@leonerd.org.uk>
557
558
559
560perl v5.38.0                      2023-07-21               Tickit::Window(3pm)
Impressum