Amebis/wxWidgets
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Update wxStyledTextCtrl documentation

Browse Source 
Table of contents is added to the documentation for wxSTC and the brief list of methods is broken into categories corresponding to this table. Documentation of several methods is rearranged and edited.

Closes #17803.
This commit is contained in:
New Pagodi
2017-02-20 08:32:39 +01:00
committed by Artur Wieczorek
parent 9035a65d17
commit 6bf083857f
7 changed files with 1012 additions and 298 deletions
Download Patch File Download Diff File Expand all files Collapse all files

435
interface/wx/stc/stc.h
View File

@@ -2767,6 +2767,20 @@
wxStyledTextCtrl is a 1 to 1 mapping of "raw" scintilla interface, whose
documentation can be found in the Scintilla website (http://www.scintilla.org/).
@section stc_index Index of the member groups
Links for quick access to the various categories of wxStyledTextCtrl functions:
- @ref_member_group{ctor, Constructors and related methods}
- @ref_member_group{scintilla_functions, Scintilla methods}
- @ref_member_group{additional_methods, Additional wxStyledTextCtrl methods}
- @ref_member_group{raw_variants , Raw variants}
- @ref_member_group{text_entry, Text entry methods}
- @ref_member_group{text_area, Text area methods}
@section event_list Events
@beginEventEmissionTable{wxStyledTextEvent}
@event{EVT_STC_AUTOCOMP_CANCELLED(id, fn)}
Process a @c wxEVT_STC_AUTOCOMP_CANCELLED event.
@@ -2854,6 +2868,11 @@ class wxStyledTextCtrl : public wxControl, public wxTextEntry
{
public:
// Ctor, etc
// ----------------------------------------------
///@member_group_name{ctor, Constructors and related methods}
//@{
/**
Ctor.
*/
@@ -2865,8 +2884,7 @@ public:
Default ctor.
*/
wxStyledTextCtrl();
/**
Destructor.
*/
@@ -2880,6 +2898,13 @@ public:
const wxSize& size = wxDefaultSize, long style = 0,
const wxString& name = wxSTCNameStr);
//@}
// Scintilla methods (generated by gen_iface.py)
// ----------------------------------------------
///@member_group_name{scintilla_functions, Scintilla methods}
//@{
// **** Generated methods {{{
@@ -3415,6 +3440,12 @@ public:
*/
int StyleGetWeight(int style) const;
/**
Set the character set of the font in a style.
Converts the Scintilla character set values to a wxFontEncoding.
*/
void StyleSetCharacterSet(int style, int characterSet);
/**
Set a style to be a hotspot or not.
*/
@@ -4018,6 +4049,11 @@ public:
*/
void HideSelection(bool hide);
/**
Retrieve the point in the window where a position is displayed.
*/
wxPoint PointFromPosition(int pos);
/**
Retrieve the line containing a position.
*/
@@ -6389,10 +6425,18 @@ public:
//}}}
//@}
// **** Manually declared methods
// Manually declared methods
// ----------------------------------------------
/**
@member_group_name{additional_methods, Additional wxStyledTextCtrl methods}
In addition to the standard Scintilla functions, wxStyledTextCtrl
includes the following functions to simplify some tasks.
*/
//@{
/**
Returns the line number of the line with the caret.
@@ -6414,21 +6458,17 @@ public:
*/
void StyleSetSpec(int styleNum, const wxString& spec);
/**
Get the font of a style.
*/
wxFont StyleGetFont(int style);
/**
Set style size, face, bold, italic, and underline attributes from
a wxFont's attributes.
*/
void StyleSetFont(int styleNum, wxFont& font);
/**
Set all font style attributes at once.
*/
@@ -6438,61 +6478,41 @@ public:
bool underline,
wxFontEncoding encoding=wxFONTENCODING_DEFAULT);
/**
Set the character set of the font in a style. Converts the Scintilla
character set values to a wxFontEncoding.
*/
void StyleSetCharacterSet(int style, int characterSet);
/**
Set the font encoding to be used by a style.
*/
void StyleSetFontEncoding(int style, wxFontEncoding encoding);
/**
Perform one of the operations defined by the wxSTC_CMD_* constants.
*/
void CmdKeyExecute(int cmd);
/**
Set the left and right margin in the edit area, measured in pixels.
*/
void SetMargins(int left, int right);
/**
Retrieve the point in the window where a position is displayed.
*/
wxPoint PointFromPosition(int pos);
/**
Scroll enough to make the given line visible
*/
void ScrollToLine(int line);
/**
Scroll enough to make the given column visible
*/
void ScrollToColumn(int column);
/**
Send a message to Scintilla
Scintilla API call.
*/
wxIntPtr SendMsg(int msg, wxUIntPtr wp=0, wxIntPtr lp=0) const;
/**
Set the vertical scrollbar to use instead of the ont that's built-in.
*/
void SetVScrollBar(wxScrollBar* bar);
/**
Set the horizontal scrollbar to use instead of the ont that's built-in.
*/
@@ -6538,11 +6558,36 @@ public:
*/
bool DoDropText(long x, long y, const wxString& data);
/**
Specify whether anti-aliased fonts should be used.
This will have no effect on some platforms, but on some (wxMac for
example) can greatly improve performance.
*/
void SetUseAntiAliasing(bool useAA);
/**
Returns the current UseAntiAliasing setting.
*/
bool GetUseAntiAliasing();
/**
Clear annotations from the given line.
*/
void AnnotationClearLine(int line);
//@}
// Raw versions
// ----------------------------------------------
/**
@member_group_name{raw_variants , Raw variants }
These methods allow data to be sent to or received from the control
using character buffers instead of using a wxString.
*/
//@{
/**
Add text to the document at current position.
@@ -6572,6 +6617,8 @@ public:
/**
Retrieve the target text.
@since 3.1.1
*/
wxCharBuffer GetTargetTextRaw();
@@ -6595,53 +6642,373 @@ public:
*/
void AppendTextRaw(const char* text, int length=-1);
static wxVersionInfo GetLibraryVersionInfo();
//@}
// wxTextEntryBase pure virtual methods
// ----------------------------------------------
///@member_group_name{text_entry, Text entry methods}
//@{
/**
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);
/**
Removes the text starting at the first given position up to
(but not including) the character at the last position.
This function puts the current insertion point position at @a to as a
side effect.
@param from
The first position.
@param to
The last position.
*/
virtual void Remove(long from, long to);
/**
Replaces the text starting at the first position up to
(but not including) the character at the last position with the given text.
This function puts the current insertion point position at @a to as a
side effect.
@param from
The first position.
@param to
The last position.
@param value
The value to replace the existing text with.
*/
virtual void Replace(long from, long to, const wxString& text);
/**
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);
/**
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
GetLastPosition().
Notice that insertion position is, in general, different from the index
of the character the cursor position at in the string returned by
GetValue(). While this is always the case for the single line controls,
multi-line controls can use two characters @c "\\r\\n" as line
separator (this is notably the case under MSW) meaning that indices in
the control and its string value are offset by 1 for every line.
Hence to correctly get the character at the current cursor position,
taking into account that there can be none if the cursor is at the end
of the string, you could do the following:
@code
wxString GetCurrentChar(wxTextCtrl *tc)
{
long pos = tc->GetInsertionPoint();
if ( pos == tc->GetLastPosition() )
return wxString();
return tc->GetRange(pos, pos + 1);
}
@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 long GetLastPosition() const;
/**
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);
/**
Deselects selected text in the control.
@since 2.9.5
*/
virtual void SelectNone();
/**
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.
@beginWxPerlOnly
In wxPerl this method takes no parameters and returns a
2-element list (from, to).
@endWxPerlOnly
*/
virtual void GetSelection(long *from, long *to) 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;
/**
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);
//@}
// wxTextAreaBase pure virtual methods
// ---------------------------------------------
///@member_group_name{text_area, Text area methods}
//@{
/**
Gets the length of the specified line, not including any trailing
newline character(s).
@param lineNo
Line number (starting from zero).
@return
The length of the line, or -1 if @a lineNo was invalid.
*/
virtual int GetLineLength(long n) const;
/**
Returns the contents of a given line in the text control, not including
any trailing newline character(s).
@param lineNo
The line number, starting from zero.
@return
The contents of the line.
*/
virtual wxString GetLineText(long n) const;
/**
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.
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.
*/
virtual int GetNumberOfLines() const;
/**
Returns @true if the text has been modified by user.
Note that calling SetValue() doesn't make the control modified.
@see MarkDirty()
*/
virtual bool IsModified() const;
/**
Mark text as modified (dirty).
@see IsModified()
*/
virtual void MarkDirty();
/**
Resets the internal modified flag as if the current changes had been
saved.
*/
virtual void DiscardEdits();
/**
This method is inherited from wxTextAreaBase but is not implemented
in wxStyledTextCtrl.
*/
virtual bool SetStyle(long start, long end, const wxTextAttr& style);
/**
This method is inherited from wxTextAreaBase but is not implemented
in wxStyledTextCtrl.
*/
virtual bool GetStyle(long position, wxTextAttr& style);
/**
This method is inherited from wxTextAreaBase but is not implemented
in wxStyledTextCtrl.
*/
virtual bool SetDefaultStyle(const wxTextAttr& style);
/**
Converts the given zero based column and line number to a position.
@param x
The column number.
@param y
The line number.
@return
The position value, or -1 if x or y was invalid.
*/
virtual long XYToPosition(long x, long y) const;
/**
Converts given position to a zero-based column, line number pair.
@param pos
Position.
@param x
Receives zero based column number.
@param y
Receives zero based line number.
@return
@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;
/**
Makes the line containing the given position visible.
@param pos
The position that should be visible.
*/
virtual void ShowPosition(long pos);
/**
Finds the position of the character at the specified point.
If the return code is not @c wxTE_HT_UNKNOWN the row and column of the
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 pos
Receives the position of the character at the given position. May
be @NULL.
@see PositionToXY(), XYToPosition()
*/
virtual wxTextCtrlHitTestResult HitTest(const wxPoint& pt, long *pos) const;
/**
Finds the row and column of the character at the specified point.
If the return code is not @c wxTE_HT_UNKNOWN the row and column of the
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.
@see PositionToXY(), XYToPosition()
*/
virtual wxTextCtrlHitTestResult HitTest(const wxPoint& pt,
wxTextCoord *col,
wxTextCoord *row) const;
//@}
// VersionInfo
// ---------------------------------------------
/**
Returns the version of the Scintilla library used by this control.
*/
static wxVersionInfo GetLibraryVersionInfo();
};
//----------------------------------------------------------------------
@@ -7673,3 +8040,5 @@ const wxEventType wxEVT_STC_AUTOCOMP_CHAR_DELETED;
const wxEventType wxEVT_STC_HOTSPOT_RELEASE_CLICK;
const wxEventType wxEVT_STC_CLIPBOARD_COPY;
const wxEventType wxEVT_STC_CLIPBOARD_PASTE;
const wxEventType wxEVT_STC_AUTOCOMP_COMPLETED;
const wxEventType wxEVT_STC_MARGIN_RIGHT_CLICK;