[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}
	12
	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.
	17
	18	@library{wxcore}
	19	@category{managedwnd}
	20
	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
	42	@param direction
	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
107	@param iconize
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
159	@param maximize
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
192	@param icon
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
207	@param icons
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
219	@param id
220	Identifier for this button.
221
222	@param label
223	Text to be displayed on the screen area dedicated to this hardware button.
224
225	@param subMenu
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
251	@param id
252	Identifier for this button.
253
254	@param label
255	Text to be displayed on the screen area dedicated to this hardware button.
256
257	@param subMenu
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
282	@param incW
283	Specifies the increment for sizing the width (GTK/Motif/Xt only).
284
285	@param incH
286	Specifies the increment for sizing the height (GTK/Motif/Xt only).
287
288	@param incSize
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);
301	void SetSizeHints(const wxSize& minSize,
302	const wxSize& maxSize=wxDefaultSize,
303	const wxSize& incSize=wxDefaultSize);
304	//@}
305
306	/**
307	Sets the window title.
308
309	@param title
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
319	@param alpha
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	};