YWidget.h

/*
  Copyright (C) 2000-2012 Novell, Inc
  This library is free software; you can redistribute it and/or modify
  it under the terms of the GNU Lesser General Public License as
  published by the Free Software Foundation; either version 2.1 of the
  License, or (at your option) version 3.0 of the License. This library
  is distributed in the hope that it will be useful, but WITHOUT ANY
  WARRANTY; without even the implied warranty of MERCHANTABILITY or
  FITNESS FOR A PARTICULAR PURPOSE. See the GNU Lesser General Public
  License for more details. You should have received a copy of the GNU
  Lesser General Public License along with this library; if not, write
  to the Free Software Foundation, Inc., 51 Franklin Street, Fifth
  Floor, Boston, MA 02110-1301 USA
*/


/*-/

  File:     YWidget.h

  Author:   Stefan Hundhammer <shundhammer@suse.de>

/-*/

#ifndef YWidget_h
#define YWidget_h

#include <string>
#include <iosfwd>

#include "YTypes.h"
#include "YProperty.h"
#include "YUISymbols.h"
#include "YUIException.h"
#include "YChildrenManager.h"
#include "ImplPtr.h"


class YDialog;
class YWidgetID;
class YMacroRecorder;


typedef YChildrenManager<YWidget>   YWidgetChildrenManager;
typedef YSingleChildManager<YWidget>    YSingleWidgetChildManager;
typedef YChildrenRejector<YWidget>  YWidgetChildrenRejector;

class YWidgetPrivate;


class YWidget
{
protected:
    YWidget( YWidget * parent );

public:
    virtual ~YWidget();

    virtual const char * widgetClass() const { return "YWidget"; }

    virtual std::string debugLabel() const;

    std::string helpText() const;

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


    //
    // Property Management
    //

    virtual const YPropertySet & propertySet();

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

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


    //
    // Children Management
    //
    // Even though many widget classes are leaf classes and thus cannot have
    // children by design, it makes sense to have the children management in
    // this base class: Then descending down a widget tree is transparent to
    // the outside without the need to check for container widget classes,
    // casting to those container widget classes and only calling child
    // management methods in that case.
    //
    // By default, YWidget and derived classes have a YWidgetChildrenRejector
    // as their children manager, i.e. any attempt to add a child will result
    // in a YUITooManyChildrenException.
    //
    // Derived classes that can (semantically) handle children should set the
    // children manager to one of
    //
    // - YWidgetChildrenManager: handles any number of child widgets;
    //   useful for VBox / HBox
    //
    // - YSingleWidgetChildManager: handles exactly one child
    //   useful for widgets like Alignment, Frame, Dialog
    //


    bool hasChildren() const
    { return childrenManager()->hasChildren(); }

    YWidget * firstChild() const
    { return childrenManager()->firstChild(); }

    YWidget * lastChild() const
    { return childrenManager()->lastChild(); }

    YWidgetListIterator childrenBegin() const
    { return childrenManager()->begin(); }

    YWidgetListIterator childrenEnd() const
    { return childrenManager()->end(); }

    YWidgetListConstIterator childrenConstBegin() const
    { return childrenManager()->begin(); }

    YWidgetListConstIterator childrenConstEnd() const
    { return childrenManager()->end(); }

    YWidgetListIterator begin()
    { return childrenBegin(); }

    YWidgetListIterator end()
    { return childrenEnd(); }

    int childrenCount() const { return childrenManager()->count(); }

    bool contains( YWidget * child ) const
    { return childrenManager()->contains( child ); }

    virtual void addChild( YWidget * child );

    virtual void removeChild( YWidget * child );

    void deleteChildren();

    YWidget * parent() const;

    bool hasParent() const;

    void setParent( YWidget * newParent );

    YDialog * findDialog();

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


    //
    // Geometry Management
    //

    virtual int preferredWidth() = 0;

    virtual int preferredHeight() = 0;

    virtual int preferredSize( YUIDimension dim );

    virtual void setSize( int newWidth, int newHeight ) = 0;


    //
    // Misc
    //


    bool isValid() const;

    bool beingDestroyed() const;

    void * widgetRep() const;

    void setWidgetRep( void * toolkitWidgetRep );

    bool hasId() const;

    YWidgetID * id() const;

    void setId( YWidgetID * newId_disown );

    virtual void setEnabled( bool enabled = true );

    void setDisabled() { setEnabled( false); }

    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 { return std::string( "" ); }

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

    virtual const char * userInputProperty() { return (const char *) 0; }

    void dumpWidgetTree( int indentationLevel = 0 );

    void dumpDialogWidgetTree();

    void setChildrenEnabled( bool enabled );

    //
    // Macro Recorder Support
    //

    virtual void saveUserInput( YMacroRecorder *macroRecorder );

    void * operator new( size_t size );


    // NCurses optimizations


    virtual void startMultipleChanges() {}
    virtual void doneMultipleChanges() {}


protected:

    YWidgetChildrenManager * childrenManager() const;

    void setChildrenManager( YWidgetChildrenManager * manager );

     void setBeingDestroyed();

    void dumpWidget( YWidget *w, int indentationLevel );


private:

    void invalidate();

    YWidget( const YWidget & other );

    const YWidget & operator=( const YWidget & other );

private:

    //
    // Data Members
    //

    int             _magic; // should always be the first member
    ImplPtr<YWidgetPrivate> priv;
    static YPropertySet     _propertySet;
    static bool         _usedOperatorNew;


#include "YWidget_OptimizeChanges.h"

};


std::ostream & operator<<( std::ostream & stream, const YWidget * widget );


#endif // YWidget_h