X-Git-Url: https://git.saurik.com/wxWidgets.git/blobdiff_plain/a660d684eda27638bca0384b2058911a31c8e845..6b037754f53cc35e177bf6787bace26c7cecc6e1:/docs/latex/wx/window.tex diff --git a/docs/latex/wx/window.tex b/docs/latex/wx/window.tex index fe1ca0b2c5..7ed5e858dc 100644 --- a/docs/latex/wx/window.tex +++ b/docs/latex/wx/window.tex @@ -29,6 +29,8 @@ the application-wide policy is for 3D controls. Windows only.} \twocolitem{\windowstyle{wxTAB\_TRAVERSAL}}{Use this to enable tab traversal for non-dialog windows.} \twocolitem{\windowstyle{wxVSCROLL}}{Use this style to enable a vertical scrollbar.} \twocolitem{\windowstyle{wxHSCROLL}}{Use this style to enable a horizontal scrollbar.} +\twocolitem{\windowstyle{wxCLIP\_CHILDREN}}{Use this style to eliminate flicker caused by the background being +repainted, then children being painted over them. Windows-only.} \end{twocollist} See also \helpref{window styles overview}{windowstyles}. @@ -45,10 +47,10 @@ See also \helpref{window styles overview}{windowstyles}. Default constructor. -\func{}{wxWindow}{\param{wxWindow*}{ parent}, \param{const wxWindowID }{id}, +\func{}{wxWindow}{\param{wxWindow*}{ parent}, \param{wxWindowID }{id}, \param{const wxPoint\& }{pos = wxDefaultPosition}, \param{const wxSize\& }{size = wxDefaultSize}, - \param{const long }{style = 0}, + \param{long }{style = 0}, \param{const wxString\& }{name = wxPanelNameStr}} Constructs a window, which can be a child of a frame, dialog or any other non-control window. @@ -110,13 +112,13 @@ release the capture. \membersection{wxWindow::Center}\label{wxwindowcenter} -\func{void}{Center}{\param{const int}{ direction}} +\func{void}{Center}{\param{int}{ direction}} A synonym for \helpref{Centre}{wxwindowcentre}. \membersection{wxWindow::Centre}\label{wxwindowcentre} -\func{virtual void}{Centre}{\param{const int}{ direction = wxHORIZONTAL}} +\func{virtual void}{Centre}{\param{int}{ direction = wxHORIZONTAL}} Centres the window. @@ -183,6 +185,60 @@ Applies to managed windows (wxFrame and wxDialog classes) only. \helpref{wxWindow::Destroy}{wxwindowdestroy},\rtfsp \helpref{wxCloseEvent}{wxcloseevent} +\membersection{wxWindow::ConvertDialogToPixels}\label{wxwindowconvertdialogtopixels} + +\func{wxPoint}{ConvertDialogToPixels}{\param{const wxPoint\&}{ pt}} + +\func{wxSize}{ConvertDialogToPixels}{\param{const wxSize\&}{ sz}} + +Converts a point or size from dialog units to pixels. + +For the x dimension, the dialog units are multiplied by the average character width +and then divided by 4. + +For the y dimension, the dialog units are multiplied by the average character height +and then divided by 8. + +\wxheading{Remarks} + +Dialog units are used for maintaining a dialog's proportions even if the font changes. +Dialogs created using Dialog Editor optionally use dialog units. + +You can also use these functions programmatically. A convenience macro is defined: + +{\small +\begin{verbatim} +#define wxDLG_UNIT(parent, pt) parent->ConvertDialogToPixels(pt) +\end{verbatim} +} + +\wxheading{See also} + +\helpref{wxWindow::ConvertPixelsToDialog}{wxwindowconvertpixelstodialog} + +\membersection{wxWindow::ConvertPixelsToDialog}\label{wxwindowconvertpixelstodialog} + +\func{wxPoint}{ConvertPixelsToDialog}{\param{const wxPoint\&}{ pt}} + +\func{wxSize}{ConvertPixelsToDialog}{\param{const wxSize\&}{ sz}} + +Converts a point or size from pixels to dialog units. + +For the x dimension, the pixels are multiplied by 4 and then divided by the average +character width. + +For the y dimension, the pixels are multipled by 8 and then divided by the average +character height. + +\wxheading{Remarks} + +Dialog units are used for maintaining a dialog's proportions even if the font changes. +Dialogs created using Dialog Editor optionally use dialog units. + +\wxheading{See also} + +\helpref{wxWindow::ConvertDialogToPixels}{wxwindowconvertdialogtopixels} + \membersection{wxWindow::Destroy}\label{wxwindowdestroy} \func{virtual bool}{Destroy}{\void} @@ -240,7 +296,7 @@ Enable or disable the window for user input. \membersection{wxWindow::FakePopupMenu}\label{wxwindowfakepopupmenu} -\func{virtual bool}{FakePopupMenu}{\param{wxMenu* }{menu}, \param{const int }{x}, \param{const int }{y}} +\func{virtual bool}{FakePopupMenu}{\param{wxMenu* }{menu}, \param{int }{x}, \param{int }{y}} A replacement for wxWindow::PopupMenu for cases where the PopupMenu implementation does not work correctly, in particular on Motif platforms. @@ -276,6 +332,16 @@ Note that this is a static function, so it can be called without needing a wxWin \helpref{wxWindow::SetFocus}{wxwindowsetfocus} +\membersection{wxWindow::FindWindow}\label{wxwindowfindwindow} + +\func{wxWindow*}{FindWindow}{\param{long}{ id}} + +Find a child of this window, by identifier. + +\func{wxWindow*}{FindWindow}{\param{const wxString\&}{ name}} + +Find a child of this window, by name. + \membersection{wxWindow::Fit}\label{wxwindowfit} \func{virtual void}{Fit}{\void} @@ -479,7 +545,7 @@ a code to the application. \membersection{wxWindow::GetScrollThumb}\label{wxwindowgetscrollthumb} -\func{virtual int}{GetScrollThumb}{\param{const int }{orientation}} +\func{virtual int}{GetScrollThumb}{\param{int }{orientation}} Returns the built-in scrollbar thumb size. @@ -489,7 +555,7 @@ Returns the built-in scrollbar thumb size. \membersection{wxWindow::GetScrollPos}\label{wxwindowgetscrollpos} -\func{virtual int}{GetScrollPos}{\param{const int }{orientation}} +\func{virtual int}{GetScrollPos}{\param{int }{orientation}} Returns the built-in scrollbar position. @@ -499,7 +565,7 @@ See \helpref{wxWindow::SetScrollbar}{wxwindowsetscrollbar} \membersection{wxWindow::GetScrollRange}\label{wxwindowgetscrollrange} -\func{virtual int}{GetScrollRange}{\param{const int }{orientation}} +\func{virtual int}{GetScrollRange}{\param{int }{orientation}} Returns the built-in scrollbar range. @@ -554,6 +620,17 @@ Gets the window's title. Applicable only to frames and dialogs. \helpref{wxWindow::SetTitle}{wxwindowsettitle} +\membersection{wxWindow::GetUpdateRegion}\label{wxwindowgetupdateregion} + +\constfunc{virtual wxRegion}{GetUpdateRegion}{\void} + +Returns the region specifying which parts of the window have been damaged. Should +only be called within an \helpref{OnPaint}{wxwindowonpaint} event handler. + +\wxheading{See also} + +\helpref{wxRegion}{wxregion}, \helpref{wxRegionIterator}{wxregioniterator}, \helpref{wxWindow::OnPaint}{wxwindowonpaint} + \membersection{wxWindow::GetWindowStyleFlag} \constfunc{long}{GetWindowStyleFlag}{\void} @@ -653,7 +730,7 @@ the user can only interact with this window. If FALSE, the effect is reversed.} \membersection{wxWindow::Move}\label{wxwindowmove} -\func{void}{Move}{\param{const int}{ x}, \param{const int}{ y}} +\func{void}{Move}{\param{int}{ x}, \param{int}{ y}} Moves the window to the given position. @@ -799,7 +876,7 @@ you may delete other windows. \wxheading{Remarks} -Derive your own class to handle this message. The default handler returns FALSE. +Derive your own class to handle this message. The default handler returns TRUE. \wxheading{See also} @@ -824,6 +901,14 @@ using \helpref{wxCloseEvent::GetForce}{wxcloseeventgetforce}. If this is TRUE, destroy the window using \helpref{wxWindow::Destroy}{wxwindowdestroy}. If not, it is up to you whether you respond by destroying the window. +(Note: GetForce is now superceded by CanVeto. So to test whether forced destruction of +the window is required, test for the negative of CanVeto. If CanVeto returns FALSE, +it is not possible to skip window deletion.) + +If you don't destroy the window, you should call \helpref{wxCloseEvent::Veto}{wxcloseeventveto} to +let the calling code know that you did not destroy the window. This allows the \helpref{wxWindow::Close}{wxwindowclose} function +to return TRUE or FALSE depending on whether the close instruction was honoured or not. + \wxheading{Remarks} The \helpref{wxWindow::OnClose}{wxwindowonclose} virtual function remains @@ -837,22 +922,9 @@ destroying the window if it returns TRUE or if the close is being forced. \helpref{wxWindow::Close}{wxwindowclose},\rtfsp \helpref{wxWindow::OnClose}{wxwindowonclose},\rtfsp \helpref{wxWindow::Destroy}{wxwindowdestroy},\rtfsp -\helpref{wxCloseEvent}{wxcloseevent} - -\membersection{wxWindow::OnDefaultAction}\label{wxwindowondefaultaction} - -\func{virtual void}{OnDefaultAction}{\param{wxControl* }{control}} - -Called when the user initiates the default action for a panel or -dialog box, for example by double clicking on a listbox. - -\wxheading{Parameters} - -\docparam{control}{The control which caused the default action.} - -\wxheading{Remarks} - -TODO: eliminate this?? Or keep it for backward compatibility? +\helpref{wxCloseEvent}{wxcloseevent},\rtfsp +\helpref{wxApp::OnQueryEndSession}{wxapponqueryendsession},\rtfsp +\helpref{wxApp::OnEndSession}{wxapponendsession} \membersection{wxWindow::OnDropFiles}\label{wxwindowondropfiles} @@ -1085,7 +1157,7 @@ terms of the client area, and are unscrolled, so you will need to do some calculations using the current view position to obtain logical, scrolled units. -Here is an example of using the \helpref{wxUpdateIterator}{wxupdateiterator} class: +Here is an example of using the \helpref{wxRegionIterator}{wxregioniterator} class: {\small% \begin{verbatim} @@ -1099,7 +1171,7 @@ void MyWindow::OnPaint(wxPaintEvent& event) ViewStart(&vbX,&vbY); int vX,vY,vW,vH; // Dimensions of client area in pixels - wxUpdateIterator upd(this); // get the update rect list + wxRegionIterator upd(GetUpdateRegion()); // get the update rect list while (upd) { @@ -1127,8 +1199,6 @@ void MyWindow::OnPaint(wxPaintEvent& event) \helpref{wxPaintDC}{wxpaintdc},\rtfsp \helpref{Event handling overview}{eventhandlingoverview} -\membersection{wxWindow::OnScroll}\label{wxwindowonscroll} - \func{void}{OnScroll}{\param{wxScrollEvent\& }{event}} Called when a scroll event is received from one of the window's built-in scrollbars. @@ -1230,7 +1300,7 @@ default value is FALSE.} \membersection{wxWindow::PopupMenu}\label{wxwindowpopupmenu} -\func{virtual bool}{PopupMenu}{\param{wxMenu* }{menu}, \param{const int }{x}, \param{const int }{y}} +\func{virtual bool}{PopupMenu}{\param{wxMenu* }{menu}, \param{int }{x}, \param{int }{y}} Pops up the given menu at the specified coordinates, relative to this window, and returns control when the user has dismissed the menu. If a @@ -1246,13 +1316,6 @@ the commandInt member of the event to check the selected menu identifier. \docparam{y}{Required y position for the menu to appear.} -\wxheading{Remarks} - -Valid only for subwindows (panels, canvases and text windows). - -Sometimes this function does not function correctly under Motif, in which case -please use \helpref{wxWindow::FakePopupMenu}{wxwindowfakepopupmenu} instead. - \wxheading{See also} \helpref{wxMenu}{wxmenu}, \helpref{wxWindow::FakePopupMenu}{wxwindowfakepopupmenu} @@ -1346,7 +1409,7 @@ Converts from screen to client window coordinates. \membersection{wxWindow::ScrollWindow}\label{wxwindowscrollwindow} -\func{virtual void}{ScrollWindow}{\param{const int }{dx}, \param{const int }{dy}, \param{const wxRect*}{ rect = NULL}} +\func{virtual void}{ScrollWindow}{\param{int }{dx}, \param{int }{dy}, \param{const wxRect*}{ rect = NULL}} Physically scrolls the pixels in the window. @@ -1367,6 +1430,12 @@ Available only under Windows. Use this function to optimise your scrolling implementations, to minimise the area that must be redrawn. +\membersection{wxWindow::SetAcceleratorTable}\label{wxwindowsetacceleratortable} + +\func{virtual void}{SetAcceleratorTable}{\param{const wxAcceleratorTable\&}{ accel}} + +Sets the accelerator table for this window. See \helpref{wxAcceleratorTable}{wxacceleratortable}. + \membersection{wxWindow::SetAutoLayout}\label{wxwindowsetautolayout} \func{void}{SetAutoLayout}{\param{const bool}{ autoLayout}} @@ -1425,13 +1494,6 @@ You must call \helpref{wxWindow::SetAutoLayout}{wxwindowsetautolayout} to tell a the constraints automatically in OnSize; otherwise, you must override OnSize and call Layout explicitly. -% TODO: double click should always be allowed. -%\membersection{wxWindow::SetDoubleClick}\label{setdoubleclick} -% -%\func{void}{SetDoubleClick}{\param{bool}{ allowDoubleClick}} -% -%For canvases, allows double click if {\it allowDoubleClick} is TRUE. The default is FALSE. - \membersection{wxWindow::SetFocus}\label{wxwindowsetfocus} \func{virtual void}{SetFocus}{\void} @@ -1530,8 +1592,8 @@ a code to the application. The function \helpref{wxDialog::EndModal}{wxdialogend \membersection{wxWindow::SetScrollbar}\label{wxwindowsetscrollbar} -\func{virtual void}{SetScrollbar}{\param{const int }{orientation}, \param{const int }{position},\rtfsp -\param{const int }{thumbSize}, \param{const int }{range},\rtfsp +\func{virtual void}{SetScrollbar}{\param{int }{orientation}, \param{int }{position},\rtfsp +\param{int }{thumbSize}, \param{int }{range},\rtfsp \param{const bool }{refresh = TRUE}} Sets the scrollbar properties of a built-in scrollbar. @@ -1581,7 +1643,7 @@ from your \helpref{wxWindow::OnSize}{wxwindowonsize} event handler function. \begin{comment} \membersection{wxWindow::SetScrollPage}\label{wxwindowsetscrollpage} -\func{virtual void}{SetScrollPage}{\param{const int }{orientation}, \param{const int }{pageSize}, \param{const bool }{refresh = TRUE}} +\func{virtual void}{SetScrollPage}{\param{int }{orientation}, \param{int }{pageSize}, \param{const bool }{refresh = TRUE}} Sets the page size of one of the built-in scrollbars. @@ -1612,16 +1674,14 @@ handling of pages and ranges. \wxheading{See also} \helpref{wxWindow::SetScrollPos}{wxwindowsetscrollpos},\rtfsp -\helpref{wxWindow::SetScrollRange}{wxwindowsetscrollpage},\rtfsp \helpref{wxWindow::GetScrollPos}{wxwindowsetscrollpos},\rtfsp -\helpref{wxWindow::GetScrollRange}{wxwindowsetscrollrange},\rtfsp -\helpref{wxWindow::GetScrollPage}{wxwindowsetscrollrange},\rtfsp +\helpref{wxWindow::GetScrollPage}{wxwindowsetscrollpage},\rtfsp \helpref{wxScrollBar}{wxscrollbar}, \helpref{wxScrolledWindow}{wxscrolledwindow} \end{comment} \membersection{wxWindow::SetScrollPos}\label{wxwindowsetscrollpos} -\func{virtual void}{SetScrollPos}{\param{const int }{orientation}, \param{const int }{pos}, \param{const bool }{refresh = TRUE}} +\func{virtual void}{SetScrollPos}{\param{int }{orientation}, \param{int }{pos}, \param{const bool }{refresh = TRUE}} Sets the position of one of the built-in scrollbars. @@ -1642,14 +1702,13 @@ application to take note of scrollbar attributes and redraw contents accordingly \helpref{wxWindow::SetScrollbar}{wxwindowsetscrollbar},\rtfsp \helpref{wxWindow::GetScrollPos}{wxwindowsetscrollpos},\rtfsp -\helpref{wxWindow::GetScrollRange}{wxwindowsetscrollrange},\rtfsp -\helpref{wxWindow::GetScrollThumb}{wxwindowsetscrollthumb},\rtfsp +\helpref{wxWindow::GetScrollThumb}{wxwindowgetscrollthumb},\rtfsp \helpref{wxScrollBar}{wxscrollbar}, \helpref{wxScrolledWindow}{wxscrolledwindow} \begin{comment} \membersection{wxWindow::SetScrollRange}\label{wxwindowsetscrollrange} -\func{virtual void}{SetScrollRange}{\param{const int }{orientation}, \param{const int }{range}, \param{const bool }{refresh = TRUE}} +\func{virtual void}{SetScrollRange}{\param{int }{orientation}, \param{int }{range}, \param{const bool }{refresh = TRUE}} Sets the range of one of the built-in scrollbars. @@ -1664,9 +1723,9 @@ Sets the range of one of the built-in scrollbars. \wxheading{Remarks} The range of a scrollbar is the number of steps that the thumb may travel, rather than the total -object length of the scrollbar. If you are implementing a scrolling canvas, for example, you -would adjust the scroll range when the canvas is resized, by subtracting the canvas view size from the -total virtual canvas size. When the two sizes are the same (all the canvas is visible), the range goes to zero +object length of the scrollbar. If you are implementing a scrolling window, for example, you +would adjust the scroll range when the window is resized, by subtracting the window view size from the +total virtual window size. When the two sizes are the same (all the window is visible), the range goes to zero and usually the scrollbar will be automatically hidden. \wxheading{See also} @@ -1674,19 +1733,18 @@ and usually the scrollbar will be automatically hidden. \helpref{wxWindow::SetScrollPos}{wxwindowsetscrollpos},\rtfsp \helpref{wxWindow::SetScrollPage}{wxwindowsetscrollpage},\rtfsp \helpref{wxWindow::GetScrollPos}{wxwindowsetscrollpos},\rtfsp -\helpref{wxWindow::GetScrollRange}{wxwindowsetscrollrange},\rtfsp -\helpref{wxWindow::GetScrollPage}{wxwindowsetscrollrange},\rtfsp +\helpref{wxWindow::GetScrollPage}{wxwindowsetscrollpage},\rtfsp \helpref{wxScrollBar}{wxscrollbar}, \helpref{wxScrolledWindow}{wxscrolledwindow} \end{comment} \membersection{wxWindow::SetSize}\label{wxwindowsetsize} -\func{virtual void}{SetSize}{\param{const int}{ x}, \param{const int}{ y}, \param{const int}{ width}, \param{int}{ height}, - \param{const int}{ sizeFlags = wxSIZE\_AUTO}} +\func{virtual void}{SetSize}{\param{int}{ x}, \param{int}{ y}, \param{int}{ width}, \param{int}{ height}, + \param{int}{ sizeFlags = wxSIZE\_AUTO}} Sets the size and position of the window in pixels. -\func{virtual void}{SetSize}{\param{const int}{ width}, \param{const int}{ height}} +\func{virtual void}{SetSize}{\param{int}{ width}, \param{int}{ height}} Sets the size of the window in pixels. @@ -1733,8 +1791,8 @@ by wxWindows, or that the current value of the dimension should be used. \membersection{wxWindow::SetSizeHints}\label{wxwindowsetsizehints} -\func{virtual void}{SetSizeHints}{\param{const int}{ minW=-1}, \param{const int}{ minH=-1}, \param{const int}{ maxW=-1}, \param{int}{ maxH=-1}, - \param{const int}{ incW=-1}, \param{const int}{ incH=-1}} +\func{virtual void}{SetSizeHints}{\param{int}{ minW=-1}, \param{int}{ minH=-1}, \param{int}{ maxW=-1}, \param{int}{ maxH=-1}, + \param{int}{ incW=-1}, \param{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), the default values will be used. @@ -1762,7 +1820,7 @@ The resizing increments are only significant under Motif or Xt. \membersection{wxWindow::SetClientSize} -\func{virtual void}{SetClientSize}{\param{const int}{ width}, \param{const int}{ height}} +\func{virtual void}{SetClientSize}{\param{int}{ width}, \param{int}{ height}} This sets the size of the window client area in pixels. Using this function to size a window tends to be more device-independent than \helpref{wxWindow::SetSize}{wxwindowsetsize}, since the application need not