libyui  3.3.2
YButtonBox Class Referenceabstract

Container widget for dialog buttons that abstracts the button order depending on the desktop environment. More...

#include <YButtonBox.h>

Inheritance diagram for YButtonBox:
Collaboration diagram for YButtonBox:

Public Member Functions

virtual ~YButtonBox ()
 Destructor.
 
virtual const char * widgetClass () const
 Return a descriptive name of this widget class for logging, debugging etc.
 
virtual void setMargins (const YButtonBoxMargins &margins)
 Set the margins for this YButtonBox. More...
 
YButtonBoxMargins margins () const
 Return the margins of this YButtonBox. More...
 
virtual void doLayout (int width, int height)
 Lay out the button box and its children (its buttons). More...
 
YPushButtonfindButton (YButtonRole role)
 Search the child widgets for the first button with the specified role. More...
 
void sanityCheck ()
 Sanity check: Check if all child widgets have the correct widget class and if the button roles are assigned correctly. More...
 
void setSanityCheckRelaxed (bool relax=true)
 Relax the sanity check done in sanityCheck(): Do not enforce that there has to be a YOKButton and a YCancelButton if there is more than one button. More...
 
bool sanityCheckRelaxed () const
 Return 'true' if sanity checks are currently relaxed, 'false' if not.
 
virtual int preferredWidth ()
 Preferred width of the widget. More...
 
virtual int preferredHeight ()
 Preferred height of the widget. More...
 
virtual void setSize (int newWidth, int newHeight)
 Sets the size of the YButtonBox. More...
 
virtual bool stretchable (YUIDimension dimension) const
 Returns the stretchability of the YButtonBox. More...
 
- Public Member Functions inherited from YWidget
virtual ~YWidget ()
 Destructor.
 
virtual std::string debugLabel () const
 Returns a descriptive label of this widget instance. More...
 
std::string helpText () const
 Return the help text for this widget.
 
void setHelpText (const std::string &helpText)
 Set a help text for this widget. More...
 
virtual const YPropertySetpropertySet ()
 Return this class's property set. More...
 
virtual bool setProperty (const std::string &propertyName, const YPropertyValue &val)
 Set a property. More...
 
virtual YPropertyValue getProperty (const std::string &propertyName)
 Get a property. More...
 
bool hasChildren () const
 Returns 'true' if this widget has any children.
 
YWidgetfirstChild () const
 Returns the first child or 0 if there is none. More...
 
YWidgetlastChild () const
 Returns the last child or 0 if there is none.
 
YWidgetListIterator childrenBegin () const
 Return an iterator that points to the first child or to childrenEnd() if there are no children.
 
YWidgetListIterator childrenEnd () const
 Return an interator that points after the last child.
 
YWidgetListConstIterator childrenConstBegin () const
 Return a const iterator that points to the first child or to childrenEnd() if there are no children.
 
YWidgetListConstIterator childrenConstEnd () const
 Return a const interator that points after the last child.
 
YWidgetListIterator begin ()
 A helper for the range-based "for" loop. More...
 
YWidgetListIterator end ()
 A helper for the range-based "for" loop. More...
 
int childrenCount () const
 Returns the current number of children.
 
bool contains (YWidget *child) const
 Checks if 'child' is a (direct!) child of this widget.
 
virtual void addChild (YWidget *child)
 Add a new child. More...
 
virtual void removeChild (YWidget *child)
 Remove a child. More...
 
void deleteChildren ()
 Delete all children and remove them from the children manager's list.
 
YWidgetparent () const
 Return this widget's parent or 0 if it doesn't have a parent.
 
bool hasParent () const
 Return 'true' if this widget has a parent, 'false' if not.
 
void setParent (YWidget *newParent)
 Set this widget's parent.
 
YDialogfindDialog ()
 Traverse up the widget hierarchy and find the dialog this widget belongs to. More...
 
YWidgetfindWidget (YWidgetID *id, bool doThrow=true) const
 Recursively find a widget by its ID. More...
 
virtual int preferredSize (YUIDimension dim)
 Preferred size of the widget in the specified dimension. More...
 
bool isValid () const
 Checks whether or not this object is valid. More...
 
bool beingDestroyed () const
 Check if this widget is in the process of being destroyed.
 
void * widgetRep () const
 Return a pointer to the underlying toolkit's (Qt, ...) widget representing this abstract UI widget.
 
