Opened 3 years ago

Closed 3 years ago

#17800 closed enhancement (fixed)

Documentation additions for wxStyledTextEvent

Reported by: NewPagodi Owned by: Artur Wieczorek <artwik@…>
Priority: normal Milestone: 3.1.1
Component: wxStyledText Version: dev-latest
Keywords: documentation Cc:
Blocked By: Blocking:
Patch: yes

Description

As mentioned in the discussion for #17680, it's probably best to break that patch into smaller pieces. This is the first piece and completes the "Todo" items for wxStyledTextEvent, adds a section describing what each of the event types do, and documents the event methods. A preview of the documentation that results from this patch can be seen here:

[​https://newpagodi.github.io/tempstcdocs/classwx_styled_text_event4.html]

3 comments:

1) I've reordered the list of event types alphabetically. The previous ordering of the list seems to be mostly based on the order in the scintilla documentation. But it's such a long list, and most people probably don't care about that order. I think it's more helpful to list the events this way, but if it's a problem I can change it back.

2) I was wondering since most of the setters aren't supposed to be called in used code, maybe those items should be removed from the documentation. The exceptions are SetPosition which is used by wxEVT_STC_DO_DROP, SetDragResult which is used by wxEVT_STC_DRAG_OVER, and SetDragFlags which is used by wxEVT_STC_START_DRAG.

3) it looks like in previous commit for wxSTC issues (#17688), a few lines like

wxEVT_STC_KEY, // deprecated

were added to stc.h. When I rerun gen_iface.py, those changes are undone. So, I've also added 2 small changes to stc.h.in to make sure those changes are preserved.

Attachments (1)

stcevntdocs.patch download (87.2 KB) - added by NewPagodi 3 years ago.

Download all attachments as: .zip

Change History (5)

comment:1 Changed 3 years ago by vadz

  • Milestone set to 3.1.1
  • Status changed from new to confirmed

I'm not applying this right now because I think Artur might want to look at this (especially 3), but this is definitely a big improvement and should be integrated, thank you!

comment:2 in reply to: ↑ description Changed 3 years ago by awi

Indeed, documentation looks better now.
Only one minor remark: I think Scintilla label should be capitalized in the documentation because this is its original spelling.

3) it looks like in previous commit for wxSTC issues (#17688), a few lines like

wxEVT_STC_KEY, // deprecated

were added to stc.h.

Thanks for noticing this discrepancy between stc.h and stc.h.in. I added these comments to the code which is active if SWIG is defined to give someone a chance to stop using these dead events. It would be better just to generate a compiler warning about deprecation but I don't know how to deprecate individual enum values in an elegant and portable way.

Changed 3 years ago by NewPagodi

comment:3 Changed 3 years ago by NewPagodi

I've updated the patch to fix the case for 'Scintilla'.

comment:4 Changed 3 years ago by Artur Wieczorek <artwik@…>

  • Owner set to Artur Wieczorek <artwik@…>
  • Resolution set to fixed
  • Status changed from confirmed to closed

In 7a88b0588270cab7de6bfc063f18a0b608498bbd/git-wxWidgets:

Fill gaps in documentation of wxSTC events

Completed "Todo" items for wxStyledTextEvent, added a section describing what each of the event types do, documented the event methods.

Closes #17800.

Note: See TracTickets for help on using tickets.