X-Git-Url: https://git.saurik.com/wxWidgets.git/blobdiff_plain/b325f27f23fa675189be3cd33b9582809ad57362..852b6c3ce7baa055da25f5254f6ee2eee0cd79b7:/docs/latex/wx/text.tex?ds=inline diff --git a/docs/latex/wx/text.tex b/docs/latex/wx/text.tex index dbb25cdce2..e93b8103e3 100644 --- a/docs/latex/wx/text.tex +++ b/docs/latex/wx/text.tex @@ -23,7 +23,7 @@ No base class control. \texttt{wxTextCoord} contains the index of a column or a row in the control. -Note that alghough both of these types should probably have been unsigned, due +Note that although both of these types should probably have been unsigned, due to backwards compatibility reasons, are defined as \texttt{long} currently. Their use (instead of plain \texttt{long}) is still encouraged as it makes the code more readable. @@ -70,7 +70,7 @@ for a text control. \end{verbatim} } -The values below are the possible return codes of the +The values below are the possible return codes of the \helpref{HitTest}{wxtextctrlhittest} method: {\small \begin{verbatim} @@ -197,6 +197,20 @@ Returns a bitlist indicating which attributes will be set. Returns {\tt true} if this style specifies any non-default attributes. +\membersection{wxTextAttr::Merge}\label{wxtextattrmerge} + +\func{void}{Merge}{\param{const wxTextAttr\&}{ overlay}} + +Copies all defined/valid properties from \arg{overlay} to current object. + +\func{static wxTextAttr}{Merge}{\param{const wxTextAttr\&}{ base}, \param{const wxTextAttr\&}{ overlay}} + +Creates a new {\tt wxTextAttr} which is a merge of \arg{base} and +\arg{overlay}. Properties defined in \arg{overlay} take precedence over those +in \arg{base}. Properties undefined/invalid in both are undefined in the +result. + + \membersection{wxTextAttr::SetAlignment}\label{wxtextattrsetalignment} \func{void}{SetAlignment}{\param{wxTextAttrAlignment}{ alignment}} @@ -230,7 +244,7 @@ Sets the text font. \func{void}{SetLeftIndent}{\param{int }{indent}, \param{int }{subIndent = 0}} Sets the left indent in tenths of a millimetre. -subIndent sets the indent for all lines but the first line in a paragraph +subIndent sets the indent for all lines but the first line in a paragraph relative to the first line. @@ -280,11 +294,11 @@ streambuf\\ \twocolwidtha{5cm} \begin{twocollist}\itemsep=0pt \twocolitem{\windowstyle{wxTE\_PROCESS\_ENTER}}{The control will generate -the message wxEVENT\_TYPE\_TEXT\_ENTER\_COMMAND (otherwise pressing Enter key +the event wxEVT\_COMMAND\_TEXT\_ENTER (otherwise pressing Enter key is either processed internally by the control or used for navigation between dialog controls).} \twocolitem{\windowstyle{wxTE\_PROCESS\_TAB}}{The control will receive -EVT\_CHAR messages for TAB pressed - normally, TAB is used for passing to the +wxEVT\_CHAR events for TAB pressed - normally, TAB is used for passing to the next control in a dialog instead. For the control created with this style, you can still use Ctrl-Enter to pass to the next control from the keyboard.} \twocolitem{\windowstyle{wxTE\_MULTILINE}}{The text control allows multiple lines.} @@ -296,23 +310,24 @@ style is ignored under other platforms.} \twocolitem{\windowstyle{wxTE\_RICH2}}{Use rich text control version 2.0 or 3.0 under Win32, this style is ignored under other platforms} \twocolitem{\windowstyle{wxTE\_AUTO\_URL}}{Highlight the URLs and generate the -wxTextUrlEvents when mouse events occur over them. This style is supported -under Win32 only and requires wxTE\_RICH.} +wxTextUrlEvents when mouse events occur over them. This style is only supported +for wxTE\_RICH Win32 and multi-line wxGTK2 text controls.} \twocolitem{\windowstyle{wxTE\_NOHIDESEL}}{By default, the Windows text control doesn't show the selection when it doesn't have focus - use this style to force it to always show it. It doesn't do anything under other platforms.} \twocolitem{\windowstyle{wxHSCROLL}}{A horizontal scrollbar will be created and -used, so that text won't be wrapped. No effect under GTK+.} +used, so that text won't be wrapped. No effect under wxGTK1.} \twocolitem{\windowstyle{wxTE\_LEFT}}{The text in the control will be left-justified (default).} \twocolitem{\windowstyle{wxTE\_CENTRE}}{The text in the control will be centered (currently wxMSW and wxGTK2 only).} \twocolitem{\windowstyle{wxTE\_RIGHT}}{The text in the control will be right-justified (currently wxMSW and wxGTK2 only).} -\twocolitem{\windowstyle{wxTE\_DONTWRAP}}{Same as {\tt wxHSCROLL} style.} -\twocolitem{\windowstyle{wxTE\_LINEWRAP}}{Wrap the lines too long to be shown entirely at any position (wxUniv only currently).} -\twocolitem{\windowstyle{wxTE\_WORDWRAP}}{Wrap the lines too long to be shown entirely at word boundaries only (wxUniv only currently).} +\twocolitem{\windowstyle{wxTE\_DONTWRAP}}{Same as {\tt wxHSCROLL} style: don't wrap at all, show horizontal scrollbar instead.} +\twocolitem{\windowstyle{wxTE\_CHARWRAP}}{Wrap the lines too long to be shown entirely at any position (wxUniv and wxGTK2 only).} +\twocolitem{\windowstyle{wxTE\_WORDWRAP}}{Wrap the lines too long to be shown entirely at word boundaries (wxUniv and wxGTK2 only).} +\twocolitem{\windowstyle{wxTE\_BESTWRAP}}{Wrap the lines at word boundaries or at any other character if there are words longer than the window width (this is the default).} +\twocolitem{\windowstyle{wxTE\_CAPITALIZE}}{On PocketPC and Smartphone, causes the first letter to be capitalized.} \end{twocollist} -See also \helpref{window styles overview}{windowstyles} and -\helpref{wxTextCtrl::wxTextCtrl}{wxtextctrlconstr}. +See also \helpref{window styles overview}{windowstyles} and \helpref{wxTextCtrl::wxTextCtrl}{wxtextctrlctor}. \wxheading{wxTextCtrl text format} @@ -320,17 +335,17 @@ The multiline text controls always store the text as a sequence of lines separated by {\tt $\backslash$n} characters, i.e. in the Unix text format even on non-Unix platforms. This allows the user code to ignore the differences between the platforms but at a price: the indices in the control such as those -returned by \helpref{GetInsertionPoint}{wxtextctrlgetinsertionpoint} or +returned by \helpref{GetInsertionPoint}{wxtextctrlgetinsertionpoint} or \helpref{GetSelection}{wxtextctrlgetselection} can {\bf not} be used as indices into the string returned by \helpref{GetValue}{wxtextctrlgetvalue} as -they're going to be slightly off for platforms using +they're going to be slightly off for platforms using {\tt $\backslash$r$\backslash$n} as separator (as Windows does), for example. Instead, if you need to obtain a substring between the $2$ indices obtained from the control with the help of the functions mentioned above, you should use \helpref{GetRange}{wxtextctrlgetrange}. And the indices themselves can -only be passed to other methods, for example -\helpref{SetInsertionPoint}{wxtextctrlsetinsertionpoint} or +only be passed to other methods, for example +\helpref{SetInsertionPoint}{wxtextctrlsetinsertionpoint} or \helpref{SetSelection}{wxtextctrlsetselection}. To summarize: never use the indices returned by (multiline) wxTextCtrl as @@ -460,8 +475,8 @@ comes from the program itself (for example, if SetValue() is called)} \twocolitem{{\bf EVT\_TEXT\_ENTER(id, func)}}{Respond to a wxEVT\_COMMAND\_TEXT\_ENTER event, generated when enter is pressed in a text control (which must have wxTE\_PROCESS\_ENTER style for this event to be generated).} -\twocolitem{{\bf EVT\_TEXT\_URL(id, func)}}{A mouse event occured over an URL -in the text control (Win32 only)} +\twocolitem{{\bf EVT\_TEXT\_URL(id, func)}}{A mouse event occurred over an URL +in the text control (wxMSW and wxGTK2 only)} \twocolitem{{\bf EVT\_TEXT\_MAXLEN(id, func)}}{User tried to enter more text into the control than the limit set by \helpref{SetMaxLength}{wxtextctrlsetmaxlength}.} @@ -470,7 +485,7 @@ into the control than the limit set by \latexignore{\rtfignore{\wxheading{Members}}} -\membersection{wxTextCtrl::wxTextCtrl}\label{wxtextctrlconstr} +\membersection{wxTextCtrl::wxTextCtrl}\label{wxtextctrlctor} \func{}{wxTextCtrl}{\void} @@ -520,7 +535,7 @@ visible. \helpref{wxTextCtrl::Create}{wxtextctrlcreate}, \helpref{wxValidator}{wxvalidator} -\membersection{wxTextCtrl::\destruct{wxTextCtrl}} +\membersection{wxTextCtrl::\destruct{wxTextCtrl}}\label{wxtextctrldtor} \func{}{\destruct{wxTextCtrl}}{\void} @@ -610,7 +625,7 @@ Copies the selected text to the clipboard under Motif and MS Windows. \param{long}{ style = 0}, \param{const wxValidator\& }{validator = wxDefaultValidator}, \param{const wxString\& }{name = wxTextCtrlNameStr}} Creates the text control for two-step construction. Derived classes -should call or replace this function. See \helpref{wxTextCtrl::wxTextCtrl}{wxtextctrlconstr}\rtfsp +should call or replace this function. See \helpref{wxTextCtrl::wxTextCtrl}{wxtextctrlctor}\rtfsp for further details. @@ -621,19 +636,19 @@ for further details. Copies the selected text to the clipboard and removes the selection. -\membersection{wxTextCtrl::DiscardEdits} +\membersection{wxTextCtrl::DiscardEdits}\label{wxtextctrldiscardedits} \func{void}{DiscardEdits}{\void} Resets the internal `modified' flag as if the current edits had been saved. -\membersection{wxTextCtrl::EmulateKeyPress} +\membersection{wxTextCtrl::EmulateKeyPress}\label{wxtextctrlemulatekeypress} \func{bool}{EmulateKeyPress}{\param{const wxKeyEvent\& }{event}} This functions inserts into the control the character which would have been -inserted if the given key event had occured in the text control. The +inserted if the given key event had occurred in the text control. The {\it event} object should be the same as the one passed to {\tt EVT\_KEY\_DOWN} handler previously by wxWidgets. @@ -683,7 +698,7 @@ point or the zero character if the point is at the end of the control. \membersection{wxTextCtrl::GetLastPosition}\label{wxtextctrlgetlastposition} -\constfunc{virtual long}{GetLastPosition}{\void} +\constfunc{virtual wxTextPos}{GetLastPosition}{\void} Returns the zero based index of the last position in the text control, which is equal to the number of characters in the control. @@ -730,24 +745,29 @@ Returns the number of lines in the text control buffer. \wxheading{Remarks} Note that even empty text controls have one line (where the insertion point -is), so GetNumberOfLines() never returns 0. +is), so GetNumberOfLines() never returns $0$. + +For wxGTK using GTK+ 1.2.x and earlier, the number of lines in a multi-line +text control is calculated by actually counting newline characters in the +buffer, i.e. this function returns the number of logical lines and doesn't +depend on whether any of them are wrapped. For all the other platforms, the +number of physical lines in the control is returned. -For gtk\_text (multi-line) controls, the number of lines is -calculated by actually counting newline characters in the buffer. You -may wish to avoid using functions that work with line numbers if you are -working with controls that contain large amounts of text. +Also note that you may wish to avoid using functions that work with line +numbers if you are working with controls that contain large amounts of text as +this function has $O(N)$ complexity for $N$ being the number of lines. \membersection{wxTextCtrl::GetRange}\label{wxtextctrlgetrange} \constfunc{virtual wxString}{GetRange}{\param{long}{ from}, \param{long}{ to}} -Returns the string containing the text staring in the positions {\it from} and +Returns the string containing the text starting in the positions {\it from} and up to {\it to} in the control. The positions must have been returned by another wxTextCtrl method. Please note that the positions in a multiline wxTextCtrl do {\bf not} -correspond to the indices in the string returned by +correspond to the indices in the string returned by \helpref{GetValue}{wxtextctrlgetvalue} because of the different new line representations ({\tt CR} or {\tt CR LF}) and so this method should be used to obtain the correct results instead of extracting parts of the entire value. It @@ -798,7 +818,7 @@ support this function. \wxheading{Return value} -{\tt true} on success, {\tt false} if an error occured - it may also mean that +{\tt true} on success, {\tt false} if an error occurred - it may also mean that the styles are not supported under this platform. \wxheading{See also} @@ -822,11 +842,11 @@ sequence in the native control. This function finds the character at the specified position expressed in pixels. If the return code is not \texttt{wxTE\_HT\_UNKNOWN} the row and column -of the character closest to this position are returned in the \arg{col} and +of the character closest to this position are returned in the \arg{col} and \arg{row} parameters (unless the pointers are {\tt NULL} which is allowed). -Please note that this function is currently only implemented in wxUniv and -wxMSW ports. +Please note that this function is currently only implemented in wxUniv, +wxMSW and wxGTK2 ports. \wxheading{See also} @@ -841,7 +861,7 @@ returns a 3-element list \texttt{(result, col, row)}}. Returns {\tt true} if the controls contents may be edited by user (note that it always can be changed by the program), i.e. if the control hasn't been put in -read-only mode by a previous call to +read-only mode by a previous call to \helpref{SetEditable}{wxtextctrlseteditable}. @@ -849,9 +869,13 @@ read-only mode by a previous call to \constfunc{bool}{IsModified}{\void} -Returns {\tt true} if the text has been modified by user. Note that calling +Returns {\tt true} if the text has been modified by user. Note that calling \helpref{SetValue}{wxtextctrlsetvalue} doesn't make the control modified. +\wxheading{See also} + +\helpref{MarkDirty}{wxtextctrlmarkdirty} + \membersection{wxTextCtrl::IsMultiLine}\label{wxtextctrlismultiline} @@ -894,20 +918,20 @@ Loads and displays the named file, if it exists. % VZ: commenting this out as: (a) the docs are wrong (you can't replace % anything), (b) wxTextCtrl doesn't have any OnChar() anyhow %% \membersection{wxTextCtrl::OnChar}\label{wxtextctrlonchar} -%% +%% %% \func{void}{OnChar}{\param{wxKeyEvent\& }{event}} -%% +%% %% Default handler for character input. -%% +%% %% \wxheading{Remarks} -%% +%% %% It is possible to intercept character %% input by overriding this member. Call this function %% to let the default behaviour take place; not calling %% it results in the character being ignored. You can %% replace the {\it keyCode} member of {\it event} to %% translate keystrokes. -%% +%% %% Note that Windows and Motif have different ways %% of implementing the default behaviour. In Windows, %% calling wxTextCtrl::OnChar immediately @@ -916,12 +940,23 @@ Loads and displays the named file, if it exists. %% to let default processing happen. This might affect %% the way in which you write your OnChar function %% on different platforms. -%% +%% %% \wxheading{See also} -%% +%% %% \helpref{wxKeyEvent}{wxkeyevent} +\membersection{wxTextCtrl::MarkDirty}\label{wxtextctrlmarkdirty} + +\func{void}{MarkDirty}{\void} + +Mark text as modified (dirty). + +\wxheading{See also} + +\helpref{IsModified}{wxtextctrlismodified} + + \membersection{wxTextCtrl::OnDropFiles}\label{wxtextctrlondropfiles} \func{void}{OnDropFiles}{\param{wxDropFilesEvent\& }{event}} @@ -1056,7 +1091,7 @@ wouldn't change it at all). \wxheading{Return value} -{\tt true} on success, {\tt false} if an error occured - may also mean that +{\tt true} on success, {\tt false} if an error occurred - may also mean that the styles are not supported under this platform. \wxheading{See also} @@ -1116,7 +1151,7 @@ already is filled up to the maximal length, a (giving it the possibility to show an explanatory message, for example) and the extra input is discarded. -Note that this function may only be used with single line text controls. +Note that under GTK+, this function may only be used with single line text controls. \wxheading{Compatibility} @@ -1143,7 +1178,7 @@ in the control is selected. \func{bool}{SetStyle}{\param{long }{start}, \param{long }{end}, \param{const wxTextAttr\& }{style}} Changes the style of the given range. If any attribute within {\it style} is -not set, the correspondign attribute from \helpref{GetDefaultStyle()}{wxtextctrlgetdefaultstyle} is used. +not set, the corresponding attribute from \helpref{GetDefaultStyle()}{wxtextctrlgetdefaultstyle} is used. \wxheading{Parameters} @@ -1155,7 +1190,7 @@ not set, the correspondign attribute from \helpref{GetDefaultStyle()}{wxtextctrl \wxheading{Return value} -{\tt true} on success, {\tt false} if an error occured - it may also mean that +{\tt true} on success, {\tt false} if an error occurred - it may also mean that the styles are not supported under this platform. \wxheading{See also} @@ -1167,7 +1202,7 @@ the styles are not supported under this platform. \func{virtual void}{SetValue}{\param{const wxString\& }{ value}} -Sets the text value and marks the control as not-modified (which means that +Sets the text value and marks the control as not-modified (which means that \helpref{IsModified}{wxtextctrlismodified} would return {\tt false} immediately after the call to SetValue). @@ -1231,7 +1266,7 @@ Converts the given zero based column and line number to a position. \wxheading{Return value} -The position value. +The position value, or -1 if {\tt x} or {\tt y} was invalid. \membersection{wxTextCtrl::operator \cinsert}\label{wxtextctrlinsert}