X-Git-Url: https://git.saurik.com/wxWidgets.git/blobdiff_plain/7c913512a4c9f36e11e07ea707002fab1608d324..3201a1046ba71ba8e5ef2ed694fde34d12f743f3:/interface/toplevel.h diff --git a/interface/toplevel.h b/interface/toplevel.h index 318edbf9ba..e87b3b31a3 100644 --- a/interface/toplevel.h +++ b/interface/toplevel.h @@ -1,33 +1,60 @@ ///////////////////////////////////////////////////////////////////////////// // Name: toplevel.h -// Purpose: documentation for wxTopLevelWindow class +// Purpose: interface of wxTopLevelWindow // Author: wxWidgets team // RCS-ID: $Id$ // 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} - @seealso - wxTopLevelWindow::SetTransparent + @see wxDialog, wxFrame */ class wxTopLevelWindow : public wxWindow { public: /** Returns @true if the platform supports making the window translucent. - - @sa SetTransparent() + + @see SetTransparent() */ virtual bool CanSetTransparent(); @@ -38,348 +65,362 @@ public: /** Centres the window on screen. - + @param direction - Specifies the direction for the centering. May be wxHORIZONTAL, wxVERTICAL - or wxBOTH. - - @sa wxWindow::CentreOnParent + Specifies the direction for the centering. May be @c wxHORIZONTAL, + @c wxVERTICAL or @c wxBOTH. + + @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); + 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(); + wxWindow* GetDefaultItem() const; /** - Returns the standard icon of the window. The icon will be invalid if it hadn't - been previously set by SetIcon(). - - @sa GetIcons() + 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 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. - - @sa wxIconBundle + 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 */ - const wxIconBundle GetIcons(); + const wxIconBundle GetIcons() const; /** Gets a string containing the window title. - - @sa SetTitle() + + @see SetTitle() */ - wxString GetTitle(); + 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); /** Iconizes or restores the window. - + @param iconize - If @true, iconizes the window; if @false, shows and restores it. - - @sa IsIconized(), Maximize(). + If @true, iconizes the window; if @false, shows and restores it. + + @see IsIconized(), Maximize(). */ void Iconize(bool iconize); /** Returns @true if this window is currently active, i.e. if the user is - currently - working with it. + currently working with it. */ - bool IsActive(); + 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(); + virtual bool IsAlwaysMaximized() const; /** Returns @true if the window is in fullscreen mode. - - @sa ShowFullScreen() + + @see ShowFullScreen() */ bool IsFullScreen(); /** Returns @true if the window is iconized. */ - bool IsIconized(); + bool IsIconized() const; /** Returns @true if the window is maximized. */ - bool IsMaximized(); + 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. - - @sa UseNativeDecorations(), - UseNativeDecorationsByDefault() + 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() */ - bool IsUsingNativeDecorations(); + bool IsUsingNativeDecorations() const; /** Maximizes or restores the window. - + @param maximize - If @true, maximizes the window, otherwise it restores it. - - @sa Iconize() + If @true, maximizes the window, otherwise it restores it. + + @see Iconize() */ void Maximize(bool maximize); /** - Use a system-dependent way to attract users attention to the window when it is - in background. - - @e 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); /** - Changes the default item for the panel, usually @e win is a button. - - @sa GetDefaultItem() + Changes the default item for the panel, usually @a win is a button. + + @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. - - @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. + 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. + + @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. - - @sa wxIconBundle. + The icons to associate with this window. + + @see wxIconBundle. */ 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. - + 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. - - @sa SetRightMenu(). + The menu to be opened after pressing this hardware button. + + @see SetRightMenu(). */ void SetLeftMenu(int id = wxID_ANY, const wxString& label = wxEmptyString, - wxMenu * subMenu = @NULL); + 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. - + 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. - - @sa SetLeftMenu(). + The menu to be opened after pressing this hardware button. + + @see SetLeftMenu(). */ void SetRightMenu(int id = wxID_ANY, const wxString& label = wxEmptyString, - wxMenu * subMenu = @NULL); + wxMenu* subMenu = NULL); /** 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). - + Specifies the increment for sizing the width (GTK/Motif/Xt only). @param incH - Specifies the increment for sizing the height (GTK/Motif/Xt only). - + Specifies the increment for sizing the height (GTK/Motif/Xt only). + + @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(). + + */ + 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). - + 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. - */ - virtual void SetSizeHints(int minW, int minH, int maxW=-1, - int maxH=-1, - int incW=-1, - int incH=-1); + 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); - //@} + const wxSize& maxSize = wxDefaultSize, + const wxSize& incSize = wxDefaultSize); /** Sets the window title. - + @param title - The window title. - - @sa GetTitle() + The window title. + + @see GetTitle() */ 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(); + virtual bool ShouldPreventAppExit() const; /** - Depending on the value of @e show parameter the window is either shown full - screen or restored to its normal state. @e 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. - - @sa IsFullScreen() + + @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: - - @sa UseNativeDecorationsByDefault(), - IsUsingNativeDecorations() + 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() */ - void UseNativeDecorations(bool native = @true); + 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 @e 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); + void UseNativeDecorationsByDefault(bool native = true); }; +