adding a app-defined event seems to quit inner eventloops like eg the popup of the...

[wxWidgets.git] / interface / wx / notebook.h

diff --git a/interface/wx/notebook.h b/interface/wx/notebook.h
index 1ce4eafcdd66ea3cf4dd5cafd8c769680f256980..59829ac0d82fc7d3ab38a3033bda250d6ad06b65 100644 (file)
--- a/interface/wx/notebook.h
+++ b/interface/wx/notebook.h
@@ -1,76 +1,30 @@
 /////////////////////////////////////////////////////////////////////////////
 // Name:        notebook.h
 /////////////////////////////////////////////////////////////////////////////
 // Name:        notebook.h

-// Purpose:     interface of wxNotebookEvent
+// Purpose:     interface of wxNotebook

 // Author:      wxWidgets team
 // RCS-ID:      $Id$
 // Author:      wxWidgets team
 // RCS-ID:      $Id$

-// Licence:     wxWindows license
+// Licence:     wxWindows licence

 /////////////////////////////////////////////////////////////////////////////
 
 /////////////////////////////////////////////////////////////////////////////
 

-/**
-    @class wxNotebookEvent
-
-    This class represents the events generated by a notebook control: currently,
-    there are two of them. The PAGE_CHANGING event is sent before the current
-    page is changed. It allows the program to examine the current page (which
-    can be retrieved with
-    wxNotebookEvent::GetOldSelection) and to veto the page
-    change by calling wxNotifyEvent::Veto if, for example, the
-    current values in the controls of the old page are invalid.
-
-    The second event - PAGE_CHANGED - is sent after the page has been changed and
-    the program cannot veto it any more, it just informs it about the page change.
-
-    To summarize, if the program is interested in validating the page values
-    before allowing the user to change it, it should process the PAGE_CHANGING
-    event, otherwise PAGE_CHANGED is probably enough. In any case, it is probably
-    unnecessary to process both events at once.
-
-    @library{wxcore}
-    @category{events}
-
-    @see wxNotebook
-*/
-class wxNotebookEvent : public wxNotifyEvent
+enum

 {
 {

-public:
-    /**
-        Constructor (used internally by wxWidgets only).
-    */
-    wxNotebookEvent(wxEventType eventType = wxEVT_NULL, int id = 0,
-                    int sel = -1,
-                    int oldSel = -1);
-
-    /**
-        Returns the page that was selected before the change, -1 if none was selected.
-    */
-    int GetOldSelection() const;
-
-    /**
-        Returns the currently selected page, or -1 if none was selected.
-        @note under Windows, GetSelection() will return the same value as
-        GetOldSelection() when called from
-        @c EVT_NOTEBOOK_PAGE_CHANGING handler and not the page which is going to
-        be selected. Also note that the values of selection and old selection returned
-        for an event generated in response to a call to
-        wxNotebook::SetSelection shouldn't be trusted
-        as they are currently inconsistent under different platforms (but in this case
-        you presumably don't need them anyhow as you already have the corresponding
-        information).
-    */
-    int GetSelection() const;
-
-    /**
-        Sets the id of the page selected before the change.
-    */
-    void SetOldSelection(int page);
-
-    /**
-        Sets the selection member variable.
-    */
-    void SetSelection(int page);
+    wxNB_HITTEST_NOWHERE = wxBK_HITTEST_NOWHERE,
+    wxNB_HITTEST_ONICON  = wxBK_HITTEST_ONICON,
+    wxNB_HITTEST_ONLABEL = wxBK_HITTEST_ONLABEL,
+    wxNB_HITTEST_ONITEM  = wxBK_HITTEST_ONITEM,
+    wxNB_HITTEST_ONPAGE  = wxBK_HITTEST_ONPAGE

 };
 
 };
 

+#define wxNB_DEFAULT          wxBK_DEFAULT
+#define wxNB_TOP              wxBK_TOP
+#define wxNB_BOTTOM           wxBK_BOTTOM
+#define wxNB_LEFT             wxBK_LEFT
+#define wxNB_RIGHT            wxBK_RIGHT

 
 

