libyui
2.42.5
Main Page
Classes
Files
File List
All
Classes
Functions
Variables
Enumerations
Friends
YWidget.h
1
/*
2
Copyright (C) 2000-2012 Novell, Inc
3
This library is free software; you can redistribute it and/or modify
4
it under the terms of the GNU Lesser General Public License as
5
published by the Free Software Foundation; either version 2.1 of the
6
License, or (at your option) version 3.0 of the License. This library
7
is distributed in the hope that it will be useful, but WITHOUT ANY
8
WARRANTY; without even the implied warranty of MERCHANTABILITY or
9
FITNESS FOR A PARTICULAR PURPOSE. See the GNU Lesser General Public
10
License for more details. You should have received a copy of the GNU
11
Lesser General Public License along with this library; if not, write
12
to the Free Software Foundation, Inc., 51 Franklin Street, Fifth
13
Floor, Boston, MA 02110-1301 USA
14
*/
15
16
17
/*-/
18
19
File: YWidget.h
20
21
Author: Stefan Hundhammer <sh@suse.de>
22
23
/-*/
24
25
#ifndef YWidget_h
26
#define YWidget_h
27
28
#include <string>
29
#include <iosfwd>
30
31
#include "YTypes.h"
32
#include "YProperty.h"
33
#include "YUISymbols.h"
34
#include "YUIException.h"
35
#include "YChildrenManager.h"
36
#include "ImplPtr.h"
37
38
39
class
YDialog
;
40
class
YWidgetID
;
41
class
YMacroRecorder
;
42
43
44
typedef
YChildrenManager<YWidget>
YWidgetChildrenManager
;
45
typedef
YSingleChildManager<YWidget>
YSingleWidgetChildManager
;
46
typedef
YChildrenRejector<YWidget>
YWidgetChildrenRejector
;
47
48
class
YWidgetPrivate
;
49
50
51
/**
52
* Abstract base class of all UI widgets
53
**/
54
class
YWidget
55
{
56
protected
:
57
/**
58
* Constructor.
59
**/
60
YWidget
(
YWidget
*
parent
);
61
62
public
:
63
/**
64
* Destructor.
65
**/
66
virtual
~YWidget
();
67
68
/**
69
* Returns a descriptive name of this widget class for logging,
70
* debugging etc.
71
**/
72
virtual
const
char
*
widgetClass
()
const
{
return
"YWidget"
; }
73
74
/**
75
* Returns a descriptive label of this widget instance.
76
*
77
* This default implementation returns this widget's "shortcut property"
78
* (possibly trunctated to avoid over-long texts) - the property that
79
* contains the keyboard shortcut used to activate this widget or to move
80
* the keyboard focus to it. In most cases this is this widget's label.
81
*
82
* Note: This is usually translated to the user's target language.
83
* This makes this useful for debugging only.
84
**/
85
virtual
std::string
debugLabel
()
const
;
86
87
/**
88
* Return the help text for this widget.
89
**/
90
std::string
helpText
()
const
;
91
92
/**
93
* Set a help text for this widget.
94
*
95
* Currently, the UI does not do anything with this text but store it.
96
* Displaying the text at a convenient time is currently the application's
97
* responsibility. This may change in future versions.
98
**/
99
void
setHelpText
(
const
std::string &
helpText
);
100
101
102
//
103
// Property Management
104
//
105
106
/**
107
* Return this class's property set.
108
* This also initializes the property upon the first call.
109
*
110
* Derived classes should reimplement this.
111
*
112
* Remember to add the base class's property set to your own
113
* in reimplemented versions, e.g.:
114
*
115
* const YPropertySet &
116
* MyWidgetClass::propertySet()
117
* {
118
* static YPropertySet propSet;
119
*
120
* if ( propSet.isEmpty() )
121
* {
122
* // Add properties for the derived class
123
* propSet.add( YProperty( YUIProperty_Value, YStringProperty ) );
124
* propSet.add( YProperty( YUIProperty_Label, YStringProperty ) );
125
*
126
* // Add base class properties
127
* propSet.add( YWidget::propertySet() );
128
* }
129
*
130
* return propSet;
131
* }
132
*
133
* Otherwise the base class's properties will not be available in the
134
* derived class. It is also important that the base class's properties
135
* are added after those of the derived class so the derived class's
136
* properties have priority over those of the base class.
137
**/
138
virtual
const
YPropertySet
&
propertySet
();
139
140
/**
141
* Set a property. Derived classes need to implement this.
142
*
143
* This method may throw exceptions, for example
144
* - if there is no property with that name
145
* - if the expected type and the type mismatch
146
* - if the value is out of range
147
*
148
* This function returns 'true' if the value was successfully set and
149
* 'false' if that value requires special handling (not in error cases:
150
* those are covered by exceptions).
151
**/
152
virtual
bool
setProperty
(
const
std::string & propertyName,
153
const
YPropertyValue
& val );
154
155
/**
156
* Get a property. Derived classes need to implement this.
157
*
158
* This method may throw exceptions, for example
159
* - if there is no property with that name
160
**/
161
virtual
YPropertyValue
getProperty
(
const
std::string & propertyName );
162
163
164
//
165
// Children Management
166
//
167
// Even though many widget classes are leaf classes and thus cannot have
168
// children by design, it makes sense to have the children management in
169
// this base class: Then descending down a widget tree is transparent to
170
// the outside without the need to check for container widget classes,
171
// casting to those container widget classes and only calling child
172
// management methods in that case.
173
//
174
// By default, YWidget and derived classes have a YWidgetChildrenRejector
175
// as their children manager, i.e. any attempt to add a child will result
176
// in a YUITooManyChildrenException.
177
//
178
// Derived classes that can (semantically) handle children should set the
179
// children manager to one of
180
//
181
// - YWidgetChildrenManager: handles any number of child widgets;
182
// useful for VBox / HBox
183
//
184
// - YSingleWidgetChildManager: handles exactly one child
185
// useful for widgets like Alignment, Frame, Dialog
186
//
187
188
189
/**
190
* Returns 'true' if this widget has any children.
191
**/
192
bool
hasChildren
()
const
193
{
return
childrenManager
()->
hasChildren
(); }
194
195
/**
196
* Returns the first child or 0 if there is none.
197
* Useful mostly for children managers that handle only one child.
198
**/
199
YWidget
*
firstChild
()
const
200
{
return
childrenManager
()->
firstChild
(); }
201
202
/**
203
* Returns the last child or 0 if there is none.
204
**/
205
YWidget
*
lastChild
()
const
206
{
return
childrenManager
()->
lastChild
(); }
207
208
/**
209
* Return an iterator that points to the first child or to childrenEnd() if
210
* there are no children.
211
**/
212
YWidgetListConstIterator
childrenBegin
()
const
213
{
return
childrenManager
()->
begin
(); }
214
215
/**
216
* Return an interator that points after the last child.
217
**/
218
YWidgetListConstIterator
childrenEnd
()
const
219
{
return
childrenManager
()->
end
(); }
220
221
/**
222
* Returns the current number of children.
223
**/
224
int
childrenCount
()
const
{
return
childrenManager
()->
count
(); }
225
226
/**
227
* Checks if 'child' is a (direct!) child of this widget.
228
**/
229
bool
contains
(
YWidget
* child )
const
230
{
return
childrenManager
()->
contains
( child ); }
231
232
/**
233
* Add a new child.
234
*
235
* This may throw exceptions if more children are added than this widget
236
* can handle.
237
**/
238
virtual
void
addChild
(
YWidget
* child );
239
240
/**
241
* Remove a child. This only removes the child from the children manager's
242
* list; it does not delete it.
243
**/
244
virtual
void
removeChild
(
YWidget
* child );
245
246
/**
247
* Delete all children and remove them from the children manager's list.
248
**/
249
void
deleteChildren
();
250
251
/**
252
* Return this widget's parent or 0 if it doesn't have a parent.
253
**/
254
YWidget
*
parent
()
const
;
255
256
/**
257
* Return 'true' if this widget has a parent, 'false' if not.
258
**/
259
bool
hasParent
()
const
;
260
261
/**
262
* Set this widget's parent.
263
**/
264
void
setParent
(
YWidget
* newParent );
265
266
/**
267
* Traverse up the widget hierarchy and find the dialog this widget belongs
268
* to. Returns 0 if there is none.
269
**/
270
YDialog
*
findDialog
();
271
272
/**
273
* Recursively find a widget by its ID.
274
* If there is no widget with that ID, this function throws a
275
* YUIWidgetNotFoundException if 'doThrow' is 'true'. It returns 0 if
276
* 'doThrow' is 'false'.
277
**/
278
YWidget
*
findWidget
(
YWidgetID
*
id
,
bool
doThrow =
true
)
const
;
279
280
281
//
282
// Geometry Management
283
//
284
285
/**
286
* Preferred width of the widget.
287
*
288
* Derived classes are required to implement this.
289
**/
290
virtual
int
preferredWidth
() = 0;
291
292
/**
293
* Preferred height of the widget.
294
*
295
* Derived classes are required to implement this.
296
**/
297
virtual
int
preferredHeight
() = 0;
298
299
/**
300
* Preferred size of the widget in the specified dimension.
301
* This default implementation calls preferredWidth() or preferredHeight()
302
* which makes sense for most cases.
303
*
304
* Derived classes can reimplement this, but this is discouraged.
305
*
306
* Note: Even in that case, preferredWidth() and preferredHeight() need to
307
* be implemented, but they might then call preferredSize().
308
**/
309
virtual
int
preferredSize
( YUIDimension dim );
310
311
/**
312
* Set the new size of the widget.
313
*
314
* Layout manager widgets (like YLayoutBox) call this during geometry
315
* management after all widgets are queried about their preferred widths
316
* and heights. Depending on layout constraints, widgets might be resized
317
* beyond or below their preferred size.
318
*
319
* The sizes passed here are not meant to affect any future
320
* preferredWidth() or preferredHeight() calls; they are just the outcome
321
* of all kinds of compromises (too little screen space or too much) for
322
* the current geometry management calculation.
323
*
324
* Derived classes are required to implement this function.
325
**/
326
virtual
void
setSize
(
int
newWidth,
int
newHeight ) = 0;
327
328
329
//
330
// Misc
331
//
332
333
334
/**
335
* Checks whether or not this object is valid. This is to enable
336
* dangling pointer error checking (i.e. this object is already
337
* deallocated, but a pointer to it is still in use).
338
*
339
* See also the YUI_CHECK_WIDGET() macro in YUIException.h
340
**/
341
bool
isValid
()
const
;
342
343
/**
344
* Check if this widget is in the process of being destroyed.
345
**/
346
bool
beingDestroyed
()
const
;
347
348
/**
349
* Return a pointer to the underlying toolkit's (Qt, ...) widget
350
* representing this abstract UI widget.
351
**/
352
void
*
widgetRep
()
const
;
353
354
/**
355
* Set the pointer to the underlying toolkit's (Qt, ...) widget
356
* representing this abstract UI widget.
357
*
358
* This pointer might be useful for derived UIs to store a counterpart of
359
* the toolkit widget in each YWidget. The abstract UI does not need that,
360
* though; this is purely for the convenience of derived UIs. All the
361
* abstract UI ever does with that pointer is store it.
362
**/
363
void
setWidgetRep
(
void
* toolkitWidgetRep );
364
365
/**
366
* Returns 'true' if this widget has an ID.
367
**/
368
bool
hasId
()
const
;
369
370
/**
371
* Returns this widget's ID.
372
**/
373
YWidgetID
*
id
()
const
;
374
375
/**
376
* Set this widget's ID.
377
*
378
* The widget assumes ownership of this ID and will delete it when needed.
379
* (In the widget's destructor or when a new ID is set)
380
*
381
* Widget IDs are purely for application use. C++ applications don't need
382
* to use them; they are much better off using widget pointers. For other
383
* languages, though, that can't use C++ pointers (e.g., YCP) it makes
384
* sense to have widget IDs to identify widgets.
385
**/
386
void
setId
(
YWidgetID
* newId_disown );
387
388
/**
389
* Enable or disable this widget, i.e. make it accept or reject user input.
390
*
391
* Derived classes should call the base class method to update the internal
392
*"enabled" flag.
393
**/
394
virtual
void
setEnabled
(
bool
enabled =
true
);
395
396
/**
397
* Disable this widget (overloaded for better readability).
398
**/
399
void
setDisabled
() {
setEnabled
(
false
); }
400
401
/**
402
* Returns 'true' if this widget is enabled.
403
**/
404
virtual
bool
isEnabled
()
const
;
405
406
/**
407
* This is a boolean value that determines whether the widget is resizable
408
* beyond its preferred size in the specified dimension. A selection box is
409
* stretchable in both dimensions, a push button is not stretchable by
410
* default, a frame is stretchable if its contents are stretchable. Most
411
* widgets accept a `hstretch or `vstretch option to become stretchable
412
* even when by default they are not.
413
**/
414
virtual
bool
stretchable
( YUIDimension dim )
const
;
415
416
/**
417
* Set the stretchable state to "newStretch" regardless of any `hstretch or
418
* `vstretch options.
419
**/
420
void
setStretchable
( YUIDimension dim,
bool
newStretch );
421
422
/**
423
* Set the stretchable state to "newStretch".
424
* `hstretch or `vstretch options may override this.
425
**/
426
void
setDefaultStretchable
( YUIDimension dim,
bool
newStretch );
427
428
/**
429
* The weight is used in situations where all widgets can get their
430
* preferred size and yet space is available. The remaining space will be
431
* devided between all stretchable widgets according to their weights. A
432
* widget with greater weight will get more space. The default weight for
433
* all widgets is 0.
434
*
435
* Derived classes can overwrite this function, but they should call this
436
* base class function in the new function.
437
**/
438
virtual
int
weight
( YUIDimension dim );
439
440
/**
441
* Return whether or not the widget has a weight in the specified
442
* dimension.
443
**/
444
bool
hasWeight
( YUIDimension dim );
445
446
/**
447
* Set a weight in the specified dimension.
448
**/
449
void
setWeight
( YUIDimension dim,
int
weight
);
450
451
/**
452
* Sets the Notify property
453
**/
454
void
setNotify
(
bool
notify
=
true
);
455
456
/**
457
* Returns whether the widget will notify, i.e. will case UserInput to
458
* return.
459
**/
460
bool
notify
()
const
;
461
462
/**
463
* Sets the notifyContextMenu property
464
**/
465
void
setNotifyContextMenu
(
bool
notifyContextMenu
=
true
);
466
467
/**
468
* Returns whether the widget will send an event when the user
469
* clicks selects the context menu e.g. via right click.
470
**/
471
bool
notifyContextMenu
()
const
;
472
473
474
/**
475
* Returns 'true' if this widget should send key events, i.e. if it has
476
* `opt(`keyEvent) set.
477
**/
478
bool
sendKeyEvents
()
const
;
479
480
/**
481
* Specify whether or not this widget should send key events.
482
**/
483
void
setSendKeyEvents
(
bool
doSend );
484
485
/**
486
* Returns 'true' if a keyboard shortcut should automatically be assigned
487
* to this widget - without complaints in the log file.
488
**/
489
bool
autoShortcut
()
const
;
490
491
/**
492
* Sets the 'autoShortcut' flag.
493
**/
494
void
setAutoShortcut
(
bool
_newAutoShortcut );
495
496
/**
497
* Return a function key number that is assigned to this widget.
498
* (1 for F1, 2 for F2, etc.; 0 for none)
499
**/
500
int
functionKey
()
const
;
501
502
/**
503
* Check if a function key is assigned to this widget.
504
**/
505
bool
hasFunctionKey
()
const
;
506
507
/**
508
* Assign a function key to this widget
509
* (1 for F1, 2 for F2, etc.; 0 for none)
510
*
511
* Derived classes may want to overwrite this function, but they should
512
* call this base class function in the new function.
513
**/
514
virtual
void
setFunctionKey
(
int
fkey_no );
515
516
/**
517
* Set the keyboard focus to this widget.
518
* The default implementation just emits a warning message.
519
* Overwrite this function for all widgets that can accept the
520
* keyboard focus.
521
*
522
* This function returns true if the widget did accept the
523
* keyboard focus, and false if not.
524
**/
525
virtual
bool
setKeyboardFocus
();
526
527
/**
528
* Get the string of this widget that holds the keyboard shortcut, if any.
529
* Most widgets will return label().
530
*
531
* Overwrite this for widgets that can have keyboard shortcuts.
532
**/
533
virtual
std::string
shortcutString
()
const
{
return
std::string(
""
); }
534
535
/**
536
* Set the string of this widget that holds the keyboard shortcut, if any.
537
* Most widgets will call setLabel().
538
*
539
* Overwrite this for widgets that can have keyboard shortcuts.
540
**/
541
virtual
void
setShortcutString
(
const
std::string & str );
542
543
/**
544
* The name of the widget property that will return user input, if there is
545
* any. Widgets that do have user input (such as InputField, ComboBox,
546
* SelBox) should overwrite this methods. Widgets that are purely passive
547
* (such as Label, RichText) should not.
548
**/
549
virtual
const
char
*
userInputProperty
() {
return
(
const
char
*) 0; }
550
551
/**
552
* Debugging function:
553
* Dump the widget tree from here on to the log file.
554
**/
555
void
dumpWidgetTree
(
int
indentationLevel = 0 );
556
557
/**
558
* Debugging function:
559
* Dump the widget tree from this widget's dialog parent.
560
* If there is no such dialog parent, dump the widget tree from
561
* here on.
562
**/
563
void
dumpDialogWidgetTree
();
564
565
/**
566
* Enable or disable all widgets in this widget tree.
567
**/
568
void
setChildrenEnabled
(
bool
enabled );
569
570
//
571
// Macro Recorder Support
572
//
573
574
/**
575
* Recursively save the user input of all child widgets to a macro
576
* recorder:
577
*
578
* All child widgets that could contain data entered by the user
579
* are requested to send their contents to the macro recorder, e.g. input
580
* fields, check boxes etc.
581
*
582
* This default implementation records this widget's user input property
583
* (the property returned by userInputProperty) and then recursively calls
584
* saveUserInput() for all child widgets. This is suitable for most cases,
585
* for container widgets as well as for leaf widgets that have no or
586
* exactly one property that needs to be recorded.
587
*
588
* Widgets that need another number of properties recorded should
589
* reimplement this method (and NOT call this default method in the new
590
* implementation).
591
**/
592
virtual
void
saveUserInput
(
YMacroRecorder
*macroRecorder );
593
594
/**
595
* Overloaded operator new to ensure widgets are always created on the
596
* heap, never on the stack.
597
*
598
* Simpler implementations of this have a tendency to be fooled by poorly
599
* implemented derived classes.
600
**/
601
void
*
operator
new
(
size_t
size );
602
603
604
// NCurses optimizations
605
606
607
/**
608
* In some UIs updating the screen content is an expensive operation. Use
609
* startMultipleChanges() to tell the ui that you're going to perform
610
* multiple chages to the widget. The UI may delay any screen updates
611
* until doneMultipleChanges() is called.
612
**/
613
virtual
void
startMultipleChanges
() {}
614
virtual
void
doneMultipleChanges() {}
615
616
617
protected
:
618
619
/**
620
* Returns this widget's children manager.
621
**/
622
YWidgetChildrenManager
*
childrenManager
()
const
;
623
624
/**
625
* Sets a new children manager for this widget. The widget assumes
626
* ownership of this children manager and will delete it when appropriate.
627
*
628
* The default children manager (a YWidgetChildrenRejector) rejects all
629
* children. This is useful for leaf widgets such as PushButton, ComboBox
630
* etc.
631
*
632
* Derived classes that can handle children might want to set the children
633
* manager to a YWidgetChildrenManager (the base class that does not reject
634
* children) or to a YSingleWidgetChildManager (the class that handles
635
* exactly one child widget).
636
**/
637
void
setChildrenManager
(
YWidgetChildrenManager
* manager );
638
639
/**
640
* Set the "being destroyed" flag, i.e. indicate that this widget is in the
641
* process of being destroyed. The base class method already sets this, but
642
* sometimes it might be useful to call this in a derived class's
643
* destructor so certain optimizations work better.
644
*
645
* This status intentionally cannot be reverted to "not being destroyed".
646
**/
647
void
setBeingDestroyed
();
648
649
/**
650
* Helper function for dumpWidgetTree():
651
* Dump one widget to the log file.
652
**/
653
void
dumpWidget
(
YWidget
*w,
int
indentationLevel );
654
655
656
private
:
657
658
/**
659
* Make this widget invalid. This operation cannot be reversed.
660
**/
661
void
invalidate();
662
663
/**
664
* Disable copy constructor.
665
**/
666
YWidget
(
const
YWidget
& other );
667
668
/**
669
* Disable assignment operator.
670
**/
671
const
YWidget
& operator=(
const
YWidget
& other );
672
673
private
:
674
675
//
676
// Data Members
677
//
678
679
int
_magic;
// should always be the first member
680
ImplPtr<YWidgetPrivate>
priv;
681
static
YPropertySet
_propertySet;
682
static
bool
_usedOperatorNew;
683
684
685
#include "YWidget_OptimizeChanges.h"
686
687
};
688
689
690
std::ostream & operator<<( std::ostream & stream,
const
YWidget
* widget );
691
692
693
#endif // YWidget_h
src
YWidget.h
Generated by
1.8.3