[wxWidgets.git] / interface / toplevel.h

/////////////////////////////////////////////////////////////////////////////
// Name:        toplevel.h
// Purpose:     documentation for wxTopLevelWindow class
// Author:      wxWidgets team
// RCS-ID:      $Id$
// Licence:     wxWindows license
/////////////////////////////////////////////////////////////////////////////

/**
    @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.

    @library{wxcore}
    @category{managedwnd}

    @seealso
    wxTopLevelWindow::SetTransparent
*/
class wxTopLevelWindow : public wxWindow
{
public:
    /**
        Returns @true if the platform supports making the window translucent.
        
        @sa SetTransparent()
    */
    virtual bool CanSetTransparent();

    /**
        A synonym for CentreOnScreen().
    */
    void CenterOnScreen(int direction);

    /**
        Centres the window on screen.
        
        @param direction
        Specifies the direction for the centering. May be wxHORIZONTAL, wxVERTICAL
        or wxBOTH.
        
        @sa 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.
    */
    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.
    */
    wxWindow * GetDefaultItem();

    /**
        Returns the standard icon of the window. The icon will be invalid if it hadn't
        been previously set by SetIcon().
        
        @sa GetIcons()
    */
    const wxIcon GetIcon();

    /**
        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
    */
    const wxIconBundle GetIcons();

    /**
        Gets a string containing the window title.
        
        @sa SetTitle()
    */
    wxString GetTitle();

    /**
        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().
    */
    void Iconize(bool iconize);

    /**
        Returns @true if this window is currently active, i.e. if the user is
        currently
        working with it.
    */
    bool IsActive();

    /**
        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();

    /**
        Returns @true if the window is in fullscreen mode.
        
        @sa ShowFullScreen()
    */
    bool IsFullScreen();

    /**
        Returns @true if the window is iconized.
    */
    bool IsIconized();

    /**
        Returns @true if the window is maximized.
    */
    bool IsMaximized();

    /**
        @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()
    */
    bool IsUsingNativeDecorations();

    /**
        Maximizes or restores the window.
        
        @param maximize
        If @true, maximizes the window, otherwise it restores it.
        
        @sa 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
        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.
    */
    void RequestUserAttention(int flags = wxUSER_ATTENTION_INFO);

    /**
        Changes the default item for the panel, usually @e win is a button.
        
        @sa GetDefaultItem()
    */
    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.
    */
    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().
        
        @param icons
        The icons to associate with this window.
        
        @sa 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.
        
        @param id
        Identifier for this button.
        
        @param label
        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().
    */
    void SetLeftMenu(int id = wxID_ANY,
                     const wxString& label = wxEmptyString,
                     wxMenu * subMenu = @NULL);

    /**
        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().
    */
    void SetMinSize(const wxSize& size);