+#define wxNB_FIXEDWIDTH       0x0100
+#define wxNB_MULTILINE        0x0200
+#define wxNB_NOPAGETHEME      0x0400
+#define wxNB_FLAT             0x0800

 
 /**
     @class wxNotebook
 
 /**
     @class wxNotebook


@@ -78,11 +32,10 @@ public:
     This class represents a notebook control, which manages multiple windows with
     associated tabs.
 
     This class represents a notebook control, which manages multiple windows with
     associated tabs.
 

-    To use the class, create a wxNotebook object and call wxNotebook::AddPage or
-    wxNotebook::InsertPage,
-    passing a window to be used as the page. Do not explicitly delete the window
-    for a page that is currently
-    managed by wxNotebook.
+    To use the class, create a wxNotebook object and call wxNotebook::AddPage
+    or wxNotebook::InsertPage, passing a window to be used as the page.
+    Do not explicitly delete the window for a page that is currently managed by
+    wxNotebook.

 
     @b wxNotebookPage is a typedef for wxWindow.
 
 
     @b wxNotebookPage is a typedef for wxWindow.
 


@@ -106,13 +59,58 @@ public:
            (Windows CE only) Show tabs in a flat style.
     @endStyleTable
 
            (Windows CE only) Show tabs in a flat style.
     @endStyleTable
 

+    The styles wxNB_LEFT, RIGHT and BOTTOM are not supported under
+    Microsoft Windows XP when using visual themes.
+
+    @beginEventEmissionTable{wxBookCtrlEvent}
+    @event{EVT_NOTEBOOK_PAGE_CHANGED(id, func)}
+        The page selection was changed.
+        Processes a @c wxEVT_COMMAND_NOTEBOOK_PAGE_CHANGED event.
+    @event{EVT_NOTEBOOK_PAGE_CHANGING(id, func)}
+        The page selection is about to be changed.
+        Processes a @c wxEVT_COMMAND_NOTEBOOK_PAGE_CHANGING event.
+        This event can be vetoed.
+    @endEventTable
+
+
+    @section notebook_bg Page backgrounds
+
+    On Windows XP, the default theme paints a gradient on the notebook's pages.
+    If you wish to suppress this theme, for aesthetic or performance reasons,
+    there are three ways of doing it.
+    You can use @c wxNB_NOPAGETHEME to disable themed drawing for a particular
+    notebook, you can call wxSystemOptions::SetOption to disable it for the
+    whole application, or you can disable it for individual pages by using
+    SetBackgroundColour().
+
+    To disable themed pages globally:
+    @code
+    wxSystemOptions::SetOption("msw.notebook.themed-background", 0);
+    @endcode
+
+    Set the value to 1 to enable it again.
+    To give a single page a solid background that more or less fits in with the
+    overall theme, use:
+    @code
+    wxColour col = notebook->GetThemeBackgroundColour();
+    if (col.IsOk())
+    {
+        page->SetBackgroundColour(col);
+    }
+    @endcode
+
+    On platforms other than Windows, or if the application is not using Windows
+    themes, GetThemeBackgroundColour() will return an uninitialised colour object,
+    and the above code will therefore work on all platforms.
+
+

     @library{wxcore}
     @library{wxcore}

-    @category{miscwnd}
+    @category{bookctrl}
+    @appearance{notebook.png}

 
 

-    @see wxBookCtrl(), wxNotebookEvent, wxImageList, 
-    @ref page_samples_notebook "Notebook Sample"
+    @see wxBookCtrl, wxBookCtrlEvent, wxImageList, @ref page_samples_notebook

 */
 */

