added wxHtmlHelpController::AddBook(wxFileName)

[wxWidgets.git] / docs / latex / wx / text.tex

diff --git a/docs/latex/wx/text.tex b/docs/latex/wx/text.tex
index ef91d18241db3148c6aa544439f3ab82911e77b5..32527801c38eb56fa32cb2ddd5898fde8b6c6549 100644 (file)
--- a/docs/latex/wx/text.tex
+++ b/docs/latex/wx/text.tex
@@ -95,7 +95,7 @@ streambuf\\
 the message wxEVENT\_TYPE\_TEXT\_ENTER\_COMMAND (otherwise pressing <Enter> is
 either processed internally by the control or used for navigation between
 dialog controls).}
 the message wxEVENT\_TYPE\_TEXT\_ENTER\_COMMAND (otherwise pressing <Enter> is
 either processed internally by the control or used for navigation between
 dialog controls).}

-\twocolitem{\windowstyle{wxTE\_PROCESS\_TAB}}{The control will receieve
+\twocolitem{\windowstyle{wxTE\_PROCESS\_TAB}}{The control will receive

 EVT\_CHAR messages 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.}
 EVT\_CHAR messages 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.}


@@ -114,11 +114,40 @@ under Win32 only and requires wxTE\_RICH.}
 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. No effect under GTK+.}
 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. No effect under GTK+.}

+\twocolitem{\windowstyle{wxTE\_LEFT}}{The text control will be left-justified (default).}
+\twocolitem{\windowstyle{wxTE\_CENTRE}}{The text control will be centre-justified.}
+\twocolitem{\windowstyle{wxTE\_RIGHT}}{The text 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).}

 \end{twocollist}
 
 See also \helpref{window styles overview}{windowstyles} and
 \helpref{wxTextCtrl::wxTextCtrl}{wxtextctrlconstr}.
 
 \end{twocollist}
 
 See also \helpref{window styles overview}{windowstyles} and
 \helpref{wxTextCtrl::wxTextCtrl}{wxtextctrlconstr}.
 