    /**
        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.
        
        @param subMenu
        The menu to be opened after pressing this hardware button.
        
        @sa SetLeftMenu().
    */
    void SetRightMenu(int id = wxID_ANY,
                      const wxString& label = wxEmptyString,
                      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.
    */
    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.
        
        @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.
    */
    virtual void SetSizeHints(int minW, int minH, int maxW=-1,
                              int maxH=-1,
                              int incW=-1,
                              int incH=-1);
    void SetSizeHints(const wxSize& minSize,
                      const wxSize& maxSize=wxDefaultSize,
                      const wxSize& incSize=wxDefaultSize);
    //@}

    /**
        Sets the window title.
        
        @param title
        The window title.
        
        @sa GetTitle()
    */
    virtual void SetTitle(const wxString& title);

    /**
        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.
    */
    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.
    */
    virtual bool ShouldPreventAppExit();

    /**
        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)
        
        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()
    */
    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()
    */
    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.
        
        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.
    */
    void UseNativeDecorationsByDefault(bool native = @true);
};
Commit	Line	Data
23324ae1 FM	1	/////////////////////////////////////////////////////////////////////////////
	2	// Name: toplevel.h
	3	// Purpose: documentation for wxTopLevelWindow class
	4	// Author: wxWidgets team
	5	// RCS-ID: $Id$
	6	// Licence: wxWindows license
	7	/////////////////////////////////////////////////////////////////////////////
	8
	9	/**
	10	@class wxTopLevelWindow
	11	@wxheader{toplevel.h}
7c913512	12
23324ae1 FM	13	wxTopLevelWindow is a common base class for wxDialog and
	14	wxFrame. It is an abstract base class meaning that you never
	15	work with objects of this class directly, but all of its methods are also
	16	applicable for the two classes above.
7c913512	17
23324ae1 FM	18	@library{wxcore}
23324ae1 FM	19	@category{managedwnd}
7c913512	20
23324ae1 FM	21	@seealso
	22	wxTopLevelWindow::SetTransparent
	23	*/
	24	class wxTopLevelWindow : public wxWindow
	25	{
	26	public:
	27	/**
	28	Returns @true if the platform supports making the window translucent.
	29
	30	@sa SetTransparent()
	31	*/
	32	virtual bool CanSetTransparent();
	33
	34	/**
	35	A synonym for CentreOnScreen().
	36	*/
	37	void CenterOnScreen(int direction);
	38
	39	/**
	40	Centres the window on screen.
	41
7c913512	42	@param direction
23324ae1 FM	43	Specifies the direction for the centering. May be wxHORIZONTAL, wxVERTICAL
	44	or wxBOTH.
	45
	46	@sa wxWindow::CentreOnParent
	47	*/
	48	void CentreOnScreen(int direction = wxBOTH);
	49
	50	/**
	51	Enables or disables the Close button (most often in the right
	52	upper corner of a dialog) and the Close entry of the system
	53	menu (most often in the left upper corner of the dialog).
	54	Currently only implemented for wxMSW and wxGTK. Returns
	55	@true if operation was successful. This may be wrong on
	56	X11 (including GTK+) where the window manager may not support
	57	this operation and there is no way to find out.
	58	*/
	59	bool EnableCloseButton(bool enable = @true);
	60
	61	/**
	62	Returns a pointer to the button which is the default for this window, or @c
	63	@NULL.
	64	The default button is the one activated by pressing the Enter key.
	65	*/
	66	wxWindow * GetDefaultItem();
	67
	68	/**
	69	Returns the standard icon of the window. The icon will be invalid if it hadn't
	70	been previously set by SetIcon().
	71
	72	@sa GetIcons()
	73	*/
	74	const wxIcon GetIcon();
	75
	76	/**
	77	Returns all icons associated with the window, there will be none of them if
	78	neither SetIcon() nor
	79	SetIcons() had been called before.
	80
	81	Use GetIcon() to get the main icon of the
	82	window.
	83
	84	@sa wxIconBundle
	85	*/
	86	const wxIconBundle GetIcons();
	87
	88	/**
	89	Gets a string containing the window title.
	90
	91	@sa SetTitle()
	92	*/
	93	wxString GetTitle();
	94
	95	/**
	96	Unique to the wxWinCE port. Responds to showing/hiding SIP (soft input panel)
	97	area and resize
	98	window accordingly. Override this if you want to avoid resizing or do additional
	99	operations.
	100	*/
	101	virtual bool HandleSettingChange(WXWPARAM wParam,
	102	WXLPARAM lParam);
	103
	104	/**
	105	Iconizes or restores the window.
	106
7c913512	107	@param iconize
23324ae1 FM	108	If @true, iconizes the window; if @false, shows and restores it.
	109
	110	@sa IsIconized(), Maximize().
	111	*/
	112	void Iconize(bool iconize);
	113
	114	/**
	115	Returns @true if this window is currently active, i.e. if the user is
	116	currently
	117	working with it.
	118	*/
	119	bool IsActive();
	120
	121	/**
	122	Returns @true if this window is expected to be always maximized, either due
	123	to platform policy
	124	or due to local policy regarding particular class.
	125	*/
	126	virtual bool IsAlwaysMaximized();
	127
	128	/**
	129	Returns @true if the window is in fullscreen mode.
	130
	131	@sa ShowFullScreen()
	132	*/
	133	bool IsFullScreen();
	134
	135	/**
	136	Returns @true if the window is iconized.
	137	*/
	138	bool IsIconized();
	139
	140	/**
	141	Returns @true if the window is maximized.
	142	*/
	143	bool IsMaximized();
	144
	145	/**
	146	@b @c This method is specific to wxUniversal port
	147
	148	Returns @true if this window is using native decorations, @false if we draw
	149	them ourselves.
	150
	151	@sa UseNativeDecorations(),
	152	UseNativeDecorationsByDefault()
	153	*/
	154	bool IsUsingNativeDecorations();
	155
	156	/**
	157	Maximizes or restores the window.
	158
7c913512	159	@param maximize
23324ae1 FM	160	If @true, maximizes the window, otherwise it restores it.
	161
	162	@sa Iconize()
	163	*/
	164	void Maximize(bool maximize);
	165
	166	/**
	167	Use a system-dependent way to attract users attention to the window when it is
	168	in background.
	169
	170	@e flags may have the value of either @c wxUSER_ATTENTION_INFO
	171	(default) or @c wxUSER_ATTENTION_ERROR which results in a more drastic
	172	action. When in doubt, use the default value.
	173
	174	Note that this function should normally be only used when the application is
	175	not already in foreground.
	176
	177	This function is currently implemented for Win32 where it flashes the
	178	window icon in the taskbar, and for wxGTK with task bars supporting it.
	179	*/
	180	void RequestUserAttention(int flags = wxUSER_ATTENTION_INFO);
	181
	182	/**
	183	Changes the default item for the panel, usually @e win is a button.
	184
	185	@sa GetDefaultItem()
	186	*/
	187	void SetDefaultItem(wxWindow win);
	188
	189	/**
	190	Sets the icon for this window.
	191
7c913512	192	@param icon
23324ae1 FM	193	The icon to associate with this window.
	194
	195	@remarks The window takes a 'copy' of icon, but since it uses reference
	196	counting, the copy is very quick. It is safe to
	197	delete icon after calling this function.
	198	*/
	199	void SetIcon(const wxIcon& icon);
	200
	201	/**
	202	Sets several icons of different sizes for this window: this allows to use
	203	different icons for different situations (e.g. task switching bar, taskbar,
	204	window title bar) instead of scaling, with possibly bad looking results, the
	205	only icon set by SetIcon().
	206
7c913512	207	@param icons
23324ae1 FM	208	The icons to associate with this window.
	209
	210	@sa wxIconBundle.
	211	*/
	212	void SetIcons(const wxIconBundle& icons);
	213
	214	/**
	215	Sets action or menu activated by pressing left hardware button on the smart
	216	phones.
	217	Unavailable on full keyboard machines.
	218
7c913512	219	@param id
23324ae1 FM	220	Identifier for this button.
23324ae1 FM	221
7c913512	222	@param label
23324ae1 FM	223	Text to be displayed on the screen area dedicated to this hardware button.
23324ae1 FM	224
7c913512	225	@param subMenu
23324ae1 FM	226	The menu to be opened after pressing this hardware button.
	227
	228	@sa SetRightMenu().
	229	*/
	230	void SetLeftMenu(int id = wxID_ANY,
	231	const wxString& label = wxEmptyString,
	232	wxMenu * subMenu = @NULL);
	233
	234	/**
	235	A simpler interface for setting the size hints than
	236	SetSizeHints().
	237	*/
	238	void SetMaxSize(const wxSize& size);
	239
	240	/**
	241	A simpler interface for setting the size hints than
	242	SetSizeHints().
	243	*/
	244	void SetMinSize(const wxSize& size);
	245
	246	/**
	247	Sets action or menu activated by pressing right hardware button on the smart
	248	phones.
	249	Unavailable on full keyboard machines.
	250
7c913512	251	@param id
23324ae1 FM	252	Identifier for this button.
23324ae1 FM	253
7c913512	254	@param label
23324ae1 FM	255	Text to be displayed on the screen area dedicated to this hardware button.
23324ae1 FM	256
7c913512	257	@param subMenu
23324ae1 FM	258	The menu to be opened after pressing this hardware button.
	259
	260	@sa SetLeftMenu().
	261	*/
	262	void SetRightMenu(int id = wxID_ANY,
	263	const wxString& label = wxEmptyString,
	264	wxMenu * subMenu = @NULL);
	265
	266	/**
	267	If the platform supports it, sets the shape of the window to that
	268	depicted by @e region. The system will not display or
	269	respond to any mouse event for the pixels that lie outside of the
	270	region. To reset the window to the normal rectangular shape simply
	271	call @e SetShape again with an empty region. Returns @true if the
	272	operation is successful.
	273	*/
	274	bool SetShape(const wxRegion& region);
	275
	276	//@{
	277	/**
	278	Allows specification of minimum and maximum window sizes, and window size
	279	increments.
	280	If a pair of values is not set (or set to -1), no constraints will be used.
	281
7c913512	282	@param incW
23324ae1 FM	283	Specifies the increment for sizing the width (GTK/Motif/Xt only).
23324ae1 FM	284
7c913512	285	@param incH
23324ae1 FM	286	Specifies the increment for sizing the height (GTK/Motif/Xt only).
23324ae1 FM	287
7c913512	288	@param incSize
23324ae1 FM	289	Increment size (only taken into account under X11-based
	290	ports such as wxGTK/wxMotif/wxX11).
	291
	292	@remarks Notice that this function not only prevents the user from
	293	resizing the window outside the given bounds but it
	294	also prevents the program itself from doing it using
	295	SetSize.
	296	*/
	297	virtual void SetSizeHints(int minW, int minH, int maxW=-1,
	298	int maxH=-1,
	299	int incW=-1,
	300	int incH=-1);
7c913512 FM	301	void SetSizeHints(const wxSize& minSize,
	302	const wxSize& maxSize=wxDefaultSize,
	303	const wxSize& incSize=wxDefaultSize);
23324ae1 FM	304	//@}
	305
	306	/**
	307	Sets the window title.
	308
7c913512	309	@param title
23324ae1 FM	310	The window title.
	311
	312	@sa GetTitle()
	313	*/
	314	virtual void SetTitle(const wxString& title);
	315
	316	/**
	317	If the platform supports it will set the window to be translucent
	318
7c913512	319	@param alpha
23324ae1 FM	320	Determines how opaque or transparent the window will
	321	be, if the platform supports the opreration. A value of 0 sets the
	322	window to be fully transparent, and a value of 255 sets the window
	323	to be fully opaque.
	324	*/
	325	virtual bool SetTransparent(int alpha);
	326
	327	/**
	328	This virtual function is not meant to be called directly but can be overridden
	329	to return @false (it returns @true by default) to allow the application to
	330	close even if this, presumably not very important, window is still opened.
	331	By default, the application stays alive as long as there are any open top level
	332	windows.
	333	*/
	334	virtual bool ShouldPreventAppExit();
	335
	336	/**
	337	Depending on the value of @e show parameter the window is either shown full
	338	screen or restored to its normal state. @e style is a bit list containing
	339	some or all of the following values, which indicate what elements of the window
	340	to hide in full-screen mode:
	341
	342	wxFULLSCREEN_NOMENUBAR
	343	wxFULLSCREEN_NOTOOLBAR
	344	wxFULLSCREEN_NOSTATUSBAR
	345	wxFULLSCREEN_NOBORDER
	346	wxFULLSCREEN_NOCAPTION
	347	wxFULLSCREEN_ALL (all of the above)
	348
	349	This function has not been tested with MDI frames.
	350
	351	Note that showing a window full screen also actually
	352	@ref wxWindow::show Show()s if it hadn't been shown yet.
	353
	354	@sa IsFullScreen()
	355	*/
	356	bool ShowFullScreen(bool show, long style = wxFULLSCREEN_ALL);
	357
	358	/**
	359	@b @c This method is specific to wxUniversal port
	360
	361	Use native or custom-drawn decorations for this window only. Notice that to
	362	have any effect this method must be called before really creating the window,
	363	i.e. two step creation must be used:
	364
	365	@sa UseNativeDecorationsByDefault(),
	366	IsUsingNativeDecorations()
	367	*/
	368	void UseNativeDecorations(bool native = @true);
	369
	370	/**
	371	@b @c This method is specific to wxUniversal port
	372
	373	Top level windows in wxUniversal port can use either system-provided window
	374	decorations (i.e. title bar and various icons, buttons and menus in it) or draw
	375	the decorations themselves. By default the system decorations are used if they
	376	are available, but this method can be called with @e native set to @false to
	377	change this for all windows created after this point.
	378
	379	Also note that if @c WXDECOR environment variable is set, then custom
	380	decorations are used by default and so it may make sense to call this method
	381	with default argument if the application can't use custom decorations at all
	382	for some reason.
	383	*/
384	void UseNativeDecorationsByDefault(bool native = @true);
385	};