libyui  3.0.5
 All Classes Functions Variables Enumerations Friends
YWidget Class Referenceabstract

#include <YWidget.h>

Inheritance diagram for YWidget:

Classes

class  OptimizeChanges
 

Public Member Functions

virtual ~YWidget ()
 
virtual const char * widgetClass () const
 
virtual std::string debugLabel () const
 
std::string helpText () const
 
void setHelpText (const std::string &helpText)
 
virtual const YPropertySetpropertySet ()
 
virtual bool setProperty (const std::string &propertyName, const YPropertyValue &val)
 
virtual YPropertyValue getProperty (const std::string &propertyName)
 
bool hasChildren () const
 
YWidgetfirstChild () const
 
YWidgetlastChild () const
 
YWidgetListConstIterator childrenBegin () const
 
YWidgetListConstIterator childrenEnd () const
 
int childrenCount () const
 
bool contains (YWidget *child) const
 
virtual void addChild (YWidget *child)
 
virtual void removeChild (YWidget *child)
 
void deleteChildren ()
 
YWidgetparent () const
 
bool hasParent () const
 
void setParent (YWidget *newParent)
 
YDialogfindDialog ()
 
YWidgetfindWidget (YWidgetID *id, bool doThrow=true) const
 
virtual int preferredWidth ()=0
 
virtual int preferredHeight ()=0
 
virtual int preferredSize (YUIDimension dim)
 
virtual void setSize (int newWidth, int newHeight)=0
 
bool isValid () const
 
bool beingDestroyed () const
 
void * widgetRep () const
 
void setWidgetRep (void *toolkitWidgetRep)
 
bool hasId () const
 
YWidgetIDid () const
 
void setId (YWidgetID *newId_disown)
 
virtual void setEnabled (bool enabled=true)
 
void setDisabled ()
 
virtual bool isEnabled () const
 
virtual bool stretchable (YUIDimension dim) const
 
void setStretchable (YUIDimension dim, bool newStretch)
 
void setDefaultStretchable (YUIDimension dim, bool newStretch)
 
virtual int weight (YUIDimension dim)
 
bool hasWeight (YUIDimension dim)
 
void setWeight (YUIDimension dim, int weight)
 
void setNotify (bool notify=true)
 
bool notify () const
 
void setNotifyContextMenu (bool notifyContextMenu=true)
 
bool notifyContextMenu () const
 
bool sendKeyEvents () const
 
void setSendKeyEvents (bool doSend)
 
bool autoShortcut () const
 
void setAutoShortcut (bool _newAutoShortcut)
 
int functionKey () const
 
bool hasFunctionKey () const
 
virtual void setFunctionKey (int fkey_no)
 
virtual bool setKeyboardFocus ()
 
virtual std::string shortcutString () const
 
virtual void setShortcutString (const std::string &str)
 
virtual const char * userInputProperty ()
 
void dumpWidgetTree (int indentationLevel=0)
 
void dumpDialogWidgetTree ()
 
void setChildrenEnabled (bool enabled)
 
virtual void saveUserInput (YMacroRecorder *macroRecorder)
 
void * operator new (size_t size)
 
virtual void startMultipleChanges ()
 
virtual void doneMultipleChanges ()
 

Protected Member Functions

 YWidget (YWidget *parent)
 
YWidgetChildrenManagerchildrenManager () const
 
void setChildrenManager (YWidgetChildrenManager *manager)
 
void setBeingDestroyed ()
 
void dumpWidget (YWidget *w, int indentationLevel)
 

Detailed Description

Abstract base class of all UI widgets

Definition at line 54 of file YWidget.h.

Constructor & Destructor Documentation

YWidget::YWidget ( YWidget parent)
protected

Constructor.

Definition at line 104 of file YWidget.cc.

Here is the call graph for this function:

YWidget::~YWidget ( )
virtual

Destructor.

Definition at line 135 of file YWidget.cc.

Here is the call graph for this function:

Member Function Documentation

void YWidget::addChild ( YWidget child)
virtual

Add a new child.

