[wxPython] wxSTC docs: second draft on the web

Hi,

You may view the second draft of the wxSTC documentation at:
    http://personalpages.tds.net/~edream/out2.htm

A great deal of work has gone into this second draft to improve the
accuracy, organization and the style of the documentation. I believe
that all and only the public methods in stc.h appear in the
documentation, and that the names and arguments of all routines now
match those in stc.h. Naturally, mistakes may still be lurking. Any
comments and corrections will be appreciated. It is now relatively
straightforward to incorporate changes.

I have tried to avoid guessing when writing the documentation. You will
notice questions preceded by ??? throughout. In the next several days
I'll be asking about these questions here.

Documentation for wxStyledTextEvent is still in dummy form. It may be a
while before a first draft is ready.

Edward

P.S. In the body of the documentation, your browser should show argument
names in a typewriter font. If not, the documentation may look
considerably better in another browser.

···

--------------------------------------------------------------------
Edward K. Ream email: edream@tds.net
Leo: Literate Editor with Outlines
Leo: http://personalpages.tds.net/~edream/front.html
--------------------------------------------------------------------

Edward K. Ream:

I have tried to avoid guessing when writing the documentation. You will
notice questions preceded by ??? throughout. In the next several days
I'll be asking about these questions here.

   I can answer from Scintilla's point of view but wxSTC may be treating
these differently.

AddStyledText: the text argument is a sequence of cells, each containing one
character and one style byte.
AddText: Inserts text at the caret position, InsertText inserts at the
position argument. AddText uses an argument for the length of the text to
insert whereas InsertText inserts up to a \0. Therefore AddText can insert
\0 bytes.
BraceMatch: the maxRestyle is currently unused and should be 0.
ChangePosition: wxSTC feature, not in Scintilla.
FormatRange: doDraw indicates whether the text is to be drawn or only
measured. draw is where to draw if drawing. target is a final destination to
measure text for. This differentiation is used to implement print preview
where the preview is being drawn on screen but as if it was going to the
printer.
GetFoldExpanded: correct.
GetFoldParent: correct.
GetHideSelection: correct.
GetLastChild: level is the fold level that should be assumed for the line,
or -1 if the level should be retrieved. This is used when performing folding
transformations where a line may already have changed its fold level before
needing to find its children.
GetLineLengthAtPos: correct.
GetLineVisible: whether it is marked as visible not whether it is on-screen.
While folding is the common way to achieve invisible lines, any line may be
made invisible.
GetRect: deprecated in Scintilla as the platform should have ways to
retrieve this information.
GetSelection: If to or from are NULL then they are not set.
GetSelectionType: Deprecated - returns 0.
GetStyledTextRange: Styled text is a sequence of cells as desribed above.
HideSelection: Hide the selection means to not display the selection in a
distinguishable manner from other text.
SearchNext: -1 is returned when the text can not be found. In Scintilla
there is a defined constant INVALID_POSITION=-1 which is used to indicate a
failure position.

SetCaretPolicy: A mess:
# Show caret within N lines of edge when it's scrolled to view
# If CARET_SLOP not set then centre caret on screen when it's
# scrolled to view
val CARET_SLOP=0x01
# Value not used
val CARET_CENTER=0x02
# If CARET_SLOP also set then reposition whenever outside slop border
# If CARET_SLOP not set then recentre even when visible
val CARET_STRICT=0x04
# If CARET_XEVEN set then both left and right margins are given equal weight
# rather than favouring left following behaviour.
val CARET_XEVEN=0x08

SetKeyWords: A language such as HTML may use several sets of keywords
including valid tags, valid attributes, and keywords for embedded
JavaScript.
SetUndoCollection: this is now a boolean in Scintilla - true means to store
undo information. The enumeration was for a third state which turned out not
to be useful.

   Neil