// Purpose: interface of wxTextAttr
// Author: wxWidgets team
// RCS-ID: $Id$
-// Licence: wxWindows license
+// Licence: wxWindows licence
/////////////////////////////////////////////////////////////////////////////
+/**
+ wxTextCtrl style flags
+*/
+#define wxTE_NO_VSCROLL 0x0002
+
+#define wxTE_READONLY 0x0010
+#define wxTE_MULTILINE 0x0020
+#define wxTE_PROCESS_TAB 0x0040
+
+// alignment flags
+#define wxTE_LEFT 0x0000 // 0x0000
+#define wxTE_CENTER wxALIGN_CENTER_HORIZONTAL // 0x0100
+#define wxTE_RIGHT wxALIGN_RIGHT // 0x0200
+#define wxTE_CENTRE wxTE_CENTER
+
+// this style means to use RICHEDIT control and does something only under wxMSW
+// and Win32 and is silently ignored under all other platforms
+#define wxTE_RICH 0x0080
+
+#define wxTE_PROCESS_ENTER 0x0400
+#define wxTE_PASSWORD 0x0800
+
+// automatically detect the URLs and generate the events when mouse is
+// moved/clicked over an URL
+//
+// this is for Win32 richedit and wxGTK2 multiline controls only so far
+#define wxTE_AUTO_URL 0x1000
+
+// 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
+#define wxTE_NOHIDESEL 0x2000
+
+// use wxHSCROLL to not wrap text at all, wxTE_CHARWRAP to wrap it at any
+// position and wxTE_WORDWRAP to wrap at words boundary
+//
+// if no wrapping style is given at all, the control wraps at word boundary
+#define wxTE_DONTWRAP wxHSCROLL
+#define wxTE_CHARWRAP 0x4000 // wrap at any position
+#define wxTE_WORDWRAP 0x0001 // wrap only at words boundaries
+#define wxTE_BESTWRAP 0x0000 // this is the default
+
+// force using RichEdit version 2.0 or 3.0 instead of 1.0 (default) for
+// wxTE_RICH controls - can be used together with or instead of wxTE_RICH
+#define wxTE_RICH2 0x8000
+
+
+#define wxTEXT_TYPE_ANY 0
+
+
+/**
+ wxTextCoord is a line or row number
+*/
+typedef long wxTextCoord;
+
/**
One of the following values can be passed to wxTextAttr::SetAlignment to determine paragraph alignment.
wxTEXT_ATTR_BACKGROUND_COLOUR = 0x00000002,
wxTEXT_ATTR_FONT_FACE = 0x00000004,
- wxTEXT_ATTR_FONT_SIZE = 0x00000008,
+ wxTEXT_ATTR_FONT_POINT_SIZE = 0x00000008,
+ wxTEXT_ATTR_FONT_PIXEL_SIZE = 0x10000000,
wxTEXT_ATTR_FONT_WEIGHT = 0x00000010,
wxTEXT_ATTR_FONT_ITALIC = 0x00000020,
wxTEXT_ATTR_FONT_UNDERLINE = 0x00000040,
+ wxTEXT_ATTR_FONT_STRIKETHROUGH = 0x08000000,
wxTEXT_ATTR_FONT_ENCODING = 0x02000000,
wxTEXT_ATTR_FONT_FAMILY = 0x04000000,
+ wxTEXT_ATTR_FONT_SIZE = \
+ ( wxTEXT_ATTR_FONT_POINT_SIZE | wxTEXT_ATTR_FONT_PIXEL_SIZE ),
/**
Defined as the combination of all @c wxTEXT_ATTR_FONT_* values above.
*/
wxTEXT_ATTR_FONT = \
( wxTEXT_ATTR_FONT_FACE | wxTEXT_ATTR_FONT_SIZE | wxTEXT_ATTR_FONT_WEIGHT | \
- wxTEXT_ATTR_FONT_ITALIC | wxTEXT_ATTR_FONT_UNDERLINE | wxTEXT_ATTR_FONT_ENCODING | wxTEXT_ATTR_FONT_FAMILY ),
+ wxTEXT_ATTR_FONT_ITALIC | wxTEXT_ATTR_FONT_UNDERLINE | wxTEXT_ATTR_FONT_STRIKETHROUGH | wxTEXT_ATTR_FONT_ENCODING | wxTEXT_ATTR_FONT_FAMILY ),
wxTEXT_ATTR_ALIGNMENT = 0x00000080,
wxTEXT_ATTR_LEFT_INDENT = 0x00000100,
/**
Styles for wxTextAttr::SetTextEffects(). They can be combined together as a bitlist.
- Of these, only wxTEXT_ATTR_EFFECT_CAPITALS and wxTEXT_ATTR_EFFECT_STRIKETHROUGH are implemented.
+ Of these, only wxTEXT_ATTR_EFFECT_CAPITALS, wxTEXT_ATTR_EFFECT_STRIKETHROUGH,
+ wxTEXT_ATTR_EFFECT_SUPERSCRIPT and wxTEXT_ATTR_EFFECT_SUBSCRIPT are implemented.
*/
enum wxTextAttrEffects
{
bool Apply(const wxTextAttr& style,
const wxTextAttr* compareWith = NULL);
- /**
- Creates a font from the font attributes.
- */
- wxFont CreateFont() const;
-
/**
Copies all defined/valid properties from overlay to current object.
*/
const wxTextAttr& overlay);
+ /**
+ Partial equality test. If @a weakTest is @true, attributes of this object do not
+ have to be present if those attributes of @a attr are present. If @a weakTest is
+ @false, the function will fail if an attribute is present in @a attr but not
+ in this object.
+ */
+ bool EqPartial(const wxTextAttr& attr, bool weakTest = true) const;
+
/**
@name GetXXX functions
*/
bool HasFontItalic() const;
/**
- Returns @true if the attribute object specifies a font point size.
+ Returns @true if the attribute object specifies a font point or pixel size.
*/
bool HasFontSize() const;
+ /**
+ Returns @true if the attribute object specifies a font point size.
+ */
+ bool HasFontPointSize() const;
+
+ /**
+ Returns @true if the attribute object specifies a font pixel size.
+ */
+ bool HasFontPixelSize() const;
+
/**
Returns @true if the attribute object specifies either underlining or no
underlining.
Sets the attributes for the given font.
Note that wxTextAttr does not store an actual wxFont object.
*/
- void SetFont(const wxFont& font, int flags = wxTEXT_ATTR_FONT);
+ void SetFont(const wxFont& font, int flags = wxTEXT_ATTR_FONT & ~wxTEXT_ATTR_FONT_PIXEL_SIZE);
/**
Sets the font encoding.
*/
void SetFontSize(int pointSize);
+ /**
+ Sets the font size in points.
+ */
+ void SetFontPointSize(int pointSize);
+
+ /**
+ Sets the font size in pixels.
+ */
+ void SetFontPixelSize(int pixelSize);
+
/**
Sets the font style (normal, italic or slanted).
*/
void SetTabs(const wxArrayInt& tabs);
/**
- Sets the text foreground colout.
+ Sets the text foreground colour.
*/
void SetTextColour(const wxColour& colText);
Sets the text effects, a bit list of styles.
The ::wxTextAttrEffects enumeration values can be used.
- Of these, only wxTEXT_ATTR_EFFECT_CAPITALS and wxTEXT_ATTR_EFFECT_STRIKETHROUGH
- are implemented.
+ Of these, only wxTEXT_ATTR_EFFECT_CAPITALS, wxTEXT_ATTR_EFFECT_STRIKETHROUGH,
+ wxTEXT_ATTR_EFFECT_SUPERSCRIPT and wxTEXT_ATTR_EFFECT_SUBSCRIPT are implemented.
wxTEXT_ATTR_EFFECT_CAPITALS capitalises text when displayed (leaving the case
of the actual buffer text unchanged), and wxTEXT_ATTR_EFFECT_STRIKETHROUGH draws
/**
Assignment from a wxTextAttr object.
*/
- void operator operator=(const wxTextAttr& attr);
+ void operator=(const wxTextAttr& attr);
};
A text control allows text to be displayed and edited.
- It may be single line or multi-line.
+ It may be single line or multi-line. Notice that a lot of methods of the
+ text controls are found in the base wxTextEntry class which is a common
+ base class for wxTextCtrl and other controls using a single line text entry
+ field (e.g. wxComboBox).
@beginStyleTable
@style{wxTE_PROCESS_ENTER}
- The control will generate the event wxEVT_COMMAND_TEXT_ENTER
+ The control will generate the event @c wxEVT_COMMAND_TEXT_ENTER
(otherwise pressing Enter key is either processed internally by the
control or used for navigation between dialog controls).
@style{wxTE_PROCESS_TAB}
- The control will receive wxEVT_CHAR events for TAB pressed -
+ The control will receive @c 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.
@style{wxTE_MULTILINE}
- The text control allows multiple lines.
+ The text control allows multiple lines. If this style is not
+ specified, line break characters should not be used in the controls
+ value.
@style{wxTE_PASSWORD}
The text will be echoed as asterisks.
@style{wxTE_READONLY}
wxID_REDO. The associated UI update events are also processed
automatically, when the control has the focus.
- @beginEventTable{wxCommandEvent}
+ @beginEventEmissionTable{wxCommandEvent}
@event{EVT_TEXT(id, func)}
- Respond to a wxEVT_COMMAND_TEXT_UPDATED event, generated when the text
+ Respond to a @c wxEVT_COMMAND_TEXT_UPDATED event, 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 wxTextCtrl::SetValue() is called); see
wxTextCtrl::ChangeValue() for a function which does not send this event.
This event is however not sent during the control creation.
@event{EVT_TEXT_ENTER(id, func)}
- Respond to a wxEVT_COMMAND_TEXT_ENTER event, generated when enter is
+ Respond to a @c 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.
@event{EVT_TEXT_URL(id, func)}
@see wxTextCtrl::Create, wxValidator
*/
-class wxTextCtrl : public wxControl
+class wxTextCtrl : public wxControl,
+ public wxTextEntry
{
public:
/**
*/
virtual ~wxTextCtrl();
- /**
- Appends the text to the end of the text control.
-
- @param text
- Text to write to the text control.
-
- @remarks
- After the text is appended, the insertion point will be at the
- end of the text control. If this behaviour is not desired, the
- programmer should use GetInsertionPoint() and SetInsertionPoint().
-
- @see WriteText()
- */
- virtual void AppendText(const wxString& text);
-
- /**
- Call this function to enable auto-completion of the text typed in a
- single-line text control using the given @a choices.
-
- Notice that currently this function is only implemented in wxGTK2 and
- wxMSW ports and does nothing under the other platforms.
-
- @since 2.9.0
-
- @return
- @true if the auto-completion was enabled or @false if the operation
- failed, typically because auto-completion is not supported by the
- current platform.
-
- @see AutoCompleteFileNames()
- */
- virtual bool AutoComplete(const wxArrayString& choices);
-
- /**
- 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.
-
- @since 2.9.0
-
- @return
- @true if the auto-completion was enabled or @false if the operation
- failed, typically because auto-completion is not supported by the
- current platform.
-
- @see AutoComplete()
- */
- virtual bool AutoCompleteFileNames();
-
- /**
- Returns @true if the selection can be copied to the clipboard.
- */
- virtual bool CanCopy() const;
-
- /**
- Returns @true if the selection can be cut to the clipboard.
- */
- virtual bool CanCut() const;
-
- /**
- Returns @true if the contents of the clipboard can be pasted into the
- text control.
-
- On some platforms (Motif, GTK) this is an approximation and returns
- @true if the control is editable, @false otherwise.
- */
- virtual bool CanPaste() const;
-
- /**
- Returns @true if there is a redo facility available and the last
- operation can be redone.
- */
- virtual bool CanRedo() const;
-
- /**
- Returns @true if there is an undo facility available and the last
- operation can be undone.
- */
- virtual bool CanUndo() const;
-
- /**
- Sets the new text control value.
-
- It also marks the control as not-modified which means that IsModified()
- would return @false immediately after the call to SetValue().
-
- The insertion point is set to the start of the control (i.e. position
- 0) by this function.
-
- This functions does not generate the @c wxEVT_COMMAND_TEXT_UPDATED
- event but otherwise is identical to SetValue().
-
- See @ref overview_eventhandling_prog for more information.
-
- @since 2.7.1
-
- @param value
- The new value to set. It may contain newline characters if the text
- control is multi-line.
- */
- virtual void ChangeValue(const wxString& value);
-
- /**
- Clears the text in the control.
-
- Note that this function will generate a @c wxEVT_COMMAND_TEXT_UPDATED
- event, i.e. its effect is identical to calling @c SetValue("").
- */
- virtual void Clear();
-
- /**
- Copies the selected text to the clipboard.
- */
- virtual void Copy();
-
/**
Creates the text control for two-step construction.
virtual void DiscardEdits();
/**
- This functions inserts into the control the character which would have
+ This function inserts into the control the character which would have
been inserted if the given key event had occurred in the text control.
The @a event object should be the same as the one passed to @c EVT_KEY_DOWN
*/
virtual const wxTextAttr& GetDefaultStyle() const;
- /**
- Returns the insertion point, or cursor, position.
-
- This is defined as the zero based index of the character position to
- the right of the insertion point. For example, if the insertion point
- is at the end of the single-line text control, it is equal to both
- GetLastPosition() and @c "GetValue().Length()" (but notice that the latter
- equality is not necessarily true for multiline edit controls which may
- use multiple new line characters).
-
- The following code snippet safely returns the character at the insertion
- point or the zero character if the point is at the end of the control.
-
- @code
- char GetCurrentChar(wxTextCtrl *tc) {
- if (tc->GetInsertionPoint() == tc->GetLastPosition())
- return '\0';
- return tc->GetValue[tc->GetInsertionPoint()];
- }
- @endcode
- */
- virtual long GetInsertionPoint() const;
-
- /**
- Returns the zero based index of the last position in the text control,
- which is equal to the number of characters in the control.
- */
- virtual wxTextPos GetLastPosition() const;
-
/**
Gets the length of the specified line, not including any trailing
newline character(s).
/**
Returns the number of lines in the text control buffer.
+ The returned number is the number of logical lines, i.e. just the count
+ of the number of newline characters in the control + 1, for wxGTK and
+ wxOSX/Cocoa ports while it is the number of physical lines, i.e. the
+ count of lines actually shown in the control, in wxMSW and wxOSX/Carbon.
+ Because of this discrepancy, it is not recommended to use this function.
+
@remarks
Note that even empty text controls have one line (where the
insertion point 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.
- 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.
*/
virtual int GetNumberOfLines() const;
- /**
- Returns the string containing the text starting in the positions
- @a from and up to @a to in the control.
-
- The positions must have been returned by another wxTextCtrl method.
- Please note that the positions in a multiline wxTextCtrl do @b not
- correspond to the indices in the string returned by GetValue() because
- of the different new line representations (@c CR or @c CR LF) and so
- this method should be used to obtain the correct results instead of
- extracting parts of the entire value. It may also be more efficient,
- especially if the control contains a lot of data.
- */
- virtual wxString GetRange(long from, long to) const;
-
- /**
- Gets the current selection span.
-
- If the returned values are equal, there was no selection. Please note
- that the indices returned may be used with the other wxTextCtrl methods
- but don't necessarily represent the correct indices into the string
- returned by GetValue() for multiline controls under Windows (at least,)
- you should use GetStringSelection() to get the selected text.
-
- @param from
- The returned first position.
- @param to
- The returned last position.
- */
- virtual void GetSelection(long* from, long* to) const;
-
- /**
- Gets the text currently selected in the control.
-
- If there is no selection, the returned string is empty.
- */
- virtual wxString GetStringSelection() const;
-
/**
Returns the style at this position in the text control.
*/
virtual bool GetStyle(long position, wxTextAttr& style);
- /**
- Gets the contents of the control.
-
- Notice that for a multiline text control, the lines will be separated
- by (Unix-style) @c \\n characters, even under Windows where they are
- separated by a @c \\r\\n sequence in the native control.
- */
- virtual wxString GetValue() const;
-
+ //@{
/**
This function finds the character at the specified position expressed
in pixels.
+ The two overloads of this method allow to find either the position of
+ the character, as an index into the text control contents, or its row
+ and column.
+
If the return code is not @c wxTE_HT_UNKNOWN the row and column of the
- character closest to this position are returned in the @a col and @a
- row parameters (unless the pointers are @NULL which is allowed).
- Please note that this function is currently only implemented in wxUniv, wxMSW
- and wxGTK2 ports.
+ character closest to this position are returned, otherwise the output
+ parameters are not modified.
+
+ Please note that this function is currently only implemented in wxUniv,
+ wxMSW and wxGTK2 ports and always returns @c wxTE_HT_UNKNOWN in the
+ other ports.
+
+ @beginWxPerlOnly
+ In wxPerl this function takes only the @a pt argument and
+ returns a 3-element list (result, col, row).
+ @endWxPerlOnly
+
+ @param pt
+ The position of the point to check, in window device coordinates.
+ @param col
+ Receives the column of the character at the given position. May be
+ @NULL.
+ @param row
+ Receives the row of the character at the given position. May be
+ @NULL.
+ @param pos
+ Receives the position of the character at the given position. May
+ be @NULL.
@see PositionToXY(), XYToPosition()
*/
+ wxTextCtrlHitTestResult HitTest(const wxPoint& pt, long *pos) const;
wxTextCtrlHitTestResult HitTest(const wxPoint& pt,
- wxTextCoord col,
- wxTextCoord row) const;
-
- /**
- Returns @true if the controls contents may be edited by user (note that
- it always can be changed by the program).
-
- In other words, this functions returns @true if the control hasn't been
- put in read-only mode by a previous call to SetEditable().
- */
- virtual bool IsEditable() const;
-
- /**
- Returns @true if the control is currently empty.
-
- This is the same as @c GetValue().empty() but can be much more
- efficient for the multiline controls containing big amounts of text.
-
- @since 2.7.1
- */
- virtual bool IsEmpty() const;
+ wxTextCoord *col,
+ wxTextCoord *row) const;
+ //@}
/**
Returns @true if the text has been modified by user.
*/
void OnDropFiles(wxDropFilesEvent& event);
- /**
- Pastes text from the clipboard to the text item.
- */
- virtual void Paste();
-
/**
Converts given position to a zero-based column, line number pair.
@true on success, @false on failure (most likely due to a too large
position parameter).
+ @beginWxPerlOnly
+ In wxPerl this function takes only the @a pos argument and
+ returns a 2-element list (x, y).
+ @endWxPerlOnly
+
@see XYToPosition()
*/
virtual bool PositionToXY(long pos, long* x, long* y) const;
/**
- If there is a redo facility and the last operation can be redone,
- redoes the last operation.
-
- Does nothing if there is no redo facility.
- */
- virtual void Redo();
-
- /**
- Removes the text starting at the first given position up to
- (but not including) the character at the last position.
+ Converts given text position to client coordinates in pixels.
- This function puts the current insertion point position at @a to as a
- side effect.
+ This function allows to find where is the character at the given
+ position displayed in the text control.
- @param from
- The first position.
- @param to
- The last position.
- */
- virtual void Remove(long from, long to);
+ @onlyfor{wxmsw,wxgtk}. Additionally, wxGTK only implements this method
+ for multiline controls and ::wxDefaultPosition is always returned for
+ the single line ones.
- /**
- Replaces the text starting at the first position up to
- (but not including) the character at the last position with the given text.
+ @param pos
+ Text position in 0 to GetLastPosition() range (inclusive).
+ @return
+ On success returns a wxPoint which contains client coordinates for
+ the given position in pixels, otherwise returns ::wxDefaultPosition.
- This function puts the current insertion point position at @a to as a
- side effect.
+ @since 2.9.3
- @param from
- The first position.
- @param to
- The last position.
- @param value
- The value to replace the existing text with.
+ @see XYToPosition(), PositionToXY()
*/
- virtual void Replace(long from, long to, const wxString& value);
+ wxPoint PositionToCoords(long pos) const;
/**
Saves the contents of the control in a text file.
*/
virtual bool SetDefaultStyle(const wxTextAttr& style);
- /**
- Makes the text item editable or read-only, overriding the
- @b wxTE_READONLY flag.
-
- @param editable
- If @true, the control is editable. If @false, the control is
- read-only.
-
- @see IsEditable()
- */
- virtual void SetEditable(bool editable);
-
- /**
- Sets the insertion point at the given position.
-
- @param pos
- Position to set, in the range from 0 to GetLastPosition() inclusive.
- */
- virtual void SetInsertionPoint(long pos);
-
- /**
- Sets the insertion point at the end of the text control.
-
- This is equivalent to calling wxTextCtrl::SetInsertionPoint() with
- wxTextCtrl::GetLastPosition() argument.
- */
- virtual void SetInsertionPointEnd();
-
- /**
- 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 @a len not
- counting the terminating @c NUL character.
-
- If @a 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).
- If the user tries to enter more characters into the text control when it
- already is filled up to the maximal length, a @c wxEVT_COMMAND_TEXT_MAXLEN
- event is sent to notify the program about it (giving it the possibility
- to show an explanatory message, for example) and the extra input is discarded.
-
- Note that in wxGTK this function may only be used with single line text controls.
- */
- virtual void SetMaxLength(unsigned long len);
-
/**
Marks the control as being modified by the user or not.
*/
void SetModified(bool modified);
- /**
- 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.
-
- Notice that the insertion point will be moved to @a from by this
- function.
-
- @param from
- The first position.
- @param to
- The last position.
-
- @see SelectAll()
- */
- virtual void SetSelection(long from, long to);
-
- /**
- Selects all text in the control.
-
- @see SetSelection()
- */
- virtual void SelectAll();
-
/**
Changes the style of the given range.
*/
virtual bool SetStyle(long start, long end, const wxTextAttr& style);
- /**
- Sets the new text control value.
-
- It also marks the control as not-modified which means that IsModified()
- would return @false immediately after the call to SetValue().
-
- The insertion point is set to the start of the control (i.e. position
- 0) by this function.
-
- Note that, unlike most other functions changing the controls values,
- this function generates a @c wxEVT_COMMAND_TEXT_UPDATED event. To avoid
- this you can use ChangeValue() instead.
-
- @param value
- The new value to set. It may contain newline characters if the text
- control is multi-line.
- */
- virtual void SetValue(const wxString& value);
-
/**
Makes the line containing the given position visible.
*/
virtual void ShowPosition(long pos);
- /**
- If there is an undo facility and the last operation can be undone,
- undoes the last operation.
-
- Does nothing if there is no undo facility.
- */
- virtual void Undo();
-
- /**
- Writes the text into the text control at the current insertion position.
-
- @param text
- Text to write to the text control.
-
- @remarks
- Newlines in the text string are the only control characters
- allowed, and they will cause appropriate line breaks.
- See operator<<() and AppendText() for more convenient ways of
- writing to the window.
- After the write operation, the insertion point will be at the end
- of the inserted text, so subsequent write operations will be appended.
- To append text after the user may have interacted with the control,
- call wxTextCtrl::SetInsertionPointEnd() before writing.
- */
- virtual void WriteText(const wxString& text);
-
/**
Converts the given zero based column and line number to a position.
projects / wxWidgets.git / blobdiff