1Curses::UI::Widget(3) User Contributed Perl DocumentationCurses::UI::Widget(3)
2
6 Curses::UI::Widget - The base class for all widgets
7
9 Curses::UI::Widget - base class
10
12 This class is not used directly by somebody who is building an
13 application using Curses::UI. It's a base class that is expanded by the
14 Curses::UI widgets. See WIDGET STRUCTURE below for a basic widget
15 framework.
16 use Curses::UI::Widget;
18 my $widget = new Curses::UI::Widget(
19 -width => 15,
20 -height => 5,
21 -border => 1,
22 );
23
25 The standard options for (most) widgets are the options that are
26 enabled by this class. So this class doesn't really have standard
27 options.
28
30 GENERAL:
31 • -parent < OBJECTREF >
32 This option specifies parent of the object. This parent is the
34 object (Curses::UI, Window, Widget(descendant), etc.) in which the
35 widget is drawn.
36 • -intellidraw < BOOLEAN >
38 If BOOLEAN has a true value (which is the default), the intellidraw
40 method (see below) will be suported. This option is mainly used in
41 widget building.
42 • -userdata < SCALAR >
44 This option specifies a user data that can be retrieved with the
46 userdata() method. It is useful to store application's internal
47 data that otherwise would not be accessible in callbacks.
48 • -border < BOOLEAN >
50 Each widget can be drawn with or without a border. To enable the
52 border use a true value and to disable it use a false value for
53 BOOLEAN. The default is not to use a border.
54 • -sbborder < BOOLEAN >
56 If no border is used, a square bracket border may be used. This is
58 a border which is constructed from '[' and ']' characters. This
59 type of border is especially useful for single line widgets (like
60 text entries and popup boxes). A square bracket border can only be
61 enabled if -border is false. The default is not to use a square
62 bracket border.
63 POSITIONING:
65 +---------------------------------------------------+
66 | parent ^ |
67 | | |
68 | y |
69 | | |
70 | v |
71 | ^ |
72 | | |
73 | padtop |
74 | | |
75 | v |
76 | +- TITLE -------+ |
77 | | widget ^ | |
78 | | | | |
79 | | | | |
80 |<--x--><--padleft-->|<----width---->|<--padright-->|
81 | | | | |
82 | | | | |
83 | | height | |
84 | | v | |
85 | +---------------+ |
86 | ^ |
87 | | |
88 | padbottom |
89 | | |
90 | v |
91 +---------------------------------------------------+
92 • -x < VALUE >
94 The x-position of the widget, relative to the parent. The default
96 is 0.
97 • -y < VALUE >
99 The y-position of the widget, relative to the parent. The default
101 is 0.
102 • -width < VALUE >
104 The width of the widget. If the width is undefined or -1, the
106 maximum available width will be used. By default the widget will
107 use the maximum available width.
108 • -height < VALUE >
110 The height of the widget. If the height is undefined or -1, the
112 maximum available height will be used. By default the widget will
113 use the maximum available height.
114 PADDING:
116 • -pad < VALUE >
117 • -padtop < VALUE >
119 • -padbottom < VALUE >
121 • -padleft < VALUE >
123 • -padright < VALUE >
125 With -pad you can specify the default padding outside the widget
127 (the default value for -pad is 0). Using one of the -pad... options
128 that have a direction in them, you can override the default
129 padding.
130 • -ipad < VALUE >
132 • -ipadtop < VALUE >
134 • -ipadbottom < VALUE >
136 • -ipadleft < VALUE >
138 • -ipadright < VALUE >
140 These are almost the same as the -pad... options, except these
142 options specify the padding _inside_ the widget. Normally the
143 available effective drawing area for a widget will be the complete
144 area if no border is used or else the area within the border.
145 TITLE:
147 Remark:
148 A title is drawn in the border of a widget. So a title will only be
150 available if -border is true.
151 • -title < TEXT >
153 Set the title of the widget to TEXT. If the text is longer then the
155 available width, it will be clipped.
156 • -titlereverse < BOOLEAN >
158 The title can be drawn in normal or in reverse type. If
160 -titlereverse is true, the text will be drawn in reverse type. The
161 default is to use reverse type.
162 • -titlefullwidth < BOOLEAN >
164 If -titlereverse is true, the title can be stretched to fill the
166 complete width of the widget by giving -titlefullwidth a true
167 value. By default this option is disabled.
168 SCROLLBARS:
170 Remark:
171 Since the user of a Curses::UI program has no real control over the so
173 called "scrollbars", they aren't really scrollbars. A better name would
174 be something like "document location indicators". But since they look
175 so much like scrollbars I decided I could get away with this naming
176 convention.
177 • -vscrollbar < VALUE >
179 VALUE can be 'left', 'right', another true value or false.
181 If -vscrollbar has a true value, a vertical scrollbar will be drawn
183 by the widget. If this true value happens to be "left", the
184 scrollbar will be drawn on the left side of the widget. In all
185 other cases it will be drawn on the right side. The default is not
186 to draw a vertical scrollbar.
187 For widget programmers: To control the scrollbar, the widget data
189 -vscrolllen (the total length of the content of the widget) and
190 -vscrollpos (the current position in the document) should be set.
191 If Curses::UI::Widget::draw is called, the scrollbar will be drawn.
192 • -hscrollbar < VALUE >
194 VALUE can be 'top', 'bottom', another true value or false.
196 If -hscrollbar has a true value, a horizontal scrollbar will be
198 drawn by the widget. If this true value happens to be "top", the
199 scrollbar will be drawn at the top of the widget. In all other
200 cases it will be drawn at the bottom. The default is not to draw a
201 horizontal scrollbar.
202 For widget programmers: To control the scrollbar, the widget data
204 -hscrolllen (the maximum width of the content of the widget) and
205 -hscrollpos (the current horizontal position in the document)
206 should be set. If Curses::UI::Widget::draw is called, the scrollbar
207 will be drawn.
208 EVENTS
210 • -onfocus < CODEREF >
211 This sets the onFocus event handler for the widget. If the widget
213 gets the focus, the code in CODEREF will be executed. It will get
214 the widget reference as its argument.
215 • -onblur < CODEREF >
217 This sets the onBlur event handler for the widget. If the widget
219 loses the focus, the code in CODEREF will be executed. It will get
220 the widget reference as its argument.
221
223 • new ( OPTIONS )
224 Create a new Curses::UI::Widget instance using the options in HASH.
226 • layout ( )
228 Layout the widget. Compute the size the widget needs and see if it
230 fits. Create the curses windows that are needed for the widget (the
231 border and the effective drawing area).
232 • draw ( BOOLEAN )
234 Draw the Curses::UI::Widget. If BOOLEAN is true, the screen will
236 not update after drawing. By default this argument is false, so the
237 screen will update after drawing the widget.
238 • intellidraw ( )
240 If the widget is visible (it is not hidden and it is in the window
242 that is currently on top) and if intellidraw is not disabled for it
243 (-intellidraw has a true value) it is drawn and the curses routine
244 doupdate() will be called to update the screen.
245 This is useful if you change something in a widget and want it to
247 update its state. If you simply call draw() and doupdate()
248 yourself, then the widget will also be drawn if it is on a window
249 that is currently not on top. This would result in the widget being
250 drawn right through the contents of the window that is currently on
251 top.
252 • focus ( )
254 Give focus to the widget. In Curses::UI::Widget, this method
256 immediately returns, so the widget will not get focused. A derived
257 class that needs focus, must override this method.
258 • focusable ( [BOOLEAN] )
260 If BOOLEAN is set to a true value the widget will be focusable,
262 false will make it unfocusable. If not argument is given, it will
263 return the current state.
264 • lose_focus ( )
266 This method makes the current widget lose it's focus. It returns
268 the current widget.
269 • modalfocus ( )
271 Gives the widget a modal focus, i.e. no other widget can be active
273 till this widget is removed.
274 • title ( TEXT )
276 Change the title that is shown in the border of the widget to TEXT.
278 • width ( )
280 • height ( )
282 These methods return the total width and height of the widget.
284 This is the space that the widget itself uses plus the space that
285 is used by the outside padding.
286 • borderwidth ( )
288 • borderheight ( )
290 These methods return the width and the height of the border of the
292 widget.
293 • canvaswidth ( )
295 • canvasheight ( )
297 These methods return the with and the height of the effective
299 drawing area of the widget. This is the area where the draw()
300 method of a widget may draw the contents of the widget (BTW: the
301 curses window that is associated to this drawing area is
302 $this->{-canvasscr}).
303 • width_by_windowscrwidth ( NEEDWIDTH, OPTIONS )
305 • height_by_windowscrheight ( NEEDHEIGHT, OPTIONS )
307 These methods are exported by this module. These can be used in
309 child classes to easily compute the total width/height the widget
310 needs in relation to the needed width/height of the effective
311 drawing area ($this->{-canvasscr}). The OPTIONS contains the
312 options that will be used to create the widget. So if we want a
313 widget that has a drawing area height of 1 and that has a border,
314 the -height option can be computed using something like:
315 my $height = height_by_windowscrheight(1, -border => 1);
317 • generic_focus ( BLOCKTIME, CTRLKEYS, CURSOR, PRECALLBACK )
319 For most widgets the generic_focus method will be enough to handle
321 focusing. This method will do the following:
322 It starts a loop for reading keyboard input from the user. At the
324 start of this loop the PRECALLBACK is called. This callback can for
325 example be used for layouting the widget. Then, the widget is
326 drawn.
327 Now a key is read or if the DO_KEY:<key> construction was used, the
329 <key> will be used as if it was read from the keyboard (you can
330 find more on this construction below). If the DO_KEY:<key>
331 construction was not used, a key is read using the get_key method
332 which is in Curses::UI::Common. The arguments BLOCKTIME, CTRLKEYS
333 and CURSOR are passed to get_key.
334 Now the key is checked. If the value of the key is -1, get_key did
336 not read a key at all. In that case, the program will go back to
337 the start of the loop.
338 As soon as a key is read, this key will be handed to the
340 process_bindings method (see below). The returnvalue of this method
341 (called RETURN from now on) will be used to determine what to do
342 next. We have the following cases:
343 * RETURN matches DO_KEY:<key>
345 The <key> is extracted from RETURN. The loop is restarted and <key>
347 will be used as if it was entered using the keyboard.
348 * RETURN is a CODE reference
350 RETURN will be returned to the caller of generic_focus. This will
352 have the widget lose its focus. The caller then can execute the
353 code.
354 * RETURN is a SCALAR value
356 RETURN will be returned to the caller of generic_focus. This will
358 have the widget lose its focus.
359 * anything else
361 The widget will keep its focus. The loop will be restarted all over
363 again. So, if you are writing a binding routine for a widget, you
364 can have the focus to stay at the widget by returning the widget
365 instance itself. Example:
366 sub myroutine() {
368 my $this = shift;
369 .... do your thing ....
370 return $this;
371 }
372 • process_bindings ( KEY )
374 KEY -> maps via binding to -> ROUTINE -> maps to -> VALUE
376 This method will try to find out if there is a binding defined for
378 the KEY. If no binding is found, the method will return the widget
379 object itself. If a binding is found, the method will check if
380 there is an corresponding ROUTINE. If the ROUTINE can be found it
381 will check if it's VALUE is a code reference. If it is, the code
382 will be executed and the returnvalue of this code will be returned.
383 Else the VALUE will directly be returned.
384 • clear_binding ( ROUTINE )
386 Clear all keybindings for routine ROUTINE.
388 • set_routine ( ROUTINE, VALUE )
390 Set the routine ROUTINE to the VALUE. The VALUE may either be a
392 scalar value or a code reference. If process_bindings (see above)
393 sees a scalar value, it will return this value. If it sees a
394 coderef, it will execute the code and return the returnvalue of
395 this code.
396 • set_binding ( ROUTINE, KEYLIST )
398 Bind the keys in the list KEYLIST to the ROUTINE. If you use an
400 empty string for a key, then this routine will become the default
401 routine (in case no other keybinding could be found). This is for
402 example used in the TextEditor widget.
403 • set_event ( EVENT, [CODEREF] )
405 This routine will set the callback for event EVENT to CODEREF. If
407 CODEREF is omitted or undefined, the event will be cleared.
408 • clear_event ( EVENT )
410 This will clear the callback for event EVENT.
412 • run_event ( EVENT )
414 This routine will check if a callback for the event EVENT is set
416 and if is a code reference. If this is the case, it will run the
417 code and return its return value.
418 • onFocus ( CODEREF )
420 This method can be used to set the -onfocus event handler (see
422 above) after initialization of the widget.
423 • onBlur ( CODEREF )
425 This method can be used to set the -onblur event handler (see
427 above) after initialization of the widget.
428 • parentwindow ( )
430 Returns this parent window for the widget or undef if no parent
432 window can be found (this should not happen).
433 • in_topwindow ( )
435 Returns true if the widget is in the window that is currently on
437 top.
438 • userdata ( [ SCALAR ] )
440 This method will return the user internal data stored in this
442 widget. If a SCALAR parameter is specified it will also set the
443 current user data to it.
444 • beep_on ( )
446 This sets the data member $this->{-nobeep} of the class instance to
448 a false value.
449 • beep_off ( )
451 This sets the data member $this->{-nobeep} of the class instance to
453 a true value.
454 • dobeep ( )
456 This will call the curses beep() routine, but only if -nobeep is
458 false.
459
461 Here's a basic framework for creating a new widget. You do not have to
462 follow this framework. As long as your widget has the methods new(),
463 layout(), draw() and focus(), it can be used in Curses::UI.
464 package Curses::UI::YourWidget
466 use Curses;
468 use Curses::UI::Widget;
469 use Curses::UI::Common; # some common widget routines
470 use vars qw($VERSION @ISA);
472 $VERSION = '0.01';
473 @ISA = qw(Curses::UI::Widget Curses::UI::Common);
474 # For a widget that can get focus, you should define
476 # the routines that are used to control the widget.
477 # Each routine has a name. This name is used in
478 # the definition of the bindings.
479 # The value can be a string or a subroutine reference.
480 # A string will make the widget return from focus.
481 #
482 my %routines = (
483 'return' => 'LOSE_FOCUS',
484 'key-a' => \&key_a,
485 'key-other' => \&other_key
486 );
487 # Using the bindings, the routines can be binded to key-
489 # presses. If the keypress is an empty string, this means
490 # that this is the default binding. If the key is not
491 # handled by any other binding, it's handled by this
492 # default binding.
493 #
494 my %bindings = (
495 KEY_DOWN() => 'return', # down arrow will make the
496 # widget lose it's focus
497 'a' => 'key-a', # a-key will trigger key_a()
498 '' => 'key-other' # any other key will trigger other_key()
499 );
500 # The creation of the widget. When doing it this way,
502 # it's easy to make optional and forced arguments
503 # possible. A forced argument could for example be
504 # -border => 1, which would mean that the widget
505 # always has a border, which can't be disabled by the
506 # programmer. The arguments can of course be used
507 # for storing the current state of the widget.
508 #
509 sub new () {
510 my $class = shift;
511 my %args = (
512 -optional_argument_1 => "default value 1",
513 -optional_argument_2 => "default value 2",
514 ....etc....
515 @_,
516 -forced_argument_1 => "forced value 1",
517 -forced_argument_2 => "forced value 2",
518 ....etc....
519 -bindings => {%bindings},
520 -routines => {%routines},
521 );
522 # Create the widget and do the layout of it.
524 my $this = $class->SUPER::new( %args );
525 $this->layout;
526 return $this;
528 }
529 # Each widget should have a layout() routine. Here,
531 # the widget itself and it's contents can be layouted.
532 # In case of a very simple widget, this will only mean
533 # that the Widget has to be layouted (in which case the
534 # routine could be left out, since it's in the base
535 # class already). In other cases you will have to add
536 # your own layout code. This routine is very important,
537 # since it will enable the resizeability of the widget!
538 #
539 sub layout () {
540 my $this = shift;
541 $this->SUPER::layout;
543 return $this if $Curses::UI::screen_too_small;
544 ....your own layout stuff....
546 # If you decide that the widget does not fit on the
548 # screen, then set $Curses::UI::screen_too_small
549 # to a true value and return.
550 if ( ....the widget does not fit.... ) {
551 $Curses::UI::screen_too_small++;
552 return $this;
553 }
554 return $this;
556 }
557 # The widget is drawn by the draw() routine. The
559 # $no_update part is used to disable screen flickering
560 # if a lot of widgets have to be drawn at once (for
561 # example on resizing or redrawing). The curses window
562 # which you can use for drawing the widget's contents
563 # is $this->{-canvasscr}.
564 #
565 sub draw(;$) {
566 my $this = shift;
567 my $no_doupdate = shift || 0;
568 return $this if $this->hidden;
569 $this->SUPER::draw(1);
570 ....your own draw stuff....
572 $this->{-canvasscr}->addstring(0, 0, "Fixed string");
573 ....your own draw stuff....
574 $this->{-canvasscr}->noutrefresh;
576 doupdate() unless $no_doupdate;
577 return $this;
578 }
579 # Focus the widget. If you do not override this routine
581 # from Curses::UI::Widget, the widget will not be
582 # focusable. Mostly you will use the generic_focus() method.
583 #
584 sub focus()
585 {
586 my $this = shift;
587 $this->show; # makes the widget visible if it was invisible
588 return $this->generic_focus(
589 undef, # delaytime, default = 2 (1/10 second).
590 NO_CONTROLKEYS, # disable controlkeys like CTRL+C. To enable
591 # them use CONTROLKEYS instead.
592 CURSOR_INVISIBLE, # do not show the cursor (if supported). To
593 # show the cursor use CURSOR_VISIBLE.
594 \&pre_key_routine, # optional callback routine to execute
595 # before a key is read. Mostly unused.
596 );
597 }
598 ....your own widget handling routines....
600
602 Curses::UI
603
605 Copyright (c) 2001-2002 Maurice Makaay. All rights reserved.
606 Maintained by Marcus Thiesen (marcus@cpan.thiesenweb.de)
608 This package is free software and is provided "as is" without express
610 or implied warranty. It may be used, redistributed and/or modified
611 under the same terms as perl itself.
612perl v5.36.0 2023-01-20 Curses::UI::Widget(3)