// Purpose: interface of wxTextAttr
// Author: wxWidgets team
// RCS-ID: $Id$
-// Licence: wxWindows license
+// Licence: wxWindows licence
/////////////////////////////////////////////////////////////////////////////
+
+/**
+ One of the following values can be passed to wxTextAttr::SetAlignment to determine paragraph alignment.
+*/
+enum wxTextAttrAlignment
+{
+ wxTEXT_ALIGNMENT_DEFAULT,
+ wxTEXT_ALIGNMENT_LEFT,
+ wxTEXT_ALIGNMENT_CENTRE,
+ wxTEXT_ALIGNMENT_CENTER = wxTEXT_ALIGNMENT_CENTRE,
+ wxTEXT_ALIGNMENT_RIGHT,
+
+ /** wxTEXT_ALIGNMENT_JUSTIFIED is unimplemented.
+ In future justification may be supported when printing or previewing, only. */
+ wxTEXT_ALIGNMENT_JUSTIFIED
+};
+
+/**
+ The following values are passed in a bitlist to wxTextAttr::SetFlags() to
+ determine what attributes will be considered when setting the attributes for a text control.
+*/
+enum wxTextAttrFlags
+{
+ wxTEXT_ATTR_TEXT_COLOUR = 0x00000001,
+ wxTEXT_ATTR_BACKGROUND_COLOUR = 0x00000002,
+
+ wxTEXT_ATTR_FONT_FACE = 0x00000004,
+ wxTEXT_ATTR_FONT_SIZE = 0x00000008,
+ wxTEXT_ATTR_FONT_WEIGHT = 0x00000010,
+ wxTEXT_ATTR_FONT_ITALIC = 0x00000020,
+ wxTEXT_ATTR_FONT_UNDERLINE = 0x00000040,
+ wxTEXT_ATTR_FONT_ENCODING = 0x02000000,
+ wxTEXT_ATTR_FONT_FAMILY = 0x04000000,
+
+ /**
+ 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_ALIGNMENT = 0x00000080,
+ wxTEXT_ATTR_LEFT_INDENT = 0x00000100,
+ wxTEXT_ATTR_RIGHT_INDENT = 0x00000200,
+ wxTEXT_ATTR_TABS = 0x00000400,
+ wxTEXT_ATTR_PARA_SPACING_AFTER = 0x00000800,
+ wxTEXT_ATTR_PARA_SPACING_BEFORE = 0x00001000,
+ wxTEXT_ATTR_LINE_SPACING = 0x00002000,
+ wxTEXT_ATTR_CHARACTER_STYLE_NAME = 0x00004000,
+ wxTEXT_ATTR_PARAGRAPH_STYLE_NAME = 0x00008000,
+ wxTEXT_ATTR_LIST_STYLE_NAME = 0x00010000,
+
+ wxTEXT_ATTR_BULLET_STYLE = 0x00020000,
+ wxTEXT_ATTR_BULLET_NUMBER = 0x00040000,
+ wxTEXT_ATTR_BULLET_TEXT = 0x00080000,
+ wxTEXT_ATTR_BULLET_NAME = 0x00100000,
+
+ /**
+ Defined as the combination of all @c wxTEXT_ATTR_BULLET_* values above.
+ */
+ wxTEXT_ATTR_BULLET = \
+ ( wxTEXT_ATTR_BULLET_STYLE | wxTEXT_ATTR_BULLET_NUMBER | wxTEXT_ATTR_BULLET_TEXT | \
+ wxTEXT_ATTR_BULLET_NAME ),
+
+ wxTEXT_ATTR_URL = 0x00200000,
+ wxTEXT_ATTR_PAGE_BREAK = 0x00400000,
+ wxTEXT_ATTR_EFFECTS = 0x00800000,
+ wxTEXT_ATTR_OUTLINE_LEVEL = 0x01000000,
+
+ /**
+ Combines the styles @c wxTEXT_ATTR_FONT, @c wxTEXT_ATTR_EFFECTS, @c wxTEXT_ATTR_BACKGROUND_COLOUR,
+ @c wxTEXT_ATTR_TEXT_COLOUR, @c wxTEXT_ATTR_CHARACTER_STYLE_NAME, @c wxTEXT_ATTR_URL.
+ */
+
+ wxTEXT_ATTR_CHARACTER = \
+ (wxTEXT_ATTR_FONT|wxTEXT_ATTR_EFFECTS| \
+ wxTEXT_ATTR_BACKGROUND_COLOUR|wxTEXT_ATTR_TEXT_COLOUR|wxTEXT_ATTR_CHARACTER_STYLE_NAME|wxTEXT_ATTR_URL),
+
+ /**
+ Combines all the styles regarding text paragraphs.
+ */
+ wxTEXT_ATTR_PARAGRAPH = \
+ (wxTEXT_ATTR_ALIGNMENT|wxTEXT_ATTR_LEFT_INDENT|wxTEXT_ATTR_RIGHT_INDENT|wxTEXT_ATTR_TABS|\
+ wxTEXT_ATTR_PARA_SPACING_BEFORE|wxTEXT_ATTR_PARA_SPACING_AFTER|wxTEXT_ATTR_LINE_SPACING|\
+ wxTEXT_ATTR_BULLET|wxTEXT_ATTR_PARAGRAPH_STYLE_NAME|wxTEXT_ATTR_LIST_STYLE_NAME|wxTEXT_ATTR_OUTLINE_LEVEL),
+
+ /**
+ Combines all previous values.
+ */
+ wxTEXT_ATTR_ALL = (wxTEXT_ATTR_CHARACTER|wxTEXT_ATTR_PARAGRAPH)
+};
+
+/**
+ Styles for wxTextAttr::SetBulletStyle. They can be combined together as a bitlist.
+*/
+enum wxTextAttrBulletStyle
+{
+ wxTEXT_ATTR_BULLET_STYLE_NONE = 0x00000000,
+ wxTEXT_ATTR_BULLET_STYLE_ARABIC = 0x00000001,
+ wxTEXT_ATTR_BULLET_STYLE_LETTERS_UPPER = 0x00000002,
+ wxTEXT_ATTR_BULLET_STYLE_LETTERS_LOWER = 0x00000004,
+ wxTEXT_ATTR_BULLET_STYLE_ROMAN_UPPER = 0x00000008,
+ wxTEXT_ATTR_BULLET_STYLE_ROMAN_LOWER = 0x00000010,
+ wxTEXT_ATTR_BULLET_STYLE_SYMBOL = 0x00000020,
+
+ /** wxTEXT_ATTR_BULLET_STYLE_BITMAP is unimplemented. */
+ wxTEXT_ATTR_BULLET_STYLE_BITMAP = 0x00000040,
+ wxTEXT_ATTR_BULLET_STYLE_PARENTHESES = 0x00000080,
+ wxTEXT_ATTR_BULLET_STYLE_PERIOD = 0x00000100,
+ wxTEXT_ATTR_BULLET_STYLE_STANDARD = 0x00000200,
+ wxTEXT_ATTR_BULLET_STYLE_RIGHT_PARENTHESIS = 0x00000400,
+ wxTEXT_ATTR_BULLET_STYLE_OUTLINE = 0x00000800,
+
+ wxTEXT_ATTR_BULLET_STYLE_ALIGN_LEFT = 0x00000000,
+ wxTEXT_ATTR_BULLET_STYLE_ALIGN_RIGHT = 0x00001000,
+ wxTEXT_ATTR_BULLET_STYLE_ALIGN_CENTRE = 0x00002000
+};
+
+/**
+ 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.
+*/
+enum wxTextAttrEffects
+{
+ wxTEXT_ATTR_EFFECT_NONE = 0x00000000,
+ wxTEXT_ATTR_EFFECT_CAPITALS = 0x00000001,
+ wxTEXT_ATTR_EFFECT_SMALL_CAPITALS = 0x00000002,
+ wxTEXT_ATTR_EFFECT_STRIKETHROUGH = 0x00000004,
+ wxTEXT_ATTR_EFFECT_DOUBLE_STRIKETHROUGH = 0x00000008,
+ wxTEXT_ATTR_EFFECT_SHADOW = 0x00000010,
+ wxTEXT_ATTR_EFFECT_EMBOSS = 0x00000020,
+ wxTEXT_ATTR_EFFECT_OUTLINE = 0x00000040,
+ wxTEXT_ATTR_EFFECT_ENGRAVE = 0x00000080,
+ wxTEXT_ATTR_EFFECT_SUPERSCRIPT = 0x00000100,
+ wxTEXT_ATTR_EFFECT_SUBSCRIPT = 0x00000200
+};
+
+/**
+ Convenience line spacing values; see wxTextAttr::SetLineSpacing().
+*/
+enum wxTextAttrLineSpacing
+{
+ wxTEXT_ATTR_LINE_SPACING_NORMAL = 10,
+ wxTEXT_ATTR_LINE_SPACING_HALF = 15,
+ wxTEXT_ATTR_LINE_SPACING_TWICE = 20
+};
+
+
+/**
+ Describes the possible return values of wxTextCtrl::HitTest().
+
+ The element names correspond to the relationship between the point asked
+ for and the character returned, e.g. @c wxTE_HT_BEFORE means that the point
+ is before (leftward or upward) it and so on.
+ */
+enum wxTextCtrlHitTestResult
+{
+ /// Indicates that wxTextCtrl::HitTest() is not implemented on this
+ /// platform.
+ wxTE_HT_UNKNOWN = -2,
+
+ /// The point is before the character returned.
+ wxTE_HT_BEFORE,
+
+ /// The point is directly on the character returned.
+ wxTE_HT_ON_TEXT,
+
+ /// The point is below the last line of the control.
+ wxTE_HT_BELOW,
+
+ /// The point is beyond the end of line containing the character returned.
+ wxTE_HT_BEYOND
+};
+
+
/**
@class wxTextAttr
for a range of text in a wxTextCtrl or wxRichTextCtrl.
When setting up a wxTextAttr object, pass a bitlist mask to
- wxTextAttr::SetFlags to indicate which style elements should be changed. As
- a convenience, when you call a setter such as SetFont, the relevant bit
+ wxTextAttr::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.
@library{wxcore}
const wxTextAttr* compareWith = NULL);
/**
- Creates a font from the font attributes.
+ Copies all defined/valid properties from overlay to current object.
*/
- wxFont CreateFont() const;
+ void Merge(const wxTextAttr& overlay);
+
+ /**
+ Creates a new @c wxTextAttr which is a merge of @a base and @a overlay.
+
+ Properties defined in @a overlay take precedence over those in @a base.
+ Properties undefined/invalid in both are undefined in the result.
+ */
+ static wxTextAttr Merge(const wxTextAttr& base,
+ const wxTextAttr& overlay);
+
+
+ /**
+ @name GetXXX functions
+ */
+
+ //@{
/**
Returns the alignment flags.
- See SetAlignment() for a list of available styles.
+ See ::wxTextAttrAlignment for a list of available styles.
*/
wxTextAttrAlignment GetAlignment() const;
/**
Returns the background colour.
*/
- const wxColour GetBackgroundColour() const;
+ const wxColour& GetBackgroundColour() const;
/**
- Returns a string containing the name of the font associated with the bullet
- symbol.
+ Returns a string containing the name of the font associated with the bullet symbol.
Only valid for attributes with wxTEXT_ATTR_BULLET_SYMBOL.
*/
- const wxString GetBulletFont() const;
+ const wxString& GetBulletFont() const;
/**
Returns the standard bullet name, applicable if the bullet style is
wxTEXT_ATTR_BULLET_STYLE_STANDARD.
+
Currently the following standard bullet names are supported:
- @c standard/circle
- @c standard/square
- @c standard/diamond
- @c standard/triangle
+ - @c standard/circle
+ - @c standard/square
+ - @c standard/diamond
+ - @c standard/triangle
+
+ @note
For wxRichTextCtrl users only: if you wish your rich text controls to support
- further bullet graphics, you can derive a
- class from wxRichTextRenderer or wxRichTextStdRenderer, override @c
- DrawStandardBullet and @c EnumerateStandardBulletNames, and
- set an instance of the class using wxRichTextBuffer::SetRenderer.
+ further bullet graphics, you can derive a class from wxRichTextRenderer or
+ wxRichTextStdRenderer, override @c DrawStandardBullet and @c EnumerateStandardBulletNames,
+ and set an instance of the class using wxRichTextBuffer::SetRenderer.
*/
- const wxString GetBulletName() const;
+ const wxString& GetBulletName() const;
/**
Returns the bullet number.
/**
Returns the bullet style.
- See SetBulletStyle() for a list of available styles.
+ See ::wxTextAttrBulletStyle for a list of available styles.
*/
int GetBulletStyle() const;
Returns the bullet text, which could be a symbol, or (for example) cached
outline text.
*/
- const wxString GetBulletText() const;
+ const wxString& GetBulletText() const;
/**
Returns the name of the character style.
*/
- const wxString GetCharacterStyleName() const;
+ const wxString& GetCharacterStyleName() const;
/**
Returns flags indicating which attributes are applicable.
/**
Creates and returns a font specified by the font attributes in the wxTextAttr
- object. Note that
- wxTextAttr does not store a wxFont object, so this is only a temporary font.
- For greater
- efficiency, access the font attributes directly.
+ object. Note that wxTextAttr does not store a wxFont object, so this is only
+ a temporary font.
+
+ For greater efficiency, access the font attributes directly.
*/
wxFont GetFont() const;
/**
Returns the font face name.
*/
- const wxString GetFontFaceName() const;
+ const wxString& GetFontFaceName() const;
+
+ /**
+ Returns the font family.
+ */
+ wxFontFamily GetFontFamily() const;
/**
Returns the font size in points.
/**
Returns the font style.
*/
- int GetFontStyle() const;
+ wxFontStyle GetFontStyle() const;
/**
Returns @true if the font is underlined.
/**
Returns the font weight.
*/
- int GetFontWeight() const;
+ wxFontWeight GetFontWeight() const;
/**
Returns the left indent in tenths of a millimetre.
long GetLeftSubIndent() const;
/**
- Returns the line spacing value, one of wxTEXT_ATTR_LINE_SPACING_NORMAL,
- wxTEXT_ATTR_LINE_SPACING_HALF, and wxTEXT_ATTR_LINE_SPACING_TWICE.
+ Returns the line spacing value, one of ::wxTextAttrLineSpacing values.
*/
int GetLineSpacing() const;
/**
Returns the name of the list style.
*/
- const wxString GetListStyleName() const;
+ const wxString& GetListStyleName() const;
/**
Returns the outline level.
*/
- bool GetOutlineLevel() const;
+ int GetOutlineLevel() const;
/**
Returns the space in tenths of a millimeter after the paragraph.
/**
Returns the name of the paragraph style.
*/
- const wxString GetParagraphStyleName() const;
+ const wxString& GetParagraphStyleName() const;
/**
Returns the right indent in tenths of a millimeter.
long GetRightIndent() const;
/**
- Returns an array of tab stops, each expressed in tenths of a millimeter. Each
- stop
- is measured from the left margin and therefore each value must be larger than
- the last.
+ Returns an array of tab stops, each expressed in tenths of a millimeter.
+
+ Each stop is measured from the left margin and therefore each value must
+ be larger than the last.
*/
- const wxArrayInt GetTabs() const;
+ const wxArrayInt& GetTabs() const;
/**
Returns the text foreground colour.
*/
- const wxColour GetTextColour() const;
+ const wxColour& GetTextColour() const;
/**
- Returns the text effect bits of interest. See SetFlags() for further
- information.
+ Returns the text effect bits of interest.
+ See SetFlags() for further information.
*/
int GetTextEffectFlags() const;
/**
- Returns the text effects, a bit list of styles. See SetTextEffects() for
- details.
+ Returns the text effects, a bit list of styles.
+ See SetTextEffects() for details.
*/
int GetTextEffects() const;
/**
- Returns the URL for the content. Content with wxTEXT_ATTR_URL style
- causes wxRichTextCtrl to show a hand cursor over it, and wxRichTextCtrl
- generates
- a wxTextUrlEvent when the content is clicked.
+ Returns the URL for the content.
+
+ Content with @a wxTEXT_ATTR_URL style causes wxRichTextCtrl to show a
+ hand cursor over it, and wxRichTextCtrl generates a wxTextUrlEvent
+ when the content is clicked.
*/
- const wxString GetURL() const;
+ const wxString& GetURL() const;
+
+ //@}
+
+
+
+ /**
+ @name HasXXX and IsXXX functions
+ */
+
+ //@{
/**
Returns @true if the attribute object specifies alignment.
*/
bool HasFontFaceName() const;
+ /**
+ Returns @true if the attribute object specifies a font family.
+ */
+ bool HasFontFamily() const;
+
/**
Returns @true if the attribute object specifies italic style.
*/
*/
bool IsParagraphStyle() const;
- //@{
- /**
- Creates a new @c wxTextAttr which is a merge of @a base and
- @a overlay. Properties defined in @a overlay take precedence over those
- in @a base. Properties undefined/invalid in both are undefined in the
- result.
- */
- void Merge(const wxTextAttr& overlay);
- static wxTextAttr Merge(const wxTextAttr& base,
- const wxTextAttr& overlay);
//@}
+
+ /**
+ @name SetXXX functions
+ */
+
+ //@{
+
/**
- Sets the paragraph alignment. These are the possible values for @a alignment:
+ Sets the paragraph alignment. See ::wxTextAttrAlignment enumeration values.
- Of these, wxTEXT_ALIGNMENT_JUSTIFIED is unimplemented. In future justification
- may be supported
- when printing or previewing, only.
+ Of these, wxTEXT_ALIGNMENT_JUSTIFIED is unimplemented.
+ In future justification may be supported when printing or previewing, only.
*/
void SetAlignment(wxTextAttrAlignment alignment);
/**
Sets the standard bullet name, applicable if the bullet style is
wxTEXT_ATTR_BULLET_STYLE_STANDARD.
- See GetBulletName() for a list
- of supported names, and how to expand the range of supported types.
+
+ See GetBulletName() for a list of supported names, and how
+ to expand the range of supported types.
*/
void SetBulletName(const wxString& name);
void SetBulletNumber(int n);
/**
- Sets the bullet style. The following styles can be passed:
+ Sets the bullet style.
- Currently wxTEXT_ATTR_BULLET_STYLE_BITMAP is not supported.
+ The ::wxTextAttrBulletStyle enumeration values are all supported,
+ except for wxTEXT_ATTR_BULLET_STYLE_BITMAP.
*/
void SetBulletStyle(int style);
/**
- Sets the bullet text, which could be a symbol, or (for example) cached outline
- text.
+ Sets the bullet text, which could be a symbol, or (for example) cached
+ outline text.
*/
- void SetBulletText(const wxString text);
+ void SetBulletText(const wxString& text);
/**
Sets the character style name.
void SetCharacterStyleName(const wxString& name);
/**
- Sets the flags determining which styles are being specified. The following
- flags can be passed in a bitlist:
+ Sets the flags determining which styles are being specified.
+ The ::wxTextAttrFlags values can be passed in a bitlist.
*/
void SetFlags(long flags);
/**
- Sets the attributes for the given font. Note that wxTextAttr does not store an
- actual wxFont object.
+ Sets the attributes for the given font.
+ Note that wxTextAttr does not store an actual wxFont object.
*/
- void SetFont(const wxFont& font);
+ void SetFont(const wxFont& font, int flags = wxTEXT_ATTR_FONT);
/**
Sets the font encoding.
void SetFontEncoding(wxFontEncoding encoding);
/**
- Sets the paragraph alignment.
+ Sets the font face name.
*/
void SetFontFaceName(const wxString& faceName);
+ /**
+ Sets the font family.
+ */
+ void SetFontFamily(wxFontFamily family);
+
/**
Sets the font size in points.
*/
/**
Sets the font style (normal, italic or slanted).
*/
- void SetFontStyle(int fontStyle);
+ void SetFontStyle(wxFontStyle fontStyle);
/**
Sets the font underlining.
/**
Sets the font weight.
*/
- void SetFontWeight(int fontWeight);
+ void SetFontWeight(wxFontWeight fontWeight);
/**
Sets the left indent and left subindent in tenths of a millimetre.
The sub-indent is an offset from the left of the paragraph, and is used for all
- but the
- first line in a paragraph. A positive value will cause the first line to appear
- to the left
+ but the first line in a paragraph.
+
+ A positive value will cause the first line to appear to the left
of the subsequent lines, and a negative value will cause the first line to be
- indented
- relative to the subsequent lines.
- wxRichTextBuffer uses indentation to render a bulleted item. The left indent is
- the distance between
- the margin and the bullet. The content of the paragraph, including the first
- line, starts
- at leftMargin + leftSubIndent. So the distance between the left edge of the
- bullet and the
+ indented relative to the subsequent lines.
+
+ wxRichTextBuffer uses indentation to render a bulleted item.
+ The left indent is the distance between the margin and the bullet.
+ The content of the paragraph, including the first line, starts
+ at leftMargin + leftSubIndent.
+ So the distance between the left edge of the bullet and the
left of the actual paragraph is leftSubIndent.
*/
void SetLeftIndent(int indent, int subIndent = 0);
/**
Sets the line spacing. @a spacing is a multiple, where 10 means single-spacing,
- 15 means 1.5 spacing, and 20 means double spacing. The following constants are
- defined for convenience:
+ 15 means 1.5 spacing, and 20 means double spacing.
+ The ::wxTextAttrLineSpacing values are defined for convenience.
*/
void SetLineSpacing(int spacing);
void SetListStyleName(const wxString& name);
/**
- Specifies the outline level. Zero represents normal text. At present, the
- outline level is
- not used, but may be used in future for determining list levels and for
- applications
- that need to store document structure information.
+ Specifies the outline level. Zero represents normal text.
+ At present, the outline level is not used, but may be used in future for
+ determining list levels and for applications that need to store document
+ structure information.
*/
void SetOutlineLevel(int level);
void SetTabs(const wxArrayInt& tabs);
/**
- Sets the text foreground colout.
+ Sets the text foreground colour.
*/
void SetTextColour(const wxColour& colText);
/**
- Sets the text effect bits of interest. You should also pass wxTEXT_ATTR_EFFECTS
- to SetFlags().
+ Sets the text effect bits of interest.
+
+ You should also pass wxTEXT_ATTR_EFFECTS to SetFlags().
See SetFlags() for further information.
*/
void SetTextEffectFlags(int flags);
/**
Sets the text effects, a bit list of styles.
- The following styles can be passed:
+ The ::wxTextAttrEffects enumeration values can be used.
Of these, only wxTEXT_ATTR_EFFECT_CAPITALS and wxTEXT_ATTR_EFFECT_STRIKETHROUGH
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 a line through text.
+ of the actual buffer text unchanged), and wxTEXT_ATTR_EFFECT_STRIKETHROUGH draws
+ a line through text.
+
To set effects, you should also pass wxTEXT_ATTR_EFFECTS to SetFlags(), and call
- SetTextEffectFlags() with the styles (taken from the
- above set) that you are interested in setting.
+ SetTextEffectFlags() with the styles (taken from the above set) that you
+ are interested in setting.
*/
void SetTextEffects(int effects);
/**
Sets the URL for the content. Sets the wxTEXT_ATTR_URL style; content with this
- style
- causes wxRichTextCtrl to show a hand cursor over it, and wxRichTextCtrl
- generates
- a wxTextUrlEvent when the content is clicked.
+ style causes wxRichTextCtrl to show a hand cursor over it, and wxRichTextCtrl
+ generates a wxTextUrlEvent when the content is clicked.
*/
void SetURL(const wxString& url);
+ //@}
+
+
/**
Assignment from a wxTextAttr object.
*/
void operator operator=(const wxTextAttr& attr);
};
-/**
- Describes the possible return values of wxTextCtrl::HitTest().
-
- The element names correspond to the relationship between the point asked
- for and the character returned, e.g. @c wxTE_HT_BEFORE means that the point
- is before (leftward or upward) it and so on.
- */
-enum wxTextCtrlHitTestResult
-{
- /// Indicates that wxTextCtrl::HitTest() is not implemented on this
- /// platform.
- wxTE_HT_UNKNOWN = -2,
-
- /// The point is before the character returned.
- wxTE_HT_BEFORE,
-
- /// The point is directly on the character returned.
- wxTE_HT_ON_TEXT,
-
- /// The point is below the last line of the control.
- wxTE_HT_BELOW,
-
- /// The point is beyond the end of line containing the character returned.
- wxTE_HT_BEYOND
-};
-
/**
@class wxTextCtrl
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}
capitalized.
@endStyleTable
+ Note that alignment styles (wxTE_LEFT, wxTE_CENTRE and wxTE_RIGHT) can be
+ changed dynamically after control creation on wxMSW and wxGTK. wxTE_READONLY,
+ wxTE_PASSWORD and wrapping styles can be dynamically changed under wxGTK but
+ not wxMSW. The other styles can be only set during control creation.
+
@section textctrl_text_format wxTextCtrl Text Format
wxID_REDO. The associated UI update events are also processed
automatically, when the control has the focus.
- To process input from a text control, use these event handler macros to
- direct input to member functions that take a wxCommandEvent argument.
-
- @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 SetValue() is called); see
- ChangeValue() for a function which does not send this event. This
- event is however not sent during the control creation.
+ 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)}
wxGTK2 only currently).
@event{EVT_TEXT_MAXLEN(id, func)}
This event is generated when the user tries to enter more text into the
- control than the limit set by SetMaxLength(), see its description.
+ control than the limit set by wxTextCtrl::SetMaxLength(), see its description.
@endEventTable
@library{wxcore}
@category{ctrl}
- <!-- @appearance{textctrl.png} -->
+ @appearance{textctrl.png}
@see wxTextCtrl::Create, wxValidator
*/
-class wxTextCtrl : public wxControl
+class wxTextCtrl : public wxControl,
+ public wxTextEntry
{
public:
- //@{
/**
- Constructor, creating and showing a text control.
- @see Create()
+ Default ctor.
*/
- wxTextCtrl();
+ wxTextCtrl();
/**
Constructor, creating and showing a text control.
@param name
Window name.
- @remarks The horizontal scrollbar (wxHSCROLL style flag) will only be
+ @remarks
+ The horizontal scrollbar (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 so that the insertion point is always
- visible.
+ wrapped (but no newline character is inserted).
+ Single line controls don't have a horizontal scrollbar, the text is
+ automatically scrolled so that the insertion point is always visible.
@see Create(), wxValidator
*/
wxTextCtrl(wxWindow* parent, wxWindowID id,
- const wxString& value = "",
+ const wxString& value = wxEmptyString,
const wxPoint& pos = wxDefaultPosition,
const wxSize& size = wxDefaultSize,
long style = 0,
const wxValidator& validator = wxDefaultValidator,
const wxString& name = wxTextCtrlNameStr);
- //@}
/**
Destructor, destroying the text control.
*/
- ~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()
- */
- 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()
- */
- 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()
- */
- bool AutoCompleteFileNames();
-
- /**
- Returns @true if the selection can be copied to the clipboard.
- */
- virtual bool CanCopy();
-
- /**
- Returns @true if the selection can be cut to the clipboard.
- */
- virtual bool CanCut();
-
- /**
- 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();
-
- /**
- Returns @true if there is a redo facility available and the last
- operation can be redone.
- */
- virtual bool CanRedo();
-
- /**
- Returns @true if there is an undo facility available and the last
- operation can be undone.
- */
- virtual bool CanUndo();
-
- /**
- Sets the text value and marks the control as not-modified (which means
- that IsModified() would return @false immediately after the call to
- SetValue).
-
- This functions does not generate the @c wxEVT_COMMAND_TEXT_UPDATED
- event but otherwise is identical to SetValue().
- See @ref overview_progevent "this topic" 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();
+ virtual ~wxTextCtrl();
/**
Creates the text control for two-step construction.
non-default constructor.
*/
bool Create(wxWindow* parent, wxWindowID id,
- const wxString& value = "",
+ const wxString& value = wxEmptyString,
const wxPoint& pos = wxDefaultPosition,
- const wxSize& size = wxDefaultSize,
- long style = 0,
+ const wxSize& size = wxDefaultSize, long style = 0,
const wxValidator& validator = wxDefaultValidator,
const wxString& name = wxTextCtrlNameStr);
Resets the internal modified flag as if the current changes had been
saved.
*/
- void DiscardEdits();
+ 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 handler previously by wxWidgets. Please note that this
- function doesn't currently work correctly for all keys under any
- platform but MSW.
+ The @a event object should be the same as the one passed to @c EVT_KEY_DOWN
+ handler previously by wxWidgets. Please note that this function doesn't
+ currently work correctly for all keys under any platform but MSW.
@return
- @true if the event resulted in a change to the control, @false
- otherwise.
+ @true if the event resulted in a change to the control, @false otherwise.
*/
- bool EmulateKeyPress(const wxKeyEvent& event);
+ virtual bool EmulateKeyPress(const wxKeyEvent& event);
/**
Returns the style currently used for the new text.
@see SetDefaultStyle()
*/
- 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 GetValue().length() (but notice that the latter
- equality is not necessarily true for multiline edit controls which may
- use multiple new line characters).
- */
- 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;
+ virtual const wxTextAttr& GetDefaultStyle() const;
/**
Gets the length of the specified line, not including any trailing
@return
The length of the line, or -1 if @a lineNo was invalid.
*/
- int GetLineLength(long lineNo) const;
+ virtual int GetLineLength(long lineNo) const;
/**
Returns the contents of a given line in the text control, not including
@return
The contents of the line.
*/
- wxString GetLineText(long lineNo) const;
+ virtual wxString GetLineText(long lineNo) const;
/**
Returns the number of lines in the text control buffer.
- @remarks Note that even empty text controls have one line (where the
- insertion point is), so GetNumberOfLines() never
- returns 0.
- */
- 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.
+ 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.
- @param from
- The returned first position.
- @param to
- The returned last position.
+ @remarks
+ Note that even empty text controls have one line (where the
+ insertion point is), so GetNumberOfLines() never returns 0.
*/
- 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();
+ virtual int GetNumberOfLines() const;
/**
Returns the style at this position in the text control.
@see SetStyle(), wxTextAttr
*/
- 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.
- */
- wxString GetValue() const;
+ virtual bool GetStyle(long position, wxTextAttr& style);
+ //@{
/**
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().
- */
- 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
- */
- bool IsEmpty() const;
+ wxTextCoord *col,
+ wxTextCoord *row) const;
+ //@}
/**
Returns @true if the text has been modified by user.
@see MarkDirty()
*/
- bool IsModified() const;
+ virtual bool IsModified() const;
/**
- Returns @true if this is a multi line edit control and @false
- otherwise.
+ Returns @true if this is a multi line edit control and @false otherwise.
@see IsSingleLine()
*/
bool IsMultiLine() const;
/**
- Returns @true if this is a single line edit control and @false
- otherwise.
+ Returns @true if this is a single line edit control and @false otherwise.
- @see @ref IsSingleLine() IsMultiLine
+ @see IsSingleLine(), IsMultiLine()
*/
bool IsSingleLine() const;
@see IsModified()
*/
- void MarkDirty();
+ virtual void MarkDirty();
/**
This event handler function implements default drag and drop behaviour,
*/
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()
*/
- bool PositionToXY(long pos, long* x, long* y) const;
+ 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.
+ Converts given text position to client coordinates in pixels.
- Does nothing if there is no redo facility.
- */
- virtual void Redo();
+ This function allows to find where is the character at the given
+ position displayed in the text control.
- /**
- Removes the text starting at the first given position up to (but not
- including) the character at the last position.
+ @onlyfor{wxmsw,wxgtk}. Additionally, wxGTK only implements this method
+ for multiline controls and ::wxDefaultPosition is always returned for
+ the single line ones.
- @param from
- The first position.
- @param to
- The last position.
- */
- virtual void Remove(long from, long to);
+ @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.
- /**
- Replaces the text starting at the first position up to (but not
- including) the character at the last position with the given text.
+ @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.
@return
@true if the operation was successful, @false otherwise.
*/
- bool SaveFile(const wxString& filename,
+ bool SaveFile(const wxString& filename = wxEmptyString,
int fileType = wxTEXT_TYPE_ANY);
/**
If either of the font, foreground, or background colour is not set in
@a style, the values of the previous default style are used for them.
If the previous default style didn't set them neither, the global font
- or colours of the text control itself are used as fall back. However if
- the @a style parameter is the default wxTextAttr, then the default
+ or colours of the text control itself are used as fall back.
+
+ However if the @a style parameter is the default wxTextAttr, then the default
style is just reset (instead of being combined with the new style which
wouldn't change it at all).
@see GetDefaultStyle()
*/
- 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(const bool editable);
-
- /**
- Sets the insertion point at the given position.
-
- @param pos
- Position to set.
- */
- 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);
+ virtual bool SetDefaultStyle(const wxTextAttr& style);
/**
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.
-
- @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.
@see GetStyle(), wxTextAttr
*/
- bool SetStyle(long start, long end, const wxTextAttr& style);
-
- /**
- Sets the text value and marks the control as not-modified (which means
- that IsModified() would return @false immediately after the call to
- SetValue).
-
- Note that 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);
+ virtual bool SetStyle(long start, long end, const wxTextAttr& style);
/**
Makes the line containing the given position visible.
@param pos
The position that should be visible.
*/
- 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 () and
- AppendText() for more convenient ways of writing to the window.
- */
- void WriteText(const wxString& text);
+ virtual void ShowPosition(long pos);
/**
Converts the given zero based column and line number to a position.
@return
The position value, or -1 if x or y was invalid.
*/
- long XYToPosition(long x, long y);
+ virtual long XYToPosition(long x, long y) const;
//@{
/**
This class can be used to (temporarily) redirect all output sent to a C++
ostream object to a wxTextCtrl instead.
- @note Some compilers and/or build configurations don't support multiply
- inheriting wxTextCtrl from @c std::streambuf in which
- case this class is not compiled in. You also must have @c wxUSE_STD_IOSTREAM
- option on (i.e. set to 1) in your setup.h to be able to use it. Under Unix,
- specify @c --enable-std_iostreams switch when running configure for this.
+ @note
+ Some compilers and/or build configurations don't support multiply
+ inheriting wxTextCtrl from @c std::streambuf in which case this class is
+ not compiled in.
+ You also must have @c wxUSE_STD_IOSTREAM option on (i.e. set to 1) in your
+ @c setup.h to be able to use it. Under Unix, specify @c --enable-std_iostreams
+ switch when running configure for this.
Example of usage:
@param ostr
The C++ stream to redirect, cout is used if it is @NULL
*/
- wxStreamToTextRedirector(wxTextCtrl text, ostream* ostr = NULL);
+ wxStreamToTextRedirector(wxTextCtrl *text, ostream* ostr);
/**
When a wxStreamToTextRedirector object is destroyed, the redirection is ended
projects / wxWidgets.git / blobdiff