ktmainwindow.h

PIXIL is a small footprint operating environment, complete with PDA PIM applications, a browser and

#ifndef _KWIDGET_H
#define _KWIDGET_H

#include <stdlib.h>
#include <qwidget.h>
#include <qlist.h>
#include <ktoolbar.h>
#include <kmenubar.h>
#include <kstatusbar.h>
#include <kconfig.h>

/**
 * Top level widget that provides toolbars, a status line and a frame.
 * It should be used as a toplevel (parent-less) widget and
 * manages the geometry for all its children, including your
 * main widget.
 *
 * Normally, you will inherit from KTMainWindow (known also as KTMW).
 * Then you must construct (or use some existing) widget that will be
 * your main view. You can set only one main view.
 *
 * You can add as many toolbar(s) as you like. There can be only one menubar
 * and only one statusbar.
 *
 * Toolbars, Menubar, and Statusbar can be generated by the KTMainWindow and - unlike
 * old KTopLevelWidget - may, but do not have to be deleted by you. KTMainWindow will
 * handle that internaly.
 *
 * KTMainWindow maintaines the layout and resizing of all elements
 * (toolbars, statusbar, main widget, etc).  KTMainWindow now handles fixed-size
 * and Y-fixed main views properly. Just set fixed size or
 * your main view. You can change it runtime, the changes will take effect
 * on next updateRects call. Do not set fixed size on window! You may set
 * minimum or maximum size on window, but only if main view is freely
 * resizable. Minimum width can also be set if main view is Y-fixed.
 *
 * KTMainWindow will set icon, mini icon and caption, which it gets
 * from KApplication. It provides full session management, and will save
 * its position, geometry and positions of toolbar(s) and menubar on
 * logout. If you want to save aditional data, overload saveProperties and
 * (to read them again on next login) readProperties. To save special
 * data about your data, overload saveData. To warn user
 * that application has unsaved data on logout, use setUnsavedData.
 *
 * There is also a macro RESTORE which can restore all your windows
 * on next login.
 *
 * This class is now merged with KTopLevelWidget (KTW). Biggest difference
 * is that KTMainWindow implements closeEvent and calls needed functios
 * in case when window is closed. By overloading these (virtual)
 * functions, you controll what happens in these cases.
 *
 * KTMainWindow might be replaced/extended in the future to
 * KMainWindow which will be a child of QMainWindow. Anyway,
 * the current interface  will be supported for compatibility
 * reasons.
 *
 * @see KApplication
 * @see KTopLevelWidget
 * @short KDE top level main window
   @author Stephan Kulow ([e-mail]), Matthias Ettrich ([e-mail]), Sven Radej ([e-mail]) .Maintained by Sven Radej ([e-mail])

 */

class KTMainWindow : public QWidget {
    Q_OBJECT

        friend class KToolBar;

public:
    /**
     * Constructor.
     * Note that for session management to work, KTMainWindow widget
     * must be created with 'new'.
     */
    KTMainWindow( const char *name = 0L );
    /**
     * Destructor. Will also destroy the toolbars, and menubar if
     * needed.
     */
    ~KTMainWindow();

    /** Deletes all KTMainWindows. This is a good thing to call before
      * an applications wants to exit via kapp->quit(). Rationale: The
      * destructors of main windows may want to delete other widgets
      * as well. Now, if an application calls kapp->quit() then Qt
      * will destroy all widgets in a somewhat random order which may
      * result in double-free'ed memory (=segfault). Since not every
      * program checks for QApplication::closingDown() before deleting
      * a widget, calling KTMainWindow::deleteAll() before is a good
      * and proper solution.
     */
  static void deleteAll();

    /**
     * Add a toolbar to the widget.
     * A toolbar added to this widget will be automatically laid out
     * by it.
     *
     * The toolbar must have been created with this instance of
     * KTMainWindow as its parent.
     *
     * Usually you do not need this function. Just refer to a toolbar
     * with @ref #toolBar (index) instead and the KTMainWindow will
     * create it for you. Anyway addToolBar() is usefull if you want
     * to pass additional arguments to the toolbar's constructor.
     * (Matthias)
     */
    int addToolBar( KToolBar *toolbar, int index = -1 );

    /**
     * Set the main client widget.
     * This is the main widget for your application; it's geometry
     * will be automatically managed by KTMainWindow to fit the
     * client area, constrained by the positions of the menu, toolbars
     * and status bar. It can be fixed-width or Y-fixed.
     *
     * Only one client widget can be handled at a time; multiple calls
     * of setView will cause only the last widget to be added to be
     * properly handled.
     *
     * The widget must have been created with this instance of
     * KTMainWindow as its parent.
     */
    void setView( QWidget *view, bool show_frame = TRUE );


    /**
     *Enable or disable the status bar.
     */
    void enableStatusBar( KStatusBar::BarStatus stat = KStatusBar::Toggle );

    /**
     * Enable or disable the toolbar with the ID specified.
     * If no ID is specified, the default ID is 0.
     */
    void enableToolBar( KToolBar::BarStatus stat = KToolBar::Toggle,
                        int ID = 0 );

    /**
     * Set the width of the view frame.
     * If you request a frame around your view with @ref #setView (...,TRUE),
     * you can use this function to set the border width of the frame.
     * The default is 1 pixel. You should call this function before
     * @ref #setView ().
     */
    void setFrameBorderWidth( int );

    /**
     * Returns a pointer to the toolbar with the specified ID.
     * If there is no such tool bar yet, it will be generated
     */
    KToolBar *toolBar( int ID = 0 );

    /**
     * Returns a pointer to the menu bar. If there is no
     * menu bar yet, it will be generated
     */
    KMenuBar *menuBar();

    /**
     * If you constructed menuBar yourself, you must set it with this
     * function. You can use it also if you want to replace old menu bar
     * with a new one. There can be only one menu bar at a time. After this
     * function, layout will be updated.
     * @see #menuBar
     */
    void setMenu (KMenuBar *menuBar);

    /**
     * Returns a pointer to the status bar. If there is no
     * status bar yet, it will be generated
     */
    KStatusBar *statusBar();

    /**
     * If you constructed statusBar yourself, you must set it with this
     * function. You can use it also if you want to replace old status bar
     * with a new one. There can be only one status bar at a time. After this
     * function layout will be updated.
     * @see #statusBar
     */
    void setStatusBar (KStatusBar *statusBar);

    /* You probably do not need this. Anyway, if you are porting code
     * which have been written for the former @ref KTopLevelWidget you may
     * find the following three boolean has-functions useful:
     *
     * This function returns wether the menubar is existing
     */
    bool hasMenuBar();
    /**
     * Returns wether the statusbar is existing
     */
    bool hasStatusBar();
    /**
     * Returns wether the specified toolbar  is existing
     */
    bool hasToolBar( int ID = 0);


    /**
     * Shows toplevel widget. Reimplemented from QWidget, and calls
     * @ref #updateRects (i.e. updates layout)
     */
    virtual void show ();

    /**
     * Distance from top of window to top of main view,
     * Computed in @ref #updateRects. Changing of this variable
     * has no effect.
     * Avoid using it, it might be removed in future.
     */
    int view_top;

    /**
     * Distance from top of window to bottom of main view.
     * Computed in @ref #updateRects. Changing of this variable
     * has no effect.
     * Avoid using it, it might be removed in future.
     */
    int view_bottom;

    /**
     * Distance from left edge of window to left border of main view.
     * Computed in @ref #updateRects. Changing of this variable
     * has no effect.
     * Avoid using it, it might be removed in future.
     */
    int view_left;

    /**
     * Distance from left edge of window to right edge of main view.
     * Computed in @ref #updateRects. Changing of this variable
     * has no effect.
     * Avoid using it, it might be removed in future.
     */
    int view_right;



  /**
   * This function tries to restore the toplevel widget as defined number (1..X)
   * If the session did not contain that high number, the configuration
   * is not changed and False returned.
   *
   * That means clients could simply do the following:
   * <pre>
   * if (kapp->isRestored()){
   *   int n = 1;
   *   while (KTMainWindow::canBeRestored(n)){
   *     (new childTLW)->restore(n);
   *     n++;
   *   }
   * } else {
   * // create default application as usual
   * }
   * </pre>
   * Note that "show()" is called implicit in restore.
   *
   * With this you can easily restore all toplevel windows of your
   * application.
   *
   * If your application uses different kinds of toplevel
   * windows, then you can use KTMainWindow::classNameOfToplevel(n)
   * to determine the exact type before calling the childTLW
   * constructor in the example from above.
   *
   * If your client has only one kind of toplevel widgets (which should
   * be pretty usual) then you should use the RESTORE-macro:
   *
   * <pre>
   * if (kapp->isRestored())
   *   RESTORE(childTLW)
   * else {
   * // create default application as usual
   * }
   * </pre>
   *
   * The macro expands to the term above but is easier to use and
   * less code to write.
   *
   * @see #restore
   * @see #classNameOfToplevel
   *
   *(Matthias)
   */
  static bool canBeRestored(int number);


  /**
   * Returns the className of the numberth toplevel window which
   * should be restored. This is only usefull if you application uses
   * different kinds of toplevel windows. (Matthias)
   */
  static const QString classNameOfToplevel(int number);