This may throw exceptions if more children are added than this widget can handle.

Reimplemented in YAlignment.

Definition at line 174 of file YWidget.cc.

Here is the call graph for this function:

bool YWidget::autoShortcut ( ) const

Returns 'true' if a keyboard shortcut should automatically be assigned to this widget - without complaints in the log file.

Definition at line 310 of file YWidget.cc.

bool YWidget::beingDestroyed ( ) const

Check if this widget is in the process of being destroyed.

Definition at line 256 of file YWidget.cc.

YWidgetListConstIterator YWidget::childrenBegin ( ) const
inline

Return an iterator that points to the first child or to childrenEnd() if there are no children.

Definition at line 212 of file YWidget.h.

Here is the call graph for this function:

int YWidget::childrenCount ( ) const
inline

Returns the current number of children.

Definition at line 224 of file YWidget.h.

Here is the call graph for this function:

YWidgetListConstIterator YWidget::childrenEnd ( ) const
inline

Return an interator that points after the last child.

Definition at line 218 of file YWidget.h.

Here is the call graph for this function:

YWidgetChildrenManager * YWidget::childrenManager ( ) const
protected

Returns this widget's children manager.

Definition at line 157 of file YWidget.cc.

bool YWidget::contains ( YWidget child) const
inline

Checks if 'child' is a (direct!) child of this widget.

Definition at line 229 of file YWidget.h.

Here is the call graph for this function:

std::string YWidget::debugLabel ( ) const
virtual

Returns a descriptive label of this widget instance.

This default implementation returns this widget's "shortcut property" (possibly trunctated to avoid over-long texts) - the property that contains the keyboard shortcut used to activate this widget or to move the keyboard focus to it. In most cases this is this widget's label.

Note: This is usually translated to the user's target language. This makes this useful for debugging only.

Reimplemented in YLabel, and YDumbTab.

Definition at line 221 of file YWidget.cc.

Here is the call graph for this function:

void YWidget::deleteChildren ( )

Delete all children and remove them from the children manager's list.

Definition at line 200 of file YWidget.cc.

Here is the call graph for this function:

void YWidget::dumpDialogWidgetTree ( )

Debugging function: Dump the widget tree from this widget's dialog parent. If there is no such dialog parent, dump the widget tree from here on.

Definition at line 658 of file YWidget.cc.

Here is the call graph for this function:

void YWidget::dumpWidget ( YWidget w,
int  indentationLevel 
)
protected

Helper function for dumpWidgetTree(): Dump one widget to the log file.

Definition at line 687 of file YWidget.cc.

Here is the call graph for this function:

void YWidget::dumpWidgetTree ( int  indentationLevel = 0)

Debugging function: Dump the widget tree from here on to the log file.

Definition at line 669 of file YWidget.cc.

Here is the call graph for this function:

YDialog * YWidget::findDialog ( )

Traverse up the widget hierarchy and find the dialog this widget belongs to. Returns 0 if there is none.

Definition at line 374 of file YWidget.cc.

Here is the call graph for this function:

YWidget * YWidget::findWidget ( YWidgetID id,
bool  doThrow = true 
) const

Recursively find a widget by its ID. If there is no widget with that ID, this function throws a YUIWidgetNotFoundException if 'doThrow' is 'true'. It returns 0 if 'doThrow' is 'false'.

Definition at line 602 of file YWidget.cc.

Here is the call graph for this function:

YWidget* YWidget::firstChild ( ) const
inline

Returns the first child or 0 if there is none. Useful mostly for children managers that handle only one child.

Definition at line 199 of file YWidget.h.

Here is the call graph for this function:

int YWidget::functionKey ( ) const

Return a function key number that is assigned to this widget. (1 for F1, 2 for F2, etc.; 0 for none)

Definition at line 322 of file YWidget.cc.

YPropertyValue YWidget::getProperty ( const std::string &  propertyName)
virtual

Get a property. Derived classes need to implement this.

This method may throw exceptions, for example

  • if there is no property with that name

