From: Bryan Petty Date: Thu, 8 May 2008 20:46:34 +0000 (+0000) Subject: More interface header reviews by Azriel Fasten, along with a simple item "add" group... X-Git-Url: https://git.saurik.com/wxWidgets.git/commitdiff_plain/f992f2ae260e437eeb729de602deee8bbef3b744 More interface header reviews by Azriel Fasten, along with a simple item "add" group for wxSizer. git-svn-id: https://svn.wxwidgets.org/svn/wx/wxWidgets/trunk@53498 c3d73ce0-8a6f-49c7-b76d-6d57e0e08775 --- diff --git a/interface/defs.h b/interface/defs.h index 47fd6ffaac..61b05d3599 100644 --- a/interface/defs.h +++ b/interface/defs.h @@ -6,6 +6,49 @@ // Licence: wxWindows license ///////////////////////////////////////////////////////////////////////////// +/** + Item kinds for use with wxMenu, wxMenuItem, and wxToolBar. + + @see wxMenu::Append(), wxMenuItem::wxMenuItem(), wxToolBar::AddTool() +*/ +enum wxItemKind +{ + wxITEM_SEPARATOR = -1, + + /** + Normal tool button / menu item. + + @see wxToolBar::AddTool(), wxMenu::AppendItem(). + */ + wxITEM_NORMAL, + + /** + Check (or toggle) tool button / menu item. + + @see wxToolBar::AddCheckTool(), wxMenu::AppendCheckItem(). + */ + wxITEM_CHECK, + + /** + Radio tool button / menu item. + + @see wxToolBar::AddRadioTool(), wxMenu::AppendRadioItem(). + */ + wxITEM_RADIO, + + /** + Normal tool button with a dropdown arrow next to it. Clicking the + dropdown arrow sends a @c wxEVT_COMMAND_TOOL_DROPDOWN_CLICKED event and may + also display the menu previously associated with the item with + wxToolBar::SetDropdownMenu(). Currently this type of tools is supported + under MSW and GTK. + */ + wxITEM_DROPDOWN, + + wxITEM_MAX +}; + + /** Paper size types for use with the printing framework. @@ -316,3 +359,4 @@ void wxVaCopy(va_list argptrDst, va_list argptrSrc); //@} + diff --git a/interface/sizer.h b/interface/sizer.h index df82b37970..c208e9973e 100644 --- a/interface/sizer.h +++ b/interface/sizer.h @@ -767,6 +767,9 @@ public: */ ~wxSizer(); + /** @name Item Management */ + //@{ + /** Appends a child to the sizer. @@ -940,6 +943,8 @@ public: */ wxSizerItem* AddStretchSpacer(int prop = 1); + //@} + /** This method is abstract and has to be overwritten by any derived class. Here, the sizer will do the actual calculation of its children's minimal sizes. diff --git a/interface/toolbook.h b/interface/toolbook.h index fc657cc92b..358adbd212 100644 --- a/interface/toolbook.h +++ b/interface/toolbook.h @@ -10,32 +10,34 @@ @class wxToolbook @wxheader{toolbook.h} - wxToolbook is a class similar to wxNotebook but which - uses a wxToolBar to show the labels instead of the - tabs. + wxToolbook is a class similar to wxNotebook but which uses a wxToolBar to + show the labels instead of the tabs. - There is no documentation for this class yet but its usage is - identical to wxNotebook (except for the features clearly related to tabs - only), so please refer to that class documentation for now. You can also - use the @ref overview_samplenotebook "notebook sample" to see wxToolbook in - action. + There is no documentation for this class yet but its usage is identical to + wxNotebook (except for the features clearly related to tabs only), so please + refer to that class documentation for now. You can also use the + @ref page_samples_notebook to see wxToolbook in action. @beginStyleTable @style{wxTBK_BUTTONBAR} - Use wxButtonToolBar-based implementation under Mac OS (ignored - under other platforms.) + Use wxButtonToolBar-based implementation under Mac OS (ignored under + other platforms). @style{wxTBK_HORZ_LAYOUT} - Shows the text and the icons alongside, not vertically stacked - (only implement under Windows and GTK 2 platforms as it relies on - wxTB_HORZ_LAYOUT flag support). + Shows the text and the icons alongside, not vertically stacked (only + implement under Windows and GTK 2 platforms as it relies on @c + wxTB_HORZ_LAYOUT flag support). @endStyleTable + The common wxBookCtrl styles described in the @ref overview_bookctrl are + also supported. + @library{wxcore} - @category{FIXME} + @category{miscwnd} - @see wxBookCtrl(), wxNotebook, @ref overview_samplenotebook "notebook sample" + @see @ref overview_bookctrl, wxBookCtrlBase, wxNotebook, + @ref page_samples_notebook */ -class wxToolbook : public wxBookCtrl overview +class wxToolbook : public wxBookCtrlBase { public: diff --git a/interface/tooltip.h b/interface/tooltip.h index 8c39060810..6d6779198a 100644 --- a/interface/tooltip.h +++ b/interface/tooltip.h @@ -10,13 +10,11 @@ @class wxToolTip @wxheader{tooltip.h} - This class holds information about a tooltip associated with a window - (see wxWindow::SetToolTip). + This class holds information about a tooltip associated with a window (see + wxWindow::SetToolTip()). - The four static methods, wxToolTip::Enable, - wxToolTip::SetDelay - wxToolTip::SetAutoPop and - wxToolTip::SetReshow can be used to globally + The four static methods, wxToolTip::Enable(), wxToolTip::SetDelay() + wxToolTip::SetAutoPop() and wxToolTip::SetReshow() can be used to globally alter tooltips behaviour. @library{wxcore} @@ -32,7 +30,8 @@ public: /** Enable or disable tooltips globally. - May not be supported on all platforms (eg. wxCocoa). + + @note May not be supported on all platforms (eg. wxCocoa). */ static void Enable(bool flag); @@ -47,21 +46,24 @@ public: wxWindow* GetWindow() const; /** - Set the delay after which the tooltip disappears or how long a - tooltip remains visible. - May not be supported on all platforms (eg. wxCocoa, GTK, Palmos). + Set the delay after which the tooltip disappears or how long a tooltip + remains visible. + + @note May not be supported on all platforms (eg. wxCocoa, GTK, Palmos). */ static void SetAutoPop(long msecs); /** Set the delay after which the tooltip appears. - May not be supported on all platforms (eg. wxCocoa). + + @note May not be supported on all platforms (eg. wxCocoa). */ static void SetDelay(long msecs); /** Set the delay between subsequent tooltips to appear. - May not be supported on all platforms (eg. wxCocoa, GTK, Palmos). + + @note May not be supported on all platforms (eg. wxCocoa, GTK, Palmos). */ static void SetReshow(long msecs); diff --git a/interface/toplevel.h b/interface/toplevel.h index b036c7837e..e87b3b31a3 100644 --- a/interface/toplevel.h +++ b/interface/toplevel.h @@ -6,19 +6,47 @@ // Licence: wxWindows license ///////////////////////////////////////////////////////////////////////////// +/** + Styles used with wxTopLevelWindow::RequestUserAttention(). +*/ +enum +{ + wxUSER_ATTENTION_INFO = 1, ///< Requests user attention, + wxUSER_ATTENTION_ERROR = 2 ///< Results in a more drastic action. +}; + +/** + Styles used with wxTopLevelWindow::ShowFullScreen(). +*/ +enum +{ + wxFULLSCREEN_NOMENUBAR = 0x0001, ///< Don't display the menu bar. + wxFULLSCREEN_NOTOOLBAR = 0x0002, ///< Don't display toolbar bars. + wxFULLSCREEN_NOSTATUSBAR = 0x0004, ///< Don't display the status bar. + wxFULLSCREEN_NOBORDER = 0x0008, ///< Don't display any border. + wxFULLSCREEN_NOCAPTION = 0x0010, ///< Don't display a caption. + + /** + Combination of all above, will display the least possible. + */ + wxFULLSCREEN_ALL = wxFULLSCREEN_NOMENUBAR | wxFULLSCREEN_NOTOOLBAR | + wxFULLSCREEN_NOSTATUSBAR | wxFULLSCREEN_NOBORDER | + wxFULLSCREEN_NOCAPTION +}; + /** @class wxTopLevelWindow @wxheader{toplevel.h} - wxTopLevelWindow is a common base class for wxDialog and - wxFrame. It is an abstract base class meaning that you never - work with objects of this class directly, but all of its methods are also - applicable for the two classes above. + wxTopLevelWindow is a common base class for wxDialog and wxFrame. It is an + abstract base class meaning that you never work with objects of this class + directly, but all of its methods are also applicable for the two classes + above. @library{wxcore} @category{managedwnd} - @see wxTopLevelWindow::SetTransparent + @see wxDialog, wxFrame */ class wxTopLevelWindow : public wxWindow { @@ -39,45 +67,45 @@ public: Centres the window on screen. @param direction - Specifies the direction for the centering. May be wxHORIZONTAL, wxVERTICAL - or wxBOTH. + Specifies the direction for the centering. May be @c wxHORIZONTAL, + @c wxVERTICAL or @c wxBOTH. - @see wxWindow::CentreOnParent + @see wxWindow::CentreOnParent() */ void CentreOnScreen(int direction = wxBOTH); /** - Enables or disables the Close button (most often in the right - upper corner of a dialog) and the Close entry of the system - menu (most often in the left upper corner of the dialog). - Currently only implemented for wxMSW and wxGTK. Returns - @true if operation was successful. This may be wrong on - X11 (including GTK+) where the window manager may not support - this operation and there is no way to find out. + Enables or disables the Close button (most often in the right upper + corner of a dialog) and the Close entry of the system menu (most often + in the left upper corner of the dialog). + + Currently only implemented for wxMSW and wxGTK. + + Returns @true if operation was successful. This may be wrong on X11 + (including GTK+) where the window manager may not support this operation + and there is no way to find out. */ bool EnableCloseButton(bool enable = true); /** - Returns a pointer to the button which is the default for this window, or @c - @NULL. - The default button is the one activated by pressing the Enter key. + Returns a pointer to the button which is the default for this window, or + @c @NULL. The default button is the one activated by pressing the Enter + key. */ wxWindow* GetDefaultItem() const; /** - Returns the standard icon of the window. The icon will be invalid if it hadn't - been previously set by SetIcon(). + Returns the standard icon of the window. The icon will be invalid if it + hadn't been previously set by SetIcon(). @see GetIcons() */ const wxIcon GetIcon() const; /** - Returns all icons associated with the window, there will be none of them if - neither SetIcon() nor - SetIcons() had been called before. - Use GetIcon() to get the main icon of the - window. + Returns all icons associated with the window, there will be none of them + if neither SetIcon() nor SetIcons() had been called before. Use + GetIcon() to get the main icon of the window. @see wxIconBundle */ @@ -91,10 +119,9 @@ public: wxString GetTitle() const; /** - Unique to the wxWinCE port. Responds to showing/hiding SIP (soft input panel) - area and resize - window accordingly. Override this if you want to avoid resizing or do additional - operations. + Unique to the wxWinCE port. Responds to showing/hiding SIP (soft input + panel) area and resize window accordingly. Override this if you want to + avoid resizing or do additional operations. */ virtual bool HandleSettingChange(WXWPARAM wParam, WXLPARAM lParam); @@ -111,15 +138,14 @@ public: /** Returns @true if this window is currently active, i.e. if the user is - currently - working with it. + currently working with it. */ bool IsActive() const; /** - Returns @true if this window is expected to be always maximized, either due - to platform policy - or due to local policy regarding particular class. + Returns @true if this window is expected to be always maximized, either + due to platform policy or due to local policy regarding particular + class. */ virtual bool IsAlwaysMaximized() const; @@ -141,9 +167,10 @@ public: bool IsMaximized() const; /** - @b @c This method is specific to wxUniversal port - Returns @true if this window is using native decorations, @false if we draw - them ourselves. + This method is specific to wxUniversal port. + + Returns @true if this window is using native decorations, @false if we + draw them ourselves. @see UseNativeDecorations(), UseNativeDecorationsByDefault() @@ -161,15 +188,21 @@ public: void Maximize(bool maximize); /** - Use a system-dependent way to attract users attention to the window when it is - in background. - @a flags may have the value of either @c wxUSER_ATTENTION_INFO - (default) or @c wxUSER_ATTENTION_ERROR which results in a more drastic + Use a system-dependent way to attract users attention to the window when + it is in background. + + @a flags may have the value of either @c ::wxUSER_ATTENTION_INFO + (default) or @c ::wxUSER_ATTENTION_ERROR which results in a more drastic action. When in doubt, use the default value. - Note that this function should normally be only used when the application is - not already in foreground. - This function is currently implemented for Win32 where it flashes the - window icon in the taskbar, and for wxGTK with task bars supporting it. + + + @note This function should normally be only used when the application + is not already in foreground. + + This function is currently implemented for Win32 where it flashes + the window icon in the taskbar, and for wxGTK with task bars + supporting it. + */ void RequestUserAttention(int flags = wxUSER_ATTENTION_INFO); @@ -178,25 +211,27 @@ public: @see GetDefaultItem() */ - void SetDefaultItem(wxWindow win); + void SetDefaultItem(wxWindow* win); /** Sets the icon for this window. @param icon - The icon to associate with this window. + The wxIcon to associate with this window. + + @remarks The window takes a 'copy' of @a icon, but since it uses + reference counting, the copy is very quick. It is safe to + delete @a icon after calling this function. - @remarks The window takes a 'copy' of icon, but since it uses reference - counting, the copy is very quick. It is safe to delete - icon after calling this function. + @see wxIcon */ void SetIcon(const wxIcon& icon); /** - Sets several icons of different sizes for this window: this allows to use - different icons for different situations (e.g. task switching bar, taskbar, - window title bar) instead of scaling, with possibly bad looking results, the - only icon set by SetIcon(). + Sets several icons of different sizes for this window: this allows to + use different icons for different situations (e.g. task switching bar, + taskbar, window title bar) instead of scaling, with possibly bad looking + results, the only icon set by SetIcon(). @param icons The icons to associate with this window. @@ -206,14 +241,14 @@ public: void SetIcons(const wxIconBundle& icons); /** - Sets action or menu activated by pressing left hardware button on the smart - phones. - Unavailable on full keyboard machines. + Sets action or menu activated by pressing left hardware button on the + smart phones. Unavailable on full keyboard machines. @param id Identifier for this button. @param label - Text to be displayed on the screen area dedicated to this hardware button. + Text to be displayed on the screen area dedicated to this hardware + button. @param subMenu The menu to be opened after pressing this hardware button. @@ -224,26 +259,24 @@ public: wxMenu* subMenu = NULL); /** - A simpler interface for setting the size hints than - SetSizeHints(). + A simpler interface for setting the size hints than SetSizeHints(). */ void SetMaxSize(const wxSize& size); /** - A simpler interface for setting the size hints than - SetSizeHints(). + A simpler interface for setting the size hints than SetSizeHints(). */ void SetMinSize(const wxSize& size); /** - Sets action or menu activated by pressing right hardware button on the smart - phones. - Unavailable on full keyboard machines. + Sets action or menu activated by pressing right hardware button on the + smart phones. Unavailable on full keyboard machines. @param id Identifier for this button. @param label - Text to be displayed on the screen area dedicated to this hardware button. + Text to be displayed on the screen area dedicated to this hardware + button. @param subMenu The menu to be opened after pressing this hardware button. @@ -255,41 +288,51 @@ public: /** If the platform supports it, sets the shape of the window to that - depicted by @e region. The system will not display or - respond to any mouse event for the pixels that lie outside of the - region. To reset the window to the normal rectangular shape simply - call @e SetShape again with an empty region. Returns @true if the - operation is successful. + depicted by @a region. The system will not display or respond to any + mouse event for the pixels that lie outside of the region. To reset the + window to the normal rectangular shape simply call SetShape() again with + an empty wxRegion. Returns @true if the operation is successful. */ bool SetShape(const wxRegion& region); - //@{ /** - Allows specification of minimum and maximum window sizes, and window size - increments. - If a pair of values is not set (or set to -1), no constraints will be used. + Allows specification of minimum and maximum window sizes, and window + size increments. If a pair of values is not set (or set to -1), no + constraints will be used. @param incW Specifies the increment for sizing the width (GTK/Motif/Xt only). @param incH Specifies the increment for sizing the height (GTK/Motif/Xt only). - @param incSize - Increment size (only taken into account under X11-based - ports such as wxGTK/wxMotif/wxX11). @remarks Notice that this function not only prevents the user from - resizing the window outside the given bounds but it - also prevents the program itself from doing it using - SetSize. + resizing the window outside the given bounds but it also + prevents the program itself from doing it using + wxWindow::SetSize(). + */ virtual void SetSizeHints(int minW, int minH, int maxW = -1, int maxH = -1, int incW = -1, int incH = -1); + + /** + Allows specification of minimum and maximum window sizes, and window + size increments. If a pair of values is not set (or set to -1), no + constraints will be used. + + @param incSize + Increment size (only taken into account under X11-based ports such + as wxGTK/wxMotif/wxX11). + + @remarks Notice that this function not only prevents the user from + resizing the window outside the given bounds but it also + prevents the program itself from doing it using + wxWindow::SetSize(). + */ void SetSizeHints(const wxSize& minSize, const wxSize& maxSize = wxDefaultSize, const wxSize& incSize = wxDefaultSize); - //@} /** Sets the window title. @@ -302,49 +345,59 @@ public: virtual void SetTitle(const wxString& title); /** - If the platform supports it will set the window to be translucent + If the platform supports it will set the window to be translucent. @param alpha - Determines how opaque or transparent the window will - be, if the platform supports the opreration. A value of 0 sets the - window to be fully transparent, and a value of 255 sets the window - to be fully opaque. + Determines how opaque or transparent the window will be, if the + platform supports the opreration. A value of 0 sets the window to be + fully transparent, and a value of 255 sets the window to be fully + opaque. */ virtual bool SetTransparent(int alpha); /** - This virtual function is not meant to be called directly but can be overridden - to return @false (it returns @true by default) to allow the application to - close even if this, presumably not very important, window is still opened. - By default, the application stays alive as long as there are any open top level - windows. + This virtual function is not meant to be called directly but can be + overridden to return @false (it returns @true by default) to allow the + application to close even if this, presumably not very important, window + is still opened. By default, the application stays alive as long as + there are any open top level windows. */ virtual bool ShouldPreventAppExit() const; /** - Depending on the value of @a show parameter the window is either shown full - screen or restored to its normal state. @a style is a bit list containing - some or all of the following values, which indicate what elements of the window - to hide in full-screen mode: - wxFULLSCREEN_NOMENUBAR - wxFULLSCREEN_NOTOOLBAR - wxFULLSCREEN_NOSTATUSBAR - wxFULLSCREEN_NOBORDER - wxFULLSCREEN_NOCAPTION - wxFULLSCREEN_ALL (all of the above) + Depending on the value of @a show parameter the window is either shown + full screen or restored to its normal state. @a style is a bit list + containing some or all of the following values, which indicate what + elements of the window to hide in full-screen mode: + + - @c ::wxFULLSCREEN_NOMENUBAR + - @c ::wxFULLSCREEN_NOTOOLBAR + - @c ::wxFULLSCREEN_NOSTATUSBAR + - @c ::wxFULLSCREEN_NOBORDER + - @c ::wxFULLSCREEN_NOCAPTION + - @c ::wxFULLSCREEN_ALL (all of the above) + This function has not been tested with MDI frames. - Note that showing a window full screen also actually - @ref wxWindow::show Show()s if it hadn't been shown yet. + + @note Showing a window full screen also actually @ref wxWindow::Show() + "Show()"s the window if it isn't shown. @see IsFullScreen() */ bool ShowFullScreen(bool show, long style = wxFULLSCREEN_ALL); /** - @b @c This method is specific to wxUniversal port - Use native or custom-drawn decorations for this window only. Notice that to - have any effect this method must be called before really creating the window, - i.e. two step creation must be used: + This method is specific to wxUniversal port. + + Use native or custom-drawn decorations for this window only. Notice that + to have any effect this method must be called before really creating the + window, i.e. two step creation must be used: + + @code + MyFrame *frame = new MyFrame; // use default ctor + frame->UseNativeDecorations(false); // change from default "true" + frame->Create(parent, title, ...); // really create the frame + @endcode @see UseNativeDecorationsByDefault(), IsUsingNativeDecorations() @@ -352,16 +405,21 @@ public: void UseNativeDecorations(bool native = true); /** - @b @c This method is specific to wxUniversal port - Top level windows in wxUniversal port can use either system-provided window - decorations (i.e. title bar and various icons, buttons and menus in it) or draw - the decorations themselves. By default the system decorations are used if they - are available, but this method can be called with @a native set to @false to - change this for all windows created after this point. + This method is specific to wxUniversal port. + + Top level windows in wxUniversal port can use either system-provided + window decorations (i.e. title bar and various icons, buttons and menus + in it) or draw the decorations themselves. By default the system + decorations are used if they are available, but this method can be + called with @a native set to @false to change this for all windows + created after this point. + Also note that if @c WXDECOR environment variable is set, then custom - decorations are used by default and so it may make sense to call this method - with default argument if the application can't use custom decorations at all - for some reason. + decorations are used by default and so it may make sense to call this + method with default argument if the application can't use custom + decorations at all for some reason. + + @see UseNativeDecorations() */ void UseNativeDecorationsByDefault(bool native = true); };