X-Git-Url: https://git.saurik.com/wxWidgets.git/blobdiff_plain/e119d0498a529d438d337a8b788c5b2333a20f93..9e967d5417d49764276cf121a32c35d5770b1332:/docs/latex/wx/text.tex diff --git a/docs/latex/wx/text.tex b/docs/latex/wx/text.tex index f99cba9690..9f2d342360 100644 --- a/docs/latex/wx/text.tex +++ b/docs/latex/wx/text.tex @@ -1,251 +1,3 @@ -%%%%%%%%%%%%%%%%%%%%%%%%%%%% wxTextAttr %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% - -\section{\class{wxTextAttr}}\label{wxtextattr} - -wxTextAttr represents the character and paragraph attributes, or style, for a range of text in a\rtfsp -\helpref{wxTextCtrl}{wxtextctrl}. - -When setting up a wxTextAttr object, pass a bitlist mask to SetFlags to indicate -which style elements should be changed. As a convenience, when you call a -setter such as SetFont, the relevant bit will be set. - -\wxheading{Derived from} - -No base class - -\wxheading{Include files} - - - -\wxheading{Typedefs} - -\texttt{wxTextPos} is the type containing the index of a position in a text -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 -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. - -\wxheading{Constants} - -The following values can be passed to SetAlignment to determine -paragraph alignment. - -{\small -\begin{verbatim} -enum wxTextAttrAlignment -{ - wxTEXT_ALIGNMENT_DEFAULT, - wxTEXT_ALIGNMENT_LEFT, - wxTEXT_ALIGNMENT_CENTRE, - wxTEXT_ALIGNMENT_CENTER = wxTEXT_ALIGNMENT_CENTRE, - wxTEXT_ALIGNMENT_RIGHT, - wxTEXT_ALIGNMENT_JUSTIFIED -}; -\end{verbatim} -} - -These values are passed in a bitlist to SetFlags to determine -what attributes will be considered when setting the attributes -for a text control. - -{\small -\begin{verbatim} -#define wxTEXT_ATTR_TEXT_COLOUR 0x0001 -#define wxTEXT_ATTR_BACKGROUND_COLOUR 0x0002 -#define wxTEXT_ATTR_FONT_FACE 0x0004 -#define wxTEXT_ATTR_FONT_SIZE 0x0008 -#define wxTEXT_ATTR_FONT_WEIGHT 0x0010 -#define wxTEXT_ATTR_FONT_ITALIC 0x0020 -#define wxTEXT_ATTR_FONT_UNDERLINE 0x0040 -#define wxTEXT_ATTR_FONT \ - wxTEXT_ATTR_FONT_FACE | wxTEXT_ATTR_FONT_SIZE | wxTEXT_ATTR_FONT_WEIGHT \ -| wxTEXT_ATTR_FONT_ITALIC | wxTEXT_ATTR_FONT_UNDERLINE -#define wxTEXT_ATTR_ALIGNMENT 0x0080 -#define wxTEXT_ATTR_LEFT_INDENT 0x0100 -#define wxTEXT_ATTR_RIGHT_INDENT 0x0200 -#define wxTEXT_ATTR_TABS 0x0400 -\end{verbatim} -} - -The values below are the possible return codes of the -\helpref{HitTest}{wxtextctrlhittest} method: -{\small -\begin{verbatim} -// the point asked is ... -enum wxTextCtrlHitTestResult -{ - wxTE_HT_UNKNOWN = -2, // this means HitTest() is simply not implemented - wxTE_HT_BEFORE, // either to the left or upper - wxTE_HT_ON_TEXT, // directly on - wxTE_HT_BELOW, // below [the last line] - wxTE_HT_BEYOND // after [the end of line] -}; -// ... the character returned -\end{verbatim} -} - - -\latexignore{\rtfignore{\wxheading{Members}}} - - -\membersection{wxTextAttr::wxTextAttr}\label{wxtextattrctor} - -\func{}{wxTextAttr}{\void} - -\func{}{wxTextAttr}{\param{const wxColour\& }{colText}, \param{const wxColour\& }{colBack = wxNullColour}, - \param{const wxFont\& }{font = wxNullFont}, \param{wxTextAttrAlignment }{alignment = wxTEXT\_ALIGNMENT\_DEFAULT}} - -The constructors initialize one or more of the text foreground colour, background -colour, font, and alignment. The values not initialized in the constructor can be set -later, otherwise \helpref{wxTextCtrl::SetStyle}{wxtextctrlsetstyle} will use -the default values for them. - - -\membersection{wxTextAttr::GetAlignment}\label{wxtextattrgetalignment} - -\constfunc{wxTextAttrAlignment}{GetAlignment}{\void} - -Returns the paragraph alignment. - - -\membersection{wxTextAttr::GetBackgroundColour}\label{wxtextattrgetbackgroundcolour} - -\constfunc{const wxColour\&}{GetBackgroundColour}{\void} - -Return the background colour specified by this attribute. - - -\membersection{wxTextAttr::GetFont}\label{wxtextattrgetfont} - -\constfunc{const wxFont\&}{GetFont}{\void} - -Return the text font specified by this attribute. - - -\membersection{wxTextAttr::GetLeftIndent}\label{wxtextattrgetleftindent} - -\constfunc{int}{GetLeftIndent}{\void} - -Returns the left indent in tenths of a millimetre. - - -\membersection{wxTextAttr::GetRightIndent}\label{wxtextattrgetrightindent} - -\constfunc{int}{GetRightIndent}{\void} - -Returns the right indent in tenths of a millimetre. - - -\membersection{wxTextAttr::GetTabs}\label{wxtextattrgettabs} - -\constfunc{const wxArrayInt\&}{GetTabs}{\void} - -Returns the array of integers representing the tab stops. Each -array element specifies the tab stop in tenths of a millimetre. - - -\membersection{wxTextAttr::GetTextColour}\label{wxtextattrgettextcolour} - -\constfunc{const wxColour\&}{GetTextColour}{\void} - -Return the text colour specified by this attribute. - - -\membersection{wxTextAttr::HasBackgroundColour}\label{wxtextattrhasbackgroundcolour} - -\constfunc{bool}{HasBackgroundColour}{\void} - -Returns {\tt true} if this style specifies the background colour to use. - - -\membersection{wxTextAttr::HasFont}\label{wxtextattrhasfont} - -\constfunc{bool}{HasFont}{\void} - -Returns {\tt true} if this style specifies the font to use. - - -\membersection{wxTextAttr::HasTextColour}\label{wxtextattrhastextcolour} - -\constfunc{bool}{HasTextColour}{\void} - -Returns {\tt true} if this style specifies the foreground colour to use. - - -\membersection{wxTextAttr::GetFlags}\label{wxtextattrgetflags} - -\func{long}{GetFlags}{\void} - -Returns a bitlist indicating which attributes will be set. - - -\membersection{wxTextAttr::IsDefault}\label{wxtextattrisdefault} - -\constfunc{bool}{IsDefault}{\void} - -Returns {\tt true} if this style specifies any non-default attributes. - - -\membersection{wxTextAttr::SetAlignment}\label{wxtextattrsetalignment} - -\func{void}{SetAlignment}{\param{wxTextAttrAlignment}{ alignment}} - -Sets the paragraph alignment. - - -\membersection{wxTextAttr::SetBackgroundColour}\label{wxtextattrsetbackgroundcolour} - -\func{void}{SetBackgroundColour}{\param{const wxColour\& }{colour}} - -Sets the background colour. - - -\membersection{wxTextAttr::SetFlags}\label{wxtextattrsetflags} - -\func{void}{SetFlags}{\param{long}{ flags}} - -Pass a bitlist indicating which attributes will be set. - - -\membersection{wxTextAttr::SetFont}\label{wxtextattrsetfont} - -\func{void}{SetFont}{\param{const wxFont\&}{ font}} - -Sets the text font. - - -\membersection{wxTextAttr::SetLeftIndent}\label{wxtextattrsetleftindent} - -\func{void}{SetLeftIndent}{\param{int }{indent}} - -Sets the left indent in tenths of a millimetre. - - -\membersection{wxTextAttr::SetRightIndent}\label{wxtextattrsetrightindent} - -\func{void}{SetRightIndent}{\param{int }{indent}} - -Sets the right indent in tenths of a millimetre. - - -\membersection{wxTextAttr::SetTabs}\label{wxtextattrsettabs} - -\func{void}{SetTabs}{\param{const wxArrayInt\&}{ tabs}} - -Sets the array of integers representing the tab stops. Each -array element specifies the tab stop in tenths of a millimetre. - - -\membersection{wxTextAttr::SetTextColour}\label{wxtextattrsettextcolour} - -\func{void}{SetTextColour}{\param{const wxColour\& }{colour}} - -Sets the text colour. - - %%%%%%%%%%%%%%%%%%%%%%%%%%%% wxTextCtrl %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% \section{\class{wxTextCtrl}}\label{wxtextctrl} @@ -265,16 +17,20 @@ streambuf\\ +\wxheading{Library} + +\helpref{wxCore}{librarieslist} + \wxheading{Window styles} \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.} @@ -286,23 +42,36 @@ 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\_NO\_VSCROLL}}{For multiline controls only: +vertical scrollbar will never be created. This limits the amount of text which +can be entered into the control to what can be displayed in it under MSW but +not under GTK2. Currently not implemented for the other platforms.} \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.} -\twocolitem{\windowstyle{wxTE\_RIGHT}}{The text in the control will be right-justified.} -\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\_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: 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}. + +Note that alignment styles (\windowstyle{wxTE\_LEFT}, +\windowstyle{wxTE\_CENTRE} and \windowstyle{wxTE\_RIGHT}) can be changed +dynamically after control creation on wxMSW and wxGTK. +\windowstyle{wxTE\_READONLY}, \windowstyle{wxTE\_PASSWORD} and wrapping styles +can be dynamically changed under wxGTK but not wxMSW. The other styles can be +only set during control creation. + \wxheading{wxTextCtrl text format} @@ -310,17 +79,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 @@ -413,7 +182,7 @@ control. This could be done in the following way: \end{verbatim} }% -But wxWindows provides a convenient class to make it even simpler so instead +But wxWidgets provides a convenient class to make it even simpler so instead you may just do {\small% @@ -432,6 +201,27 @@ you may just do See \helpref{wxStreamToTextRedirector}{wxstreamtotextredirector} for more details. +\wxheading{Constants} + +The values below are the possible return codes of the +\helpref{HitTest}{wxtextctrlhittest} method: + +{\small +\begin{verbatim} +// the point asked is ... +enum wxTextCtrlHitTestResult +{ + wxTE_HT_UNKNOWN = -2, // this means HitTest() is simply not implemented + wxTE_HT_BEFORE, // either to the left or upper + wxTE_HT_ON_TEXT, // directly on + wxTE_HT_BELOW, // below [the last line] + wxTE_HT_BEYOND // after [the end of line] +}; +// ... the character returned +\end{verbatim} +} + + \wxheading{Event handling} The following commands are processed by default event handlers in wxTextCtrl: wxID\_CUT, wxID\_COPY, @@ -444,14 +234,15 @@ functions that take a \helpref{wxCommandEvent}{wxcommandevent} argument. \twocolwidtha{7cm}% \begin{twocollist}\itemsep=0pt \twocolitem{{\bf EVT\_TEXT(id, func)}}{Respond to a wxEVT\_COMMAND\_TEXT\_UPDATED event, -generated when the text changes. Notice that this event will always be sent +generated when the text changes. Notice that this event will be sent when the text controls contents changes - whether this is due to user input or -comes from the program itself (for example, if SetValue() is called)} +comes from the program itself (for example, if SetValue() is called); see ChangeValue() for +a function which does not send this event.} \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}.} @@ -460,7 +251,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} @@ -510,7 +301,7 @@ visible. \helpref{wxTextCtrl::Create}{wxtextctrlcreate}, \helpref{wxValidator}{wxvalidator} -\membersection{wxTextCtrl::\destruct{wxTextCtrl}} +\membersection{wxTextCtrl::\destruct{wxTextCtrl}}\label{wxtextctrldtor} \func{}{\destruct{wxTextCtrl}}{\void} @@ -537,6 +328,50 @@ the programmer should use \helpref{GetInsertionPoint}{wxtextctrlgetinsertionpoin \helpref{wxTextCtrl::WriteText}{wxtextctrlwritetext} +\membersection{wxTextCtrl::AutoComplete}\label{wxtextctrlautocomplete} + +\func{bool}{AutoComplete}{\param{const wxArrayString\& }{choices}} + +Call this function to enable auto-completion of the text typed in a single-line +text control using the given \arg{choices}. + +Notice that currently this function is only implemented in wxGTK2 and wxMSW +ports and does nothing under the other platforms. + +\newsince{2.9.0} + +\wxheading{Return value} + +\true if the auto-completion was enabled or \false if the operation failed, +typically because auto-completion is not supported by the current platform. + +\wxheading{See also} + +\helpref{AutoCompleteFileNames}{wxtextctrlautocompletefilenames} + + +\membersection{wxTextCtrl::AutoCompleteFileNames}\label{wxtextctrlautocompletefilenames} + +\func{bool}{AutoCompleteFileNames}{\void} + +Call this function to enable auto-completion of the text typed in a single-line +text control using all valid file system paths. + +Notice that currently this function is only implemented in wxGTK2 port and does +nothing under the other platforms. + +\newsince{2.9.0} + +\wxheading{Return value} + +\true if the auto-completion was enabled or \false if the operation failed, +typically because auto-completion is not supported by the current platform. + +\wxheading{See also} + +\helpref{AutoComplete}{wxtextctrlautocomplete} + + \membersection{wxTextCtrl::CanCopy}\label{wxtextctrlcancopy} \func{virtual bool}{CanCopy}{\void} @@ -600,7 +435,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. @@ -611,21 +446,21 @@ 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 wxWindows. +handler previously by wxWidgets. Please note that this function doesn't currently work correctly for all keys under any platform but MSW. @@ -673,7 +508,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. @@ -720,24 +555,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 @@ -788,7 +628,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} @@ -812,11 +652,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 -\arg{row} parameters (unless the pointers are \tt{NULL} which is allowed). +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} @@ -825,23 +665,39 @@ wxMSW ports. \perlnote{In wxPerl this function takes only the position argument and returns a 3-element list \texttt{(result, col, row)}}. + \membersection{wxTextCtrl::IsEditable}\label{wxtextctrliseditable} \constfunc{bool}{IsEditable}{\void} 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}. +\membersection{wxTextCtrl::IsEmpty}\label{wxtextctrlisempty} + +\constfunc{bool}{IsEmpty}{\void} + +Returns \true if the control is currently empty. This is the same as +\texttt{GetValue().empty()} but can be much more efficient for the multiline +controls containing big amounts of text. + +\newsince{2.7.1} + + \membersection{wxTextCtrl::IsModified}\label{wxtextctrlismodified} \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} @@ -869,7 +725,7 @@ otherwise. \membersection{wxTextCtrl::LoadFile}\label{wxtextctrlloadfile} -\func{bool}{LoadFile}{\param{const wxString\& }{ filename}} +\func{bool}{LoadFile}{\param{const wxString\& }{ filename}, \param{int }{fileType = wxTEXT\_TYPE\_ANY}} Loads and displays the named file, if it exists. @@ -877,6 +733,8 @@ Loads and displays the named file, if it exists. \docparam{filename}{The filename of the file to load.} +\docparam{fileType}{The type of file to load. This is currently ignored in wxTextCtrl.} + \wxheading{Return value} {\tt true} if successful, {\tt false} otherwise. @@ -884,20 +742,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 @@ -906,12 +764,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}} @@ -1010,7 +879,7 @@ the character at the last position with the given text. \membersection{wxTextCtrl::SaveFile}\label{wxtextctrlsavefile} -\func{bool}{SaveFile}{\param{const wxString\& }{ filename}} +\func{bool}{SaveFile}{\param{const wxString\& }{ filename}, \param{int }{fileType = wxTEXT\_TYPE\_ANY}} Saves the contents of the control in a text file. @@ -1018,6 +887,8 @@ Saves the contents of the control in a text file. \docparam{filename}{The name of the file in which to save the text.} +\docparam{fileType}{The type of file to save. This is currently ignored in wxTextCtrl.} + \wxheading{Return value} {\tt true} if the operation was successful, {\tt false} otherwise. @@ -1046,7 +917,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} @@ -1106,11 +977,22 @@ 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} -Only implemented in wxMSW/wxGTK starting with wxWindows 2.3.2. +Only implemented in wxMSW/wxGTK starting with wxWidgets 2.3.2. + + +\membersection{wxTextCtrl::SetModified}\label{wxtextctrlsetmodified} + +\func{void}{SetModified}{\param{bool }{modified}} + +Marks the control as being modified by the user or not. + +\wxheading{See also} + +\helpref{MarkDirty}{wxtextctrlmarkdirty}, \helpref{DiscardEdits}{wxtextctrldiscardedits} \membersection{wxTextCtrl::SetSelection}\label{wxtextctrlsetselection} @@ -1133,7 +1015,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} @@ -1145,7 +1027,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} @@ -1157,13 +1039,36 @@ 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). Note that this function will generate a {\tt wxEVT\_COMMAND\_TEXT\_UPDATED} event. +This function is deprecated and should not be used in new code. Please use the +\helpref{ChangeValue}{wxtextctrlchangevalue} function instead. + +\wxheading{Parameters} + +\docparam{value}{The new value to set. It may contain newline characters if the text control is multi-line.} + + +\membersection{wxTextCtrl::ChangeValue}\label{wxtextctrlchangevalue} + +\func{virtual void}{ChangeValue}{\param{const wxString\& }{ value}} + +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). + +Note that this function will \emph{not} generate the {\tt wxEVT\_COMMAND\_TEXT\_UPDATED} +event. +This is the only difference with \helpref{SetValue}{wxtextctrlsetvalue}. +See \helpref{this topic}{progevent} for more information. + +\newsince{2.7.1} + \wxheading{Parameters} \docparam{value}{The new value to set. It may contain newline characters if the text control is multi-line.} @@ -1221,7 +1126,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}