Reimplemented in YWizard, YComboBox, YTable, YInputField, YPushButton, YCheckBoxFrame, YPartitionSplitter, YCheckBox, YLogView, YIntField, YRadioButton, YMultiProgressMeter, YLabel, YRichText, YBarGraph, YMultiLineEdit, YDownloadProgress, YTree, YContextMenu, YMenuButton, YSelectionBox, YBusyIndicator, YRadioButtonGroup, YProgressBar, YDumbTab, YSimpleInputField, YGraph, YFrame, YMultiSelectionBox, and YTimezoneSelector.

Definition at line 453 of file YWidget.cc.

Here is the call graph for this function:

bool YWidget::hasChildren ( ) const
inline

Returns 'true' if this widget has any children.

Definition at line 192 of file YWidget.h.

Here is the call graph for this function:

bool YWidget::hasFunctionKey ( ) const

Check if a function key is assigned to this widget.

Definition at line 328 of file YWidget.cc.

bool YWidget::hasId ( ) const

Returns 'true' if this widget has an ID.

Definition at line 368 of file YWidget.cc.

bool YWidget::hasParent ( ) const

Return 'true' if this widget has a parent, 'false' if not.

Definition at line 276 of file YWidget.cc.

bool YWidget::hasWeight ( YUIDimension  dim)

Return whether or not the widget has a weight in the specified dimension.

Definition at line 585 of file YWidget.cc.

Here is the call graph for this function:

std::string YWidget::helpText ( ) const

Return the help text for this widget.

Definition at line 340 of file YWidget.cc.

YWidgetID * YWidget::id ( ) const

Returns this widget's ID.

Definition at line 353 of file YWidget.cc.

bool YWidget::isEnabled ( ) const
virtual

Returns 'true' if this widget is enabled.

Definition at line 502 of file YWidget.cc.

bool YWidget::isValid ( ) const

Checks whether or not this object is valid. This is to enable dangling pointer error checking (i.e. this object is already deallocated, but a pointer to it is still in use).

See also the YUI_CHECK_WIDGET() macro in YUIException.h

Definition at line 242 of file YWidget.cc.

YWidget* YWidget::lastChild ( ) const
inline

Returns the last child or 0 if there is none.

Definition at line 205 of file YWidget.h.

Here is the call graph for this function:

bool YWidget::notify ( ) const

Returns whether the widget will notify, i.e. will case UserInput to return.

Definition at line 529 of file YWidget.cc.

bool YWidget::notifyContextMenu ( ) const

Returns whether the widget will send an event when the user clicks selects the context menu e.g. via right click.

Definition at line 535 of file YWidget.cc.

void * YWidget::operator new ( size_t  size)

Overloaded operator new to ensure widgets are always created on the heap, never on the stack.

Simpler implementations of this have a tendency to be fooled by poorly implemented derived classes.

Definition at line 128 of file YWidget.cc.

YWidget * YWidget::parent ( ) const

Return this widget's parent or 0 if it doesn't have a parent.

Definition at line 269 of file YWidget.cc.

virtual int YWidget::preferredHeight ( )
pure virtual

Preferred height of the widget.

Derived classes are required to implement this.

Implemented in YButtonBox, YAlignment, YSpacing, YLayoutBox, YEmpty, and YSingleChildContainerWidget.

int YWidget::preferredSize ( YUIDimension  dim)
virtual

Preferred size of the widget in the specified dimension. This default implementation calls preferredWidth() or preferredHeight() which makes sense for most cases.

Derived classes can reimplement this, but this is discouraged.

Note: Even in that case, preferredWidth() and preferredHeight() need to be implemented, but they might then call preferredSize().

Reimplemented in YLayoutBox.

Definition at line 541 of file YWidget.cc.

Here is the call graph for this function:

virtual int YWidget::preferredWidth ( )
pure virtual

Preferred width of the widget.

Derived classes are required to implement this.

Implemented in YButtonBox, YAlignment, YSpacing, YLayoutBox, YEmpty, and YSingleChildContainerWidget.

