1Curses::UI::Widget(3) User Contributed Perl DocumentationCurses::UI::Widget(3)
2
3
4

NAME

6       Curses::UI::Widget - The base class for all widgets
7

CLASS HIERARCHY

9        Curses::UI::Widget - base class
10

SYNOPSIS

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
17           use Curses::UI::Widget;
18           my $widget = new Curses::UI::Widget(
19               -width  => 15,
20               -height => 5,
21               -border => 1,
22           );
23

STANDARD OPTIONS

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

WIDGET-SPECIFIC OPTIONS

30   GENERAL:
31-parent < OBJECTREF >
32
33           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
37-intellidraw < BOOLEAN >
38
39           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
43-userdata < SCALAR >
44
45           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
49-border < BOOLEAN >
50
51           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
55-sbborder < BOOLEAN >
56
57           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
64   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
93-x < VALUE >
94
95           The x-position of the widget, relative to the parent. The default
96           is 0.
97
98-y < VALUE >
99
100           The y-position of the widget, relative to the parent. The default
101           is 0.
102
103-width < VALUE >
104
105           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
109-height < VALUE >
110
111           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
115   PADDING:
116-pad < VALUE >
117
118-padtop < VALUE >
119
120-padbottom < VALUE >
121
122-padleft < VALUE >
123
124-padright < VALUE >
125
126           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
131-ipad < VALUE >
132
133-ipadtop < VALUE >
134
135-ipadbottom < VALUE >
136
137-ipadleft < VALUE >
138
139-ipadright < VALUE >
140
141           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
146   TITLE:
147       Remark:
148
149       A title is drawn in the border of a widget. So a title will only be
150       available if -border is true.
151
152-title < TEXT >
153
154           Set the title of the widget to TEXT. If the text is longer then the
155           available width, it will be clipped.
156
157-titlereverse < BOOLEAN >
158
159           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
163-titlefullwidth < BOOLEAN >
164
165           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
169   SCROLLBARS:
170       Remark:
171
172       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
178-vscrollbar < VALUE >
179
180           VALUE can be 'left', 'right', another true value or false.
181
182           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
188           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
193-hscrollbar < VALUE >
194
195           VALUE can be 'top', 'bottom', another true value or false.
196
197           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
203           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
209   EVENTS
210-onfocus < CODEREF >
211
212           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
216-onblur < CODEREF >
217
218           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

METHODS

223new ( OPTIONS )
224
225           Create a new Curses::UI::Widget instance using the options in HASH.
226
227layout ( )
228
229           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
233draw ( BOOLEAN )
234
235           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
239intellidraw ( )
240
241           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
246           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
253focus ( )
254
255           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
259focusable ( [BOOLEAN] )
260
261           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
265lose_focus ( )
266
267           This method makes the current widget lose it's focus.  It returns
268           the current widget.
269
270modalfocus ( )
271
272           Gives the widget a modal focus, i.e. no other widget can be active
273           till this widget is removed.
274
275title ( TEXT )
276
277           Change the title that is shown in the border of the widget to TEXT.
278
279width ( )
280
281height ( )
282
283           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
287borderwidth ( )
288
289borderheight ( )
290
291           These methods return the width and the height of the border of the
292           widget.
293
294canvaswidth ( )
295
296canvasheight ( )
297
298           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
304width_by_windowscrwidth ( NEEDWIDTH, OPTIONS )
305
306height_by_windowscrheight ( NEEDHEIGHT, OPTIONS )
307
308           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
316             my $height = height_by_windowscrheight(1, -border => 1);
317
318generic_focus ( BLOCKTIME, CTRLKEYS, CURSOR, PRECALLBACK )
319
320           For most widgets the generic_focus method will be enough to handle
321           focusing. This method will do the following:
322
323           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
328           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
335           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
339           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
344           * RETURN matches DO_KEY:<key>
345
346           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
349           * RETURN is a CODE reference
350
351           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
355           * RETURN is a SCALAR value
356
357           RETURN will be returned to the caller of generic_focus.  This will
358           have the widget lose its focus.
359
360           * anything else
361
362           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
367               sub myroutine() {
368                   my $this = shift;
369                   .... do your thing ....
370                   return $this;
371               }
372
373process_bindings ( KEY )
374
375           KEY -> maps via binding to -> ROUTINE -> maps to -> VALUE
376
377           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
385clear_binding ( ROUTINE )
386
387           Clear all keybindings for routine ROUTINE.
388
389set_routine ( ROUTINE, VALUE )
390
391           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
397set_binding ( ROUTINE, KEYLIST )
398
399           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
404set_event ( EVENT, [CODEREF] )
405
406           This routine will set the callback for event EVENT to CODEREF. If
407           CODEREF is omitted or undefined, the event will be cleared.
408
409clear_event ( EVENT )
410
411           This will clear the callback for event EVENT.
412
413run_event ( EVENT )
414
415           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
419onFocus ( CODEREF )
420
421           This method can be used to set the -onfocus event handler (see
422           above) after initialization of the widget.
423
424onBlur ( CODEREF )
425
426           This method can be used to set the -onblur event handler (see
427           above) after initialization of the widget.
428
429parentwindow ( )
430
431           Returns this parent window for the widget or undef if no parent
432           window can be found (this should not happen).
433
434in_topwindow ( )
435
436           Returns true if the widget is in the window that is currently on
437           top.
438
439userdata ( [ SCALAR ] )
440
441           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
445beep_on ( )
446
447           This sets the data member $this->{-nobeep} of the class instance to
448           a false value.
449
450beep_off ( )
451
452           This sets the data member $this->{-nobeep} of the class instance to
453           a true value.
454
455dobeep ( )
456
457           This will call the curses beep() routine, but only if -nobeep is
458           false.
459

WIDGET STRUCTURE

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
465           package Curses::UI::YourWidget
466
467           use Curses;
468           use Curses::UI::Widget;
469           use Curses::UI::Common; # some common widget routines
470
471           use vars qw($VERSION @ISA);
472           $VERSION = '0.01';
473           @ISA = qw(Curses::UI::Widget Curses::UI::Common);
474
475           # 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
488           # 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
501           # 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
523               # Create the widget and do the layout of it.
524               my $this = $class->SUPER::new( %args );
525           $this->layout;
526
527           return $this;
528           }
529
530           # 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
542               $this->SUPER::layout;
543           return $this if $Curses::UI::screen_too_small;
544
545               ....your own layout stuff....
546
547               # 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
555               return $this;
556           }
557
558           # 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
571               ....your own draw stuff....
572               $this->{-canvasscr}->addstring(0, 0, "Fixed string");
573               ....your own draw stuff....
574
575               $this->{-canvasscr}->noutrefresh;
576               doupdate() unless $no_doupdate;
577           return $this;
578           }
579
580           # 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
599           ....your own widget handling routines....
600

SEE ALSO

602       Curses::UI
603

AUTHOR

605       Copyright (c) 2001-2002 Maurice Makaay. All rights reserved.
606
607       Maintained by Marcus Thiesen (marcus@cpan.thiesenweb.de)
608
609       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.
612
613
614
615perl v5.36.0                      2023-01-20             Curses::UI::Widget(3)
Impressum