+\wxheading{wxTextCtrl text format}
+
+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 
+\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 
+{\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 
+\helpref{SetSelection}{wxtextctrlsetselection}.
+
+To summarize: never use the indices returned by (multiline) wxTextCtrl as
+indices into the string it contains, but only as arguments to be passed back
+to the other wxTextCtrl methods.
+

 \wxheading{wxTextCtrl styles}
 
 Multi-line text controls support the styles, i.e. provide a possibility to set
 \wxheading{wxTextCtrl styles}
 
 Multi-line text controls support the styles, i.e. provide a possibility to set


@@ -257,8 +286,8 @@ into the control than the limit set by
 Default constructor.
 
 \func{}{wxTextCtrl}{\param{wxWindow* }{parent}, \param{wxWindowID}{ id},\rtfsp
 Default constructor.
 
 \func{}{wxTextCtrl}{\param{wxWindow* }{parent}, \param{wxWindowID}{ id},\rtfsp

-\param{const wxString\& }{value = ``"}, \param{const wxPoint\& }{pos}, \param{const wxSize\& }{size = wxDefaultSize},\rtfsp
-\param{long}{ style = 0}, \param{const wxValidator\& }{validator}, \param{const wxString\& }{name = ``text"}}
+\param{const wxString\& }{value = ``"}, \param{const wxPoint\& }{pos = wxDefaultPosition}, \param{const wxSize\& }{size = wxDefaultSize},\rtfsp
+\param{long}{ style = 0}, \param{const wxValidator\& }{validator = wxDefaultValidator}, \param{const wxString\& }{name = wxTextCtrlNameStr}}

 
 Constructor, creating and showing a text control.
 
 
 Constructor, creating and showing a text control.
 


@@ -282,7 +311,8 @@ Constructor, creating and showing a text control.
 
 \wxheading{Remarks}
 
 
 \wxheading{Remarks}
 

-The horizontal scrollbar ({\bf wxTE\_HSCROLL} style flag) will only be created for multi-line text controls.
+The horizontal scrollbar ({\bf wxHSCROLL} style flag) will only be created
+for multi-line text controls.

 Without a horizontal scrollbar, text lines that don't fit in the control's
 size will be wrapped (but no newline character is inserted). Single line
 controls don't have a horizontal scrollbar, the text is automatically scrolled
 Without a horizontal scrollbar, text lines that don't fit in the control's
 size will be wrapped (but no newline character is inserted). Single line
 controls don't have a horizontal scrollbar, the text is automatically scrolled


@@ -363,6 +393,9 @@ can be undone.
 
 Clears the text in the control.
 
 
 Clears the text in the control.
 

+Note that this function will generate a {\tt wxEVT\_COMMAND\_TEXT\_UPDATED}
+event.
+

 \membersection{wxTextCtrl::Copy}\label{wxtextctrlcopy}
 
 \func{virtual void}{Copy}{\void}
 \membersection{wxTextCtrl::Copy}\label{wxtextctrlcopy}
 
 \func{virtual void}{Copy}{\void}


@@ -372,8 +405,8 @@ Copies the selected text to the clipboard under Motif and MS Windows.
 \membersection{wxTextCtrl::Create}\label{wxtextctrlcreate}
 
 \func{bool}{Create}{\param{wxWindow* }{parent}, \param{wxWindowID}{ id},\rtfsp
 \membersection{wxTextCtrl::Create}\label{wxtextctrlcreate}
 
 \func{bool}{Create}{\param{wxWindow* }{parent}, \param{wxWindowID}{ id},\rtfsp

-\param{const wxString\& }{value = ``"}, \param{const wxPoint\& }{pos}, \param{const wxSize\& }{size = wxDefaultSize},\rtfsp
-\param{long}{ style = 0}, \param{const wxValidator\& }{validator}, \param{const wxString\& }{name = ``text"}}
+\param{const wxString\& }{value = ``"}, \param{const wxPoint\& }{pos = wxDefaultPosition}, \param{const wxSize\& }{size = wxDefaultSize},\rtfsp
+\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
 
 Creates the text control for two-step construction. Derived classes
 should call or replace this function. See \helpref{wxTextCtrl::wxTextCtrl}{wxtextctrlconstr}\rtfsp


@@ -391,6 +424,20 @@ Copies the selected text to the clipboard and removes the selection.
 
 Resets the internal `modified' flag as if the current edits had been saved.
 
 
 Resets the internal `modified' flag as if the current edits had been saved.
 

+\membersection{wxTextCtrl::EmulateKeyPress}
+
+\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 
+{\it event} object should be the same as the one passed to {\tt EVT\_KEY\_DOWN}
+handler previously by wxWindows.
+
+\wxheading{Return value}
+
+{\tt TRUE} if the event resulted in a change to the control, {\tt FALSE}
+otherwise.
+

 \membersection{wxTextCtrl::GetDefaultStyle}\label{wxtextctrlgetdefaultstyle}
 
 \constfunc{const wxTextAttr\& }{GetDefaultStyle}{\void}
 \membersection{wxTextCtrl::GetDefaultStyle}\label{wxtextctrlgetdefaultstyle}
 
 \constfunc{const wxTextAttr\& }{GetDefaultStyle}{\void}


@@ -530,8 +577,18 @@ returned string is empty.
 \constfunc{wxString}{GetValue}{\void}
 
 Gets the contents of the control. Notice that for a multiline text control,
 \constfunc{wxString}{GetValue}{\void}
 
 Gets the contents of the control. Notice that for a multiline text control,

-the lines will be separated by (Unix-style) $\backslash$n characters, even under
-Windows where they are separated by a $\backslash$r$\backslash$n sequence in the native control.
+the lines will be separated by (Unix-style) $\backslash$n characters, even
+under Windows where they are separated by a $\backslash$r$\backslash$n
+sequence in the native control.
+
+\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 
+\helpref{SetEditable}{wxtextctrlseteditable}.

 
 \membersection{wxTextCtrl::IsModified}\label{wxtextctrlismodified}
 
 
 \membersection{wxTextCtrl::IsModified}\label{wxtextctrlismodified}
 


@@ -540,6 +597,28 @@ Windows where they are separated by a $\backslash$r$\backslash$n sequence in the
 Returns {\tt TRUE} if the text has been modified by user. Note that calling 
 \helpref{SetValue}{wxtextctrlsetvalue} doesn't make the control modified.
 
 Returns {\tt TRUE} if the text has been modified by user. Note that calling 
 \helpref{SetValue}{wxtextctrlsetvalue} doesn't make the control modified.
 

+\membersection{wxTextCtrl::IsMultiLine}\label{wxtextctrlismultiline}
+
+\constfunc{bool}{IsMultiLine}{\void}
+
+Returns {\tt TRUE} if this is a multi line edit control and {\tt FALSE}
+otherwise.
+
+\wxheading{See also}
+
+\helpref{IsSingleLine}{wxtextctrlissingleline}
+
+\membersection{wxTextCtrl::IsSingleLine}\label{wxtextctrlissingleline}
+
+\constfunc{bool}{IsSingleLine}{\void}
+
+Returns {\tt TRUE} if this is a single line edit control and {\tt FALSE}
+otherwise.
+
+\wxheading{See also}
+
+\helpref{IsMultiLine}{wxtextctrlissingleline}
+

 \membersection{wxTextCtrl::LoadFile}\label{wxtextctrlloadfile}
 
 \func{bool}{LoadFile}{\param{const wxString\& }{ filename}}
 \membersection{wxTextCtrl::LoadFile}\label{wxtextctrlloadfile}
 
 \func{bool}{LoadFile}{\param{const wxString\& }{ filename}}


@@ -554,33 +633,35 @@ Loads and displays the named file, if it exists.
 
 {\tt TRUE} if successful, {\tt FALSE} otherwise.
 
 
 {\tt TRUE} if successful, {\tt FALSE} otherwise.
 

-\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
-processes the character. In Motif,
-calling this function simply sets a flag
-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}
+% 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
+%% processes the character. In Motif,
+%% calling this function simply sets a flag
+%% 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::OnDropFiles}\label{wxtextctrlondropfiles}
 
 
 \membersection{wxTextCtrl::OnDropFiles}\label{wxtextctrlondropfiles}
 


@@ -726,6 +807,10 @@ Makes the text item editable or read-only, overriding the {\bf wxTE\_READONLY} f
 
 \docparam{editable}{If {\tt TRUE}, the control is editable. If {\tt FALSE}, the control is read-only.}
 
 
 \docparam{editable}{If {\tt TRUE}, the control is editable. If {\tt FALSE}, the control is read-only.}
 

+\wxheading{See also}
+
+\helpref{IsEditable}{wxtextctrliseditable}
+

 \membersection{wxTextCtrl::SetInsertionPoint}\label{wxtextctrlsetinsertionpoint}
 
 \func{virtual void}{SetInsertionPoint}{\param{long}{ pos}}
 \membersection{wxTextCtrl::SetInsertionPoint}\label{wxtextctrlsetinsertionpoint}
 
 \func{virtual void}{SetInsertionPoint}{\param{long}{ pos}}


@@ -751,7 +836,7 @@ This function sets the maximum number of characters the user can enter into the
 control. In other words, it allows to limit the text value length to {\it len}
 not counting the terminating {\tt NUL} character.
 
 control. In other words, it allows to limit the text value length to {\it len}
 not counting the terminating {\tt NUL} character.
 

-If {\it len} is $0$, the previously set max length limi, if any, is discarded
+If {\it len} is $0$, the previously set max length limit, if any, is discarded

 and the user may enter as much text as the underlying native text control
 widget supports (typically at least 32Kb).
 
 and the user may enter as much text as the underlying native text control
 widget supports (typically at least 32Kb).
 


@@ -771,7 +856,9 @@ Only implemented in wxMSW/wxGTK starting with wxWindows 2.3.2.
 
 \func{virtual void}{SetSelection}{\param{long}{ from}, \param{long}{ to}}
 
 
 \func{virtual void}{SetSelection}{\param{long}{ from}, \param{long}{ to}}
 

-Selects the text starting at the first position up to (but not including) the character at the last position.
+Selects the text starting at the first position up to (but not including) the
+character at the last position. If both parameters are equal to $-1$ all text
+in the control is selected.

 
 \wxheading{Parameters}
 
 
 \wxheading{Parameters}
 


@@ -808,6 +895,9 @@ 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).
 
 \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.
+

 \wxheading{Parameters}
 
 \docparam{value}{The new value to set. It may contain newline characters if the text control is multi-line.}
 \wxheading{Parameters}
 
 \docparam{value}{The new value to set. It may contain newline characters if the text control is multi-line.}