void setWidgetRep (void *toolkitWidgetRep)
 Set the pointer to the underlying toolkit's (Qt, ...) widget representing this abstract UI widget. More...
 
bool hasId () const
 Returns 'true' if this widget has an ID.
 
YWidgetIDid () const
 Returns this widget's ID.
 
void setId (YWidgetID *newId_disown)
 Set this widget's ID. More...
 
virtual void setEnabled (bool enabled=true)
 Enable or disable this widget, i.e. More...
 
void setDisabled ()
 Disable this widget (overloaded for better readability).
 
virtual bool isEnabled () const
 Returns 'true' if this widget is enabled.
 
void setStretchable (YUIDimension dim, bool newStretch)
 Set the stretchable state to "newStretch" regardless of any hstretch or vstretch options.
 
void setDefaultStretchable (YUIDimension dim, bool newStretch)
 Set the stretchable state to "newStretch". More...
 
virtual int weight (YUIDimension dim)
 The weight is used in situations where all widgets can get their preferred size and yet space is available. More...
 
bool hasWeight (YUIDimension dim)
 Return whether or not the widget has a weight in the specified dimension.
 
void setWeight (YUIDimension dim, int weight)
 Set a weight in the specified dimension.
 
void setNotify (bool notify=true)
 Sets the Notify property.
 
bool notify () const
 Returns whether the widget will notify, i.e. More...
 
void setNotifyContextMenu (bool notifyContextMenu=true)
 Sets the notifyContextMenu property.
 
bool notifyContextMenu () const
 Returns whether the widget will send an event when the user clicks selects the context menu e.g. More...
 
bool sendKeyEvents () const
 Returns 'true' if this widget should send key events, i.e. More...
 
void setSendKeyEvents (bool doSend)
 Specify whether or not this widget should send key events.
 
bool autoShortcut () const
 Returns 'true' if a keyboard shortcut should automatically be assigned to this widget - without complaints in the log file.
 
void setAutoShortcut (bool _newAutoShortcut)
 Sets the 'autoShortcut' flag.
 
int functionKey () const
 Return a function key number that is assigned to this widget. More...
 
bool hasFunctionKey () const
 Check if a function key is assigned to this widget.
 
virtual void setFunctionKey (int fkey_no)
 Assign a function key to this widget (1 for F1, 2 for F2, etc. More...
 
virtual bool setKeyboardFocus ()
 Set the keyboard focus to this widget. More...
 
virtual std::string shortcutString () const
 Get the string of this widget that holds the keyboard shortcut, if any. More...
 
virtual void setShortcutString (const std::string &str)
 Set the string of this widget that holds the keyboard shortcut, if any. More...
 
virtual const char * userInputProperty ()
 The name of the widget property that will return user input, if there is any. More...
 
void dumpWidgetTree (int indentationLevel=0)
 Debugging function: Dump the widget tree from here on to the log file.
 
void dumpDialogWidgetTree ()
 Debugging function: Dump the widget tree from this widget's dialog parent. More...
 
void setChildrenEnabled (bool enabled)
 Enable or disable all widgets in this widget tree.
 
virtual void saveUserInput (YMacroRecorder *macroRecorder)
 Recursively save the user input of all child widgets to a macro recorder: More...
 
void * operator new (size_t size)
 Overloaded operator new to ensure widgets are always created on the heap, never on the stack. More...
 
virtual void startMultipleChanges ()
 In some UIs updating the screen content is an expensive operation. More...
 
virtual void doneMultipleChanges ()
 

Static Public Member Functions

static void setLayoutPolicy (const YButtonBoxLayoutPolicy &layoutPolicy)
 Set the button policy for all future YButtonBox widgets: Button order, alignment if there is any excess space, whether or not to give all buttons the same size. More...
 
static YButtonBoxLayoutPolicy layoutPolicy ()
 Return the layout policy.
 
static YButtonBoxLayoutPolicy kdeLayoutPolicy ()
 Predefined layout policy for KDE-like behaviour.
 
static YButtonBoxLayoutPolicy gnomeLayoutPolicy ()
 Predefined layout policy for GNOME-like behaviour.
 
static void setDefaultMargins (const YButtonBoxMargins &margins)
 Set the default margins for all future YButtonBox widgets.
 
static YButtonBoxMargins defaultMargins ()
 Return the default margins for all future YButtonBox widgets.
 

Protected Member Functions

 YButtonBox (YWidget *parent)
 Constructor.
 
virtual std::vector< YPushButton * > buttonsByButtonOrder ()
 Return the button children sorted (left to right) by the current button order (from the layout policy). More...
 
int maxChildSize (YUIDimension dim) const
 Return the (preferred) size of the biggest child widget in the specified dimension.
 
int totalChildrenWidth () const
 Return the sum of the (preferred) widths of all child widgets.
 
virtual void moveChild (YWidget *child, int newX, int newY)=0
 Move a child to a new position. More...
 
int preferredWidth (bool equalSizeButtons)
 Calculate the preferred with with or without trying to enforce buttons of equal size.
 
- Protected Member Functions inherited from YWidget
 YWidget (YWidget *parent)
 Constructor.
 
YWidgetChildrenManagerchildrenManager () const
 Returns this widget's children manager.
 
void setChildrenManager (YWidgetChildrenManager *manager)
 Sets a new children manager for this widget. More...
 
void setBeingDestroyed ()
 Set the "being destroyed" flag, i.e. More...
 
void dumpWidget (YWidget *w, int indentationLevel)
 Helper function for dumpWidgetTree(): Dump one widget to the log file.
 

Friends

class YButtonBoxPrivate
 

Detailed Description

Container widget for dialog buttons that abstracts the button order depending on the desktop environment.

KDE and Windows arrange dialog buttons like this:

[OK] [Apply] [Cancel] [Custom1] [Custom2] ... [Help]

[Continue] [Cancel]

[Yes] [No]

GNOME and MacOS arrange them like this:

[Help] [Custom1] [Custom2] ... [Apply] [Cancel] [OK]

[Cancel] [Continue]

[No] [Yes]

This class provides the abstraction to use whatever layout is more appropriate in the current environment. The application creates the buttons as child widgets of a YButtonBox (rather than a YHBox) and leaves the button order to the YButtonBox.

Each of the standard buttons ([OK], [Apply], [Cancel], [Help]) needs to have a button role properly assigned.

If set up properly (see YApplication::setDefaultFunctionKey()), known button labels will be assigned an appropriate role:

[OK]                        F10
[Continue] -> [OK]  F10
[Yes]      -> [OK]  F10
[Accept]   -> [OK]  F10
[Next]     -> [OK]  F10

[Cancel]                    F9
[No]       -> [Cancel]      F9

[Help]                      F1

Buttons with nonstandard labels that act in such a role need to be explicitly assigned that role:

[Print ] [Cancel] [Help]
[Delete] [Cancel] [Help]

Those [Print] or [Delete] buttons act as [OK] buttons (the "yes, do it" action of that dialog). Call YPushButton::setButtonRole( YOkButton ) explicitly for them.

YButtonBox widgets only accept YPushButton child widgets. Otherwise an exception is thrown.

If there is more than one button, one of the child buttons needs to have the [OK] role, and another needs to have the [Cancel] role. Otherwise an exception is thrown.

Definition at line 148 of file YButtonBox.h.

Member Function Documentation

◆ buttonsByButtonOrder()

std::vector< YPushButton * > YButtonBox::buttonsByButtonOrder ( )
protectedvirtual

Return the button children sorted (left to right) by the current button order (from the layout policy).

This default implementation handles KDE and Gnome button orders. It is used in the default doLayout() method.

This may throw exceptions if there are non-button children or if there are multiple buttons with any of the standard button roles (except YCustomButton, of course).

Definition at line 410 of file YButtonBox.cc.

◆ doLayout()

void YButtonBox::doLayout ( int  width,
int  height 
)
virtual

Lay out the button box and its children (its buttons).

This is where the button order is implemented.

This method is called by the default setSize() method. It uses YButtonBox::layoutPolicy() and the specified margins (defaultMargins unless changed with setMargins() ). It moves the buttons to their position with moveChild().

This all should work reasonably in all cases (Qt-UI with KDE button order, Gtk-UI with Gnome button order, NCurses-UI with KDE button order).

Still, derived classes can reimplement this. It does not make very much sense to call this default method in a new implementation.

Definition at line 161 of file YButtonBox.cc.

Here is the call graph for this function:

◆ findButton()

YPushButton * YButtonBox::findButton ( YButtonRole  role)

Search the child widgets for the first button with the specified role.

Return the button or 0 if there is no button with that role.

Definition at line 575 of file YButtonBox.cc.

Here is the call graph for this function:

◆ margins()

YButtonBoxMargins YButtonBox::margins ( ) const

Return the margins of this YButtonBox.

Notice that those are only the desired margins; if there is not enough space, margins and spacings will be reduced before buttons are cut off.

Definition at line 146 of file YButtonBox.cc.

◆ moveChild()

virtual void YButtonBox::moveChild ( YWidget child,
int  newX,
int  newY 
)
protectedpure virtual

Move a child to a new position.

This is used in doLayout().

Derived classes are required to implement this.

◆ preferredHeight()

int YButtonBox::preferredHeight ( )
virtual

Preferred height of the widget.

Reimplemented from YWidget. This default method returns the height of the highest child plus the top and bottom margins.

Derived classes can reimplement this method. It does not make very much sense to call this base class method in a new implementation.

Implements YWidget.

Definition at line 517 of file YButtonBox.cc.

Here is the call graph for this function:

◆ preferredWidth()

int YButtonBox::preferredWidth ( )
virtual

Preferred width of the widget.

Reimplemented from YWidget. This default method returns the sum of the the widths of all child widgets plus the left and right margins plus the spacings.

Derived classes can reimplement this method. It does not make very much sense to call this base class method in a new implementation.

Implements YWidget.

Definition at line 510 of file YButtonBox.cc.

◆ sanityCheck()

void YButtonBox::sanityCheck ( )

Sanity check: Check if all child widgets have the correct widget class and if the button roles are assigned correctly.

A YButtonBox with more than one button is required to have one YOKButton and ony YCancelButton. Neither button role may be assigned more than once.

This method may throw exceptions:

This cannot be done as child widgets are inserted since this is done from the child widgets' constructors, so virtual methods or dynamic_cast don't work at that point.

This is called in the default setSize() method (just before doLayout()), so any of the above errors are caught only at that time. Applications are free to call this before that time to make error handling more transparent.

Definition at line 606 of file YButtonBox.cc.

Here is the call graph for this function:

◆ setLayoutPolicy()

void YButtonBox::setLayoutPolicy ( const YButtonBoxLayoutPolicy layoutPolicy)
static

Set the button policy for all future YButtonBox widgets: Button order, alignment if there is any excess space, whether or not to give all buttons the same size.

You might want to use one of the predefined static methods: YButtonBox::kdeLayoutPolicy(), YButtonBox::gnomeLayoutPolicy().

The default doLayout() method uses those values.

Notice that there is intentionally no way to set this differently for each individual YButtonBox: This would defeat the purpose of consistency (with the desktop environment this application is running in), which is the reason for having this widget class.

Definition at line 82 of file YButtonBox.cc.

Here is the call graph for this function:

◆ setMargins()

void YButtonBox::setMargins ( const YButtonBoxMargins margins)
virtual

Set the margins for this YButtonBox.

Derived classes are free to reimplement this, but they should call this base class method in the new method.

Definition at line 139 of file YButtonBox.cc.

Here is the call graph for this function:

◆ setSanityCheckRelaxed()

void YButtonBox::setSanityCheckRelaxed ( bool  relax = true)

Relax the sanity check done in sanityCheck(): Do not enforce that there has to be a YOKButton and a YCancelButton if there is more than one button.

In very rare cases, it might be neccessary to have a less stringent sanity check: There are some very few legitimate cases for having a YButtonBox with multiple buttons, yet without a YCancelButton.

Examples:

...message...
 <Countdown>
 [OK] [Stop]

...message...
[OK] [Details]

In those cases, it makes sense to relax the sanity check.

Definition at line 592 of file YButtonBox.cc.

◆ setSize()

void YButtonBox::setSize ( int  newWidth,
int  newHeight 
)
virtual

Sets the size of the YButtonBox.

Derived classes can reimplement this, but this base class method should be called in the reimplemented function.

Reimplemented from YWidget.

Implements YWidget.

Definition at line 153 of file YButtonBox.cc.

Here is the call graph for this function:

◆ stretchable()

bool YButtonBox::stretchable ( YUIDimension  dimension) const
virtual

Returns the stretchability of the YButtonBox.

YButtonBox widgets are horizontally stretchable by default. How any excess space is used is specified in the layout policy.

Reimplemented from YWidget.

Reimplemented from YWidget.

Definition at line 560 of file YButtonBox.cc.


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