-class wxNotebook : public wxBookCtrl overview
+class wxNotebook : public wxBookCtrlBase

 {
 public:
 
 {
 public:
 


@@ -137,7 +135,7 @@ public:
         @param style
             The window style. See wxNotebook.
         @param name
         @param style
             The window style. See wxNotebook.
         @param name

-            The name of the control (used only under Motif).
+            The name of the control.

     */
     wxNotebook(wxWindow* parent, wxWindowID id,
                const wxPoint& pos = wxDefaultPosition,
     */
     wxNotebook(wxWindow* parent, wxWindowID id,
                const wxPoint& pos = wxDefaultPosition,


@@ -151,54 +149,8 @@ public:
     virtual ~wxNotebook();
 
     /**
     virtual ~wxNotebook();
 
     /**

-        Adds a new page.
-        The call to this function may generate the page changing events.
-
-        @param page
-            Specifies the new page.
-        @param text
-            Specifies the text for the new page.
-        @param select
-            Specifies whether the page should be selected.
-        @param imageId
-            Specifies the optional image index for the new page.
-
-        @return @true if successful, @false otherwise.
-
-        @remarks Do not delete the page, it will be deleted by the notebook.
-
-        @see InsertPage()
-    */
-    bool AddPage(wxNotebookPage* page, const wxString& text,
-                 bool select = false,
-                 int imageId = -1);
-
-    /**
-        Cycles through the tabs.
-        The call to this function generates the page changing events.
-    */
-    void AdvanceSelection(bool forward = true);
-
-    /**
-        Sets the image list for the page control and takes ownership of
-        the list.
-
-        @see wxImageList, SetImageList()
-    */
-    void AssignImageList(wxImageList* imageList);
-
-    /**
-        Changes the selection for the given page, returning the previous selection.
-        The call to this function does not generate the page changing events.
-        This is the only difference with SetSelection(). See 
-        @ref overview_eventhandling_prog "User Generated Events"
-        for more infomation.
-    */
-    virtual int ChangeSelection(size_t page);
-
-    /**
-        Creates a notebook control. See wxNotebook() for a description
-        of the parameters.
+        Creates a notebook control.
+        See wxNotebook() for a description of the parameters.

     */
     bool Create(wxWindow* parent, wxWindowID id,
                 const wxPoint& pos = wxDefaultPosition,
     */
     bool Create(wxWindow* parent, wxWindowID id,
                 const wxPoint& pos = wxDefaultPosition,


@@ -206,175 +158,45 @@ public:
                 long style = 0,
                 const wxString& name = wxNotebookNameStr);
 
                 long style = 0,
                 const wxString& name = wxNotebookNameStr);
 

-    /**
-        Deletes all pages.
-    */
-    virtual bool DeleteAllPages();
-
-    /**
-        Deletes the specified page, and the associated window.
-        The call to this function generates the page changing events.
-    */
-    bool DeletePage(size_t page);
-
-    /**
-        Returns the currently selected notebook page or @NULL.
-    */
-    wxWindow* GetCurrentPage() const;
-
-    /**
-        Returns the associated image list.
-
-        @see wxImageList, SetImageList()
-    */
-    wxImageList* GetImageList() const;
-
-    /**
-        Returns the window at the given page position.
-    */
-    wxNotebookPage* GetPage(size_t page);
-
-    /**
-        Returns the number of pages in the notebook control.
-    */
-    size_t GetPageCount() const;
-
-    /**
-        Returns the image index for the given page.
-    */
-    virtual int GetPageImage(size_t nPage) const;
-
-    /**
-        Returns the string for the given page.
-    */
-    virtual wxString GetPageText(size_t nPage) const;

 
     /**
         Returns the number of rows in the notebook control.
     */
     virtual int GetRowCount() const;
 
 
     /**
         Returns the number of rows in the notebook control.
     */
     virtual int GetRowCount() const;
 

-    /**
-        Returns the currently selected page, or -1 if none was selected.
-        Note that this method may return either the previously or newly selected page
-        when called from the @c EVT_NOTEBOOK_PAGE_CHANGED handler depending on
-        the platform and so
-        wxNotebookEvent::GetSelection should be
-        used instead in this case.
-    */
-    virtual int GetSelection() const;
-

     /**
         If running under Windows and themes are enabled for the application, this
     /**
         If running under Windows and themes are enabled for the application, this

-        function
-        returns a suitable colour for painting the background of a notebook page, and
-        can be passed
-        to @c SetBackgroundColour. Otherwise, an uninitialised colour will be returned.
-    */
-    virtual wxColour GetThemeBackgroundColour() const;
-
-    /**
-        Returns the index of the tab at the specified position or @c wxNOT_FOUND
-        if none. If @a flags parameter is non-@NULL, the position of the point
-        inside the tab is returned as well.
-
-        @param pt
-            Specifies the point for the hit test.
-        @param flags
-            Return value for detailed information. One of the following values:
-            <TABLE><TR><TD>wxBK_HITTEST_NOWHERE</TD>
-            <TD>There was no tab under this point.</TD></TR>
-            <TR><TD>wxBK_HITTEST_ONICON</TD>
-            <TD>The point was over an icon (currently wxMSW only).</TD></TR>
-            <TR><TD>wxBK_HITTEST_ONLABEL</TD>
-            <TD>The point was over a label (currently wxMSW only).</TD></TR>
-            <TR><TD>wxBK_HITTEST_ONITEM</TD>
-            <TD>The point was over an item, but not on the label or icon.</TD></TR>
-            <TR><TD>wxBK_HITTEST_ONPAGE</TD>
-            <TD>The point was over a currently selected page, not over any tab.
-            Note that this flag is present only if wxNOT_FOUND is returned.</TD></TR>
-            </TABLE>
-@return Returns the zero-based tab index or wxNOT_FOUND if there is no
-                 tab at the specified position.
-    */
-    virtual int HitTest(const wxPoint& pt, long* flags = NULL) const;
-
-    /**
-        Inserts a new page at the specified position.
-
-        @param index
-            Specifies the position for the new page.
-        @param page
-            Specifies the new page.
-        @param text
-            Specifies the text for the new page.
-        @param select
-            Specifies whether the page should be selected.
-        @param imageId
-            Specifies the optional image index for the new page.
-
-        @return @true if successful, @false otherwise.
+        function returns a suitable colour for painting the background of a notebook
+        page, and can be passed to SetBackgroundColour().

 
 

-        @remarks Do not delete the page, it will be deleted by the notebook.
-
-        @see AddPage()
+        Otherwise, an uninitialised colour will be returned.

     */
     */

-    bool InsertPage(size_t index, wxNotebookPage* page,
-                    const wxString& text,
-                    bool select = false,
-                    int imageId = -1);
+    virtual wxColour GetThemeBackgroundColour() const;

 
     /**
         An event handler function, called when the page selection is changed.
 
 
     /**
         An event handler function, called when the page selection is changed.
 

-        @see wxNotebookEvent
-    */
-    void OnSelChange(wxNotebookEvent& event);
-
-    /**
-        Deletes the specified page, without deleting the associated window.
-    */
-    bool RemovePage(size_t page);
-
-    /**
-        Sets the image list for the page control. It does not take
-        ownership of the image list, you must delete it yourself.
-
-        @see wxImageList, AssignImageList()
+        @see wxBookCtrlEvent

     */
     */

-    void SetImageList(wxImageList* imageList);
+    void OnSelChange(wxBookCtrlEvent& event);

 
     /**
         Sets the amount of space around each page's icon and label, in pixels.
 
     /**
         Sets the amount of space around each page's icon and label, in pixels.

+

         @note The vertical padding cannot be changed in wxGTK.
     */
         @note The vertical padding cannot be changed in wxGTK.
     */

-    void SetPadding(const wxSize& padding);
+    virtual void SetPadding(const wxSize& padding);

 
 

-    /**
-        Sets the image index for the given page. @a image is an index into
-        the image list which was set with SetImageList().
-    */
+    // implementations of pure virtuals
+    virtual int GetPageImage(size_t nPage) const;

     virtual bool SetPageImage(size_t page, int image);
     virtual bool SetPageImage(size_t page, int image);

-
-    /**
-        Sets the width and height of the pages.
-        @note This method is currently not implemented for wxGTK.
-    */
-    virtual void SetPageSize(const wxSize& size);
-
-    /**
-        Sets the text for the given page.
-    */
+    virtual wxString GetPageText(size_t nPage) const;

     virtual bool SetPageText(size_t page, const wxString& text);
     virtual bool SetPageText(size_t page, const wxString& text);

-
-    /**
-        Sets the selection for the given page, returning the previous selection.
-        The call to this function generates the page changing events.
-        This function is deprecated and should not be used in new code. Please use the
-        ChangeSelection() function instead.
-
-        @see GetSelection()
-    */
+    virtual int GetSelection() const;

     virtual int SetSelection(size_t page);
     virtual int SetSelection(size_t page);

+    virtual int ChangeSelection(size_t page);
+    virtual bool InsertPage(size_t index, wxWindow * page, const wxString & text,
+                            bool select = false, int imageId = NO_IMAGE);
+

 };
 
 };