/////////////////////////////////////////////////////////////////////////////
// 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();
/**
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);
};
+
projects / wxWidgets.git / blobdiff