const YPropertySet & YWidget::propertySet ( )
virtual

Return this class's property set. This also initializes the property upon the first call.

Derived classes should reimplement this.

Remember to add the base class's property set to your own in reimplemented versions, e.g.:

const YPropertySet &
MyWidgetClass::propertySet()
{
    static YPropertySet propSet;

    if ( propSet.isEmpty() )
    {
        // Add properties for the derived class
       propSet.add( YProperty( YUIProperty_Value, YStringProperty ) );
       propSet.add( YProperty( YUIProperty_Label, YStringProperty ) );

        // Add base class properties
       propSet.add( YWidget::propertySet() );
    }

    return propSet;
}

Otherwise the base class's properties will not be available in the derived class. It is also important that the base class's properties are added after those of the derived class so the derived class's properties have priority over those of the base class.

Reimplemented in YWizard, YComboBox, YTable, YInputField, YPushButton, YCheckBoxFrame, YPartitionSplitter, YCheckBox, YLogView, YIntField, YRadioButton, YMultiProgressMeter, YLabel, YRichText, YBarGraph, YMultiLineEdit, YDownloadProgress, YTree, YContextMenu, YMenuButton, YSelectionBox, YBusyIndicator, YRadioButtonGroup, YProgressBar, YDumbTab, YSimpleInputField, YGraph, YFrame, YMultiSelectionBox, and YTimezoneSelector.

Definition at line 393 of file YWidget.cc.

Here is the call graph for this function:

void YWidget::removeChild ( YWidget child)
virtual

Remove a child. This only removes the child from the children manager's list; it does not delete it.

Definition at line 189 of file YWidget.cc.

Here is the call graph for this function:

void YWidget::saveUserInput ( YMacroRecorder macroRecorder)
virtual

Recursively save the user input of all child widgets to a macro recorder:

All child widgets that could contain data entered by the user are requested to send their contents to the macro recorder, e.g. input fields, check boxes etc.

This default implementation records this widget's user input property (the property returned by userInputProperty) and then recursively calls saveUserInput() for all child widgets. This is suitable for most cases, for container widgets as well as for leaf widgets that have no or exactly one property that needs to be recorded.

Widgets that need another number of properties recorded should reimplement this method (and NOT call this default method in the new implementation).

Reimplemented in YInputField, YRadioButton, and YMultiSelectionBox.

Definition at line 714 of file YWidget.cc.

Here is the call graph for this function:

bool YWidget::sendKeyEvents ( ) const

Returns 'true' if this widget should send key events, i.e. if it has opt(keyEvent) set.

Definition at line 298 of file YWidget.cc.

void YWidget::setAutoShortcut ( bool  _newAutoShortcut)

Sets the 'autoShortcut' flag.

Definition at line 316 of file YWidget.cc.

void YWidget::setBeingDestroyed ( )
protected

Set the "being destroyed" flag, i.e. indicate that this widget is in the process of being destroyed. The base class method already sets this, but sometimes it might be useful to call this in a derived class's destructor so certain optimizations work better.

This status intentionally cannot be reverted to "not being destroyed".

Definition at line 262 of file YWidget.cc.

void YWidget::setChildrenEnabled ( bool  enabled)

Enable or disable all widgets in this widget tree.

Definition at line 638 of file YWidget.cc.

Here is the call graph for this function:

void YWidget::setChildrenManager ( YWidgetChildrenManager manager)
protected

Sets a new children manager for this widget. The widget assumes ownership of this children manager and will delete it when appropriate.

The default children manager (a YWidgetChildrenRejector) rejects all children. This is useful for leaf widgets such as PushButton, ComboBox etc.

Derived classes that can handle children might want to set the children manager to a YWidgetChildrenManager (the base class that does not reject children) or to a YSingleWidgetChildManager (the class that handles exactly one child widget).

Definition at line 164 of file YWidget.cc.

void YWidget::setDefaultStretchable ( YUIDimension  dim,
bool  newStretch 
)

Set the stretchable state to "newStretch". hstretch orvstretch options may override this.

Definition at line 561 of file YWidget.cc.

void YWidget::setDisabled ( )
inline

Disable this widget (overloaded for better readability).

Definition at line 399 of file YWidget.h.

Here is the call graph for this function:

void YWidget::setEnabled ( bool  enabled = true)
virtual

Enable or disable this widget, i.e. make it accept or reject user input.

Derived classes should call the base class method to update the internal "enabled" flag.

Definition at line 495 of file YWidget.cc.

void YWidget::setFunctionKey ( int  fkey_no)
virtual

Assign a function key to this widget (1 for F1, 2 for F2, etc.; 0 for none)

Derived classes may want to overwrite this function, but they should call this base class function in the new function.

Reimplemented in YPushButton.

Definition at line 334 of file YWidget.cc.

void YWidget::setHelpText ( const std::string &  helpText)

Set a help text for this widget.

Currently, the UI does not do anything with this text but store it. Displaying the text at a convenient time is currently the application's responsibility. This may change in future versions.

Definition at line 346 of file YWidget.cc.

Here is the call graph for this function:

void YWidget::setId ( YWidgetID newId_disown)

Set this widget's ID.

The widget assumes ownership of this ID and will delete it when needed. (In the widget's destructor or when a new ID is set)

Widget IDs are purely for application use. C++ applications don't need to use them; they are much better off using widget pointers. For other languages, though, that can't use C++ pointers (e.g., YCP) it makes sense to have widget IDs to identify widgets.

Definition at line 359 of file YWidget.cc.

bool YWidget::setKeyboardFocus ( )
virtual

Set the keyboard focus to this widget. The default implementation just emits a warning message. Overwrite this function for all widgets that can accept the keyboard focus.

This function returns true if the widget did accept the keyboard focus, and false if not.

Definition at line 594 of file YWidget.cc.

void YWidget::setNotify ( bool  notify = true)

Sets the Notify property

Definition at line 517 of file YWidget.cc.

Here is the call graph for this function:

void YWidget::setNotifyContextMenu ( bool  notifyContextMenu = true)

Sets the notifyContextMenu property

Definition at line 523 of file YWidget.cc.

Here is the call graph for this function:

void YWidget::setParent ( YWidget newParent)

Set this widget's parent.

Definition at line 283 of file YWidget.cc.

Here is the call graph for this function:

bool YWidget::setProperty ( const std::string &  propertyName,
const YPropertyValue val 
)
virtual

Set a property. Derived classes need to implement this.

This method may throw exceptions, for example

  • if there is no property with that name
  • if the expected type and the type mismatch
  • if the value is out of range

This function returns 'true' if the value was successfully set and 'false' if that value requires special handling (not in error cases: those are covered by exceptions).

Reimplemented in YComboBox, YTable, YInputField, YPushButton, YCheckBoxFrame, YPartitionSplitter, YCheckBox, YLogView, YIntField, YRadioButton, YMultiProgressMeter, YRichText, YLabel, YBarGraph, YMultiLineEdit, YDownloadProgress, YTree, YContextMenu, YMenuButton, YSelectionBox, YBusyIndicator, YRadioButtonGroup, YProgressBar, YDumbTab, YSimpleInputField, YGraph, YFrame, YMultiSelectionBox, and YTimezoneSelector.

Definition at line 428 of file YWidget.cc.

Here is the call graph for this function:

void YWidget::setSendKeyEvents ( bool  doSend)

Specify whether or not this widget should send key events.

Definition at line 304 of file YWidget.cc.

void YWidget::setShortcutString ( const std::string &  str)
virtual

Set the string of this widget that holds the keyboard shortcut, if any. Most widgets will call setLabel().

Overwrite this for widgets that can have keyboard shortcuts.

Reimplemented in YSelectionWidget, YInputField, YPushButton, YCheckBox, YLogView, YIntField, YRadioButton, YMultiLineEdit, YCheckBoxFrame, YDumbTab, and YSimpleInputField.

Definition at line 508 of file YWidget.cc.

Here is the call graph for this function:

virtual void YWidget::setSize ( int  newWidth,
int  newHeight 
)
pure virtual

Set the new size of the widget.

Layout manager widgets (like YLayoutBox) call this during geometry management after all widgets are queried about their preferred widths and heights. Depending on layout constraints, widgets might be resized beyond or below their preferred size.

The sizes passed here are not meant to affect any future preferredWidth() or preferredHeight() calls; they are just the outcome of all kinds of compromises (too little screen space or too much) for the current geometry management calculation.

Derived classes are required to implement this function.

Implemented in YButtonBox, YAlignment, YLayoutBox, and YSingleChildContainerWidget.

void YWidget::setStretchable ( YUIDimension  dim,
bool  newStretch 
)

Set the stretchable state to "newStretch" regardless of any hstretch or vstretch options.

Definition at line 555 of file YWidget.cc.

void YWidget::setWeight ( YUIDimension  dim,
int  weight 
)

Set a weight in the specified dimension.

Definition at line 579 of file YWidget.cc.

Here is the call graph for this function:

void YWidget::setWidgetRep ( void *  toolkitWidgetRep)

Set the pointer to the underlying toolkit's (Qt, ...) widget representing this abstract UI widget.

This pointer might be useful for derived UIs to store a counterpart of the toolkit widget in each YWidget. The abstract UI does not need that, though; this is purely for the convenience of derived UIs. All the abstract UI ever does with that pointer is store it.

Definition at line 488 of file YWidget.cc.

virtual std::string YWidget::shortcutString ( ) const
inlinevirtual

Get the string of this widget that holds the keyboard shortcut, if any. Most widgets will return label().

Overwrite this for widgets that can have keyboard shortcuts.

Reimplemented in YSelectionWidget, YInputField, YPushButton, YCheckBox, YLogView, YIntField, YRadioButton, YMultiLineEdit, YCheckBoxFrame, YDumbTab, and YSimpleInputField.

Definition at line 533 of file YWidget.h.

virtual void YWidget::startMultipleChanges ( )
inlinevirtual

In some UIs updating the screen content is an expensive operation. Use startMultipleChanges() to tell the ui that you're going to perform multiple chages to the widget. The UI may delay any screen updates until doneMultipleChanges() is called.

Definition at line 613 of file YWidget.h.

bool YWidget::stretchable ( YUIDimension  dim) const
virtual

This is a boolean value that determines whether the widget is resizable beyond its preferred size in the specified dimension. A selection box is stretchable in both dimensions, a push button is not stretchable by default, a frame is stretchable if its contents are stretchable. Most widgets accept a hstretch orvstretch option to become stretchable even when by default they are not.

Reimplemented in YButtonBox, YAlignment, YDumbTab, YLayoutBox, YSquash, and YSingleChildContainerWidget.

Definition at line 567 of file YWidget.cc.

virtual const char* YWidget::userInputProperty ( )
inlinevirtual

The name of the widget property that will return user input, if there is any. Widgets that do have user input (such as InputField, ComboBox, SelBox) should overwrite this methods. Widgets that are purely passive (such as Label, RichText) should not.

Reimplemented in YComboBox, YInputField, YCheckBox, YTable, YIntField, YRadioButton, YPartitionSplitter, YMultiLineEdit, YTree, YSelectionBox, YCheckBoxFrame, YSimpleInputField, and YMultiSelectionBox.

Definition at line 549 of file YWidget.h.

int YWidget::weight ( YUIDimension  dim)
virtual

The weight is used in situations where all widgets can get their preferred size and yet space is available. The remaining space will be devided between all stretchable widgets according to their weights. A widget with greater weight will get more space. The default weight for all widgets is 0.

Derived classes can overwrite this function, but they should call this base class function in the new function.

Definition at line 573 of file YWidget.cc.

void * YWidget::widgetRep ( ) const

Return a pointer to the underlying toolkit's (Qt, ...) widget representing this abstract UI widget.

Definition at line 481 of file YWidget.cc.


The documentation for this class was generated from the following files: