X-Git-Url: https://git.saurik.com/wxWidgets.git/blobdiff_plain/90ae878ffc2a80a74995ab0c3d26170acdf149b9..50d4763f1710f6e45ac6af7112d1ce9effe93bc4:/interface/wx/notebook.h diff --git a/interface/wx/notebook.h b/interface/wx/notebook.h index 1ce4eafcdd..59829ac0d8 100644 --- a/interface/wx/notebook.h +++ b/interface/wx/notebook.h @@ -1,76 +1,30 @@ ///////////////////////////////////////////////////////////////////////////// // Name: notebook.h -// Purpose: interface of wxNotebookEvent +// Purpose: interface of wxNotebook // 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 @@ -78,11 +32,10 @@ public: 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. @@ -106,13 +59,58 @@ public: (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} - @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: @@ -137,7 +135,7 @@ public: @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, @@ -151,54 +149,8 @@ public: 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, @@ -206,175 +158,45 @@ public: 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 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 - 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: - - - - - - - - - - -
wxBK_HITTEST_NOWHEREThere was no tab under this point.
wxBK_HITTEST_ONICONThe point was over an icon (currently wxMSW only).
wxBK_HITTEST_ONLABELThe point was over a label (currently wxMSW only).
wxBK_HITTEST_ONITEMThe point was over an item, but not on the label or icon.
wxBK_HITTEST_ONPAGEThe point was over a currently selected page, not over any tab. - Note that this flag is present only if wxNOT_FOUND is returned.
-@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. - @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. + @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); - - /** - 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); - - /** - 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 ChangeSelection(size_t page); + virtual bool InsertPage(size_t index, wxWindow * page, const wxString & text, + bool select = false, int imageId = NO_IMAGE); + };