  /**
   * Restores the specified number. Returns "False" if this
   * fails, otherwise returns "True" and shows the window
   * You should call @ref canBeRestored first.
   */
  bool restore(int number);

  /**
    * Tells the session manager wether the window contains
    * unsaved data which cannot be stored in temporary files
    * during saveYourself. Note that this is somewhat bad style.
    * A really good KDE application should store everything in
    * temporary recover files. Kapplication has some nifty support
    * for that.
    *
    * Default is False == No unsaved data.
    * @see KApplication::tempSaveName
    */
  void setUnsavedData( bool );


protected:
   /**
    * Default implementation calls @ref #updateRects if main widget
    * is resizable. If mainWidget is not resizable it does
    * nothing. You shouldn't need to override this function.
    */
    virtual void resizeEvent( QResizeEvent *e);
    /**
     * Default implementation just calls repaint (FALSE); You may
     * reimplement this function if you want to.
     */
    virtual void focusInEvent ( QFocusEvent *);
    /**
     * Default implementation just calls repaint (FALSE); You may
     * reimplement this function if you want to.
     */
    virtual void focusOutEvent ( QFocusEvent *);

    /**
      * This is called when the widget is closed.
      * The default implementation will also destroy the
      * widget.(Matthias)
      */
    virtual void closeEvent ( QCloseEvent *);

   /**
    * KTMainWindow has the nice habbit that it will exit the
    * application when the very last KTMainWindow is
    * closed. Some applications may not want this default
    * behaviour, for example if the application wants to ask the user
    * wether he really wants to quit the application.  This can be
    * achived by overloading the @ref #queryExit () method.  The default
    * implementation simply returns TRUE, which means that the
    * application will be quitted. FALSE will cancel the exiting
    * process. (Matthias)
    * Note, if you cancel exiting, your application will live on without
    * windows (sven).
    * @see #queryClose
    */
    virtual bool queryExit();

    /**
     * Called before window is closed.
     * Reimplement this function if you want to ignore/accept close event.
     * Default implementation returns true. Returning false will ignore
     * closing. (sven)
     * @see #queryExit
     */
    virtual bool queryClose();

    
  /**
   * Save your instance-specific properties.
   * You MUST NOT change the group of the kconfig object,
   * since KTMainWindow uses one group for each window.
   * Please overload these function in childclasses.
   *
   * Note that any interaction or X calls are forbidden
   * in these functions!
   *
   * (Matthias)
   */
  virtual void saveProperties(KConfig*){};

  /**
  * Read your instance-specific properties.
  */
  virtual void readProperties(KConfig*){};
  /**
   * This method is called, when @ref KApplication emits signal saveYourself
   * and after KTMainWindow has verified that it is "main" top-level window.
   * So this method will be called only once and not in every widget.
   * Override it if you need to save other data about your documents on
   * session end. sessionConfig is a config to which that data should be
   * saved. Normaly, you don't need this function. But if you want to save
   * data about your documents that are not in opened windows you might need
   * it.
   *
   * Default implementation does nothing.
   */
  virtual void saveData(KConfig* sessionConfig);

protected slots:
    /**
     * Updates child window geometry. This is automatically called
     * when the window is created, new components are added or the
     * window is resized, or showd.
     * updateRects handles fixed-size widgets properly.
     *
     * Override it if you intend to manage the children yourself.
     * You normally do not need or want to do this.
     */
    virtual void updateRects();

 private slots:
  /**
   * React on the request of the session manager (Matthias)
   */
    void saveYourself();

    /**
     * Notices when toolbar is deleted.
     */
    void toolbarKilled();

    /**
     * Notices when menubar is killed.
     */
    void menubarKilled();


public:

  /**
   * List of members of KTMainWindow class
   */
  static QList<KTMainWindow>* memberList;

private:
    /**
     * List of toolbars.
     */
    QList <KToolBar> toolbars;

    /**
     * Main widget. If you want fixed-widget just call setFixedSize(w.h)
     * on your mainwidget.
     * You should not setFixedSize on KTMainWindow.
     */
    QWidget *kmainwidget;

    /**
     * Menubar.
     */
    KMenuBar *kmenubar;

    /**
     * Statusbar
     */
    KStatusBar *kstatusbar;

    /**
     * Frame around main widget
     */
    QFrame *kmainwidgetframe;

    /**
     * Stores the width of the view frame
     */
    int borderwidth;

    /**
     * True if toolbars are killed by this destructor.
     */
    bool localKill;


  // Matthias
protected:
  void savePropertiesInternal (KConfig*, int);
  bool readPropertiesInternal (KConfig*, int);
};


#define RESTORE(type) { int n = 1;\
    while (KTMainWindow::canBeRestored(n)){\
      (new type)->restore(n);\
      n++;}}

#endif