Thanks for your comments, I will look over my patch soon.

Part calls them like this:

I suggested to use KActionMenu in D21622 (although not really focussed on that patch). Turned out that KActionMenu can not access already constructed toolbar buttons, so that approach is not possible.

In D21195#477747, @ngraham wrote:

OK, got to test this out. It works well! I would recommend making the toolbar button show the text of the actual color change mode that's currently active, much like how the selection tools toolbar button currently does. Otherwise you won't know which mode it will invoke.

Oh, does someone know any intended purpose division between setupActions(), setupViewerActions(), and setupBaseActions()?

Documenting these classes wasn’t really difficult, they already have helpful inline comments and member names.

Is it intended to fix Bug 398108 - Annotation toolbar works only in Browse mode, not in e. g. Text Selection mode?

In T10997#187755, @mglb wrote:

[...] indeterminate is used in one place - tree views. And everything there is a problem:

• square - mentioned before, it is used right now, so would be confusing for current users
• horizontal line - might be confused with a button for folding tree
• colored/transparent check mark - color-only differences are bad
• ellipsis - "open..."
• ⠴ - conceived while writing this note, intended meaning: "not all"/"something missing"
  
  Any ideas?
  
  [...]
  
  Re check meaning around the world: "Check mark" meaning does not always apply to check boxes. E.g. teachers in Poland use ✓/✗ or ✓/― or +/- as "correct"/"wrong", but in tests, forms and voting cards ✗ is almost always placed in a square as the choice marker.
  
  [...]

In T10997#187703, @ngraham wrote:

We can't make everything configurable, and configurability is never a substitute for good default behavior. What if I want the letter Z or an Emoji in my checkbox? Should we go out of our way to support those too? Let's not bikeshed this too much and derail the task.

In T10997#187701, @ngraham wrote:

I think it makes much more sense to have this automatically set according to the locale (or language, or whatever makes the most sense) than making it user-configurable. Nobody would ever find it.

In T10997#187683, @ngraham wrote:

the current locale

By the way, this also affects the magnifier tool (Ctrl+6), which calls scrollPosIntoView() when dragged against or beyond the viewport edges.

Sorry for testing it so late, now that I’m working on PageView.

Couldn’t the whole class ToolAction be replaced by KActionMenu now?

+1 for using a checkmark instead of a sqare. (Although I like the animation of folding and unfolding the sqare.)
-1 for using ... for tristate/indeterminate. That looks like the checkbox will open a dialog (https://hig.kde.org/style/writing/labels.html?highlight=ellipsis). If looking fast, it even looks like a hamburger button, which will open a menu. At least, it looks more like a pushbutton than a checkbox.

In D21622#475197, @ngraham wrote:

clicking on the arrow on the right side of the button will open the pop-up and allow choosing another tool, which is a more common method of implementing the feature.

In D21635#475541, @ngraham wrote:

The current keyboard shortcuts aren't a problem if we don't re-arrange the items in the Selection Mode toolbar button.

In T10201#187374, @ngraham wrote:

So yes, we should and must consider "Pro" apps, but we cannot fix apps that are already have very problematic user interfaces.

In D15580#474457, @simgunz wrote:

In D15580#474436, @simgunz wrote:

Or: Why is this still PageViewToolBar? It is not anymore in the PageView?

I'll move it, added to TODO

Actually the code of the other toolbar (Browse, Zoom, Selection) is managed in the file pageview.cpp. In which file would you move the code of PageViewToolBar?

In T10201#186847, @davidhurka wrote:

In T10201#176718, @ndavis wrote:

In T10201#175063, @filipf wrote:

SierraBreezeEnhanced to the rescue again - what about different window buttons if the window is active or inactive?

Obviously this exact solution would be seen as copying macOS, but maybe just having circles or rings in the active window would help.

I suppose inactive windows could be set to not show the circle around the close button by default, but there should always be visible symbols.

The close button is good to find a window corner, even if the window is mostly hidden by other windows. I think it shouldn’t be circle-less when the window is inactive, that way a visual aid on the window geometry is lost.

Removed references to pages from methods.

In D15580#473824, @ngraham wrote:

Sticky-by-default would probably be okay as long as we can make it very clear how to un-select the tool. Probably implementing multiple methods would be good (hit esc key, left-click again on the tool, right-click anywhere, etc).

In D15580#473733, @ngraham wrote:

• I can't figure out what Pin Annotation actually does

If checked the current annotation tool is kept selected after use (as double-click does in the current Okular). Needs a better name/tooltip. Added to TODO.

Can't we just keep the old double-click behavior? I think that's good. Various other similar tools use a double-click to mean "activate this tool and then keep it active after you've used it once" so it's not a totally alien UI. Then we could keep the pin icon as an additional visual status indicator of whether the current tool is "sticky" or not.

Using double-click is probably used to some [how many?] Okular users, but others asked for something like a sticky button. An option to make selected actions sticky by default, without sticky button, would be perfect for me.
From other applications I know left-click: use the tool, right-click: stop using the tool. If there is no fallback tool (see below), the tool will be remembered for the next left click.

I will remove page sizes from member documentations and describe the coordinate system with a more abstract reference rectangle.

Sometimes I’m working on PageView, but I move it out of this patch because it’s less related than I thought. And this is enough stuff for a single patch for now...

How will you do what currently a double-click does? It should still be possible to do more than one annotation in one go.

In T8076#186894, @simgunz wrote:

In the current version of Okular, the numbers 1-9 select the annotation tools based on their order.

Good to know... They are not listed in Configure Shortcuts.

Probably some users are used to this configuration and we can recycle it. Either we assign the numbers 1-9 to select the implict tools or use them for the explict tools.

Then we should assign them to implicit tools similar to the existing configuration.

In T10034#186764, @davidhurka wrote:

I have just tried ScanTailor. It is useful to convert photographed documents to good looking PDFs.

4. Can you make screenshots of an application like FreeCAD, with its n = n + 1 toolbars?

Oh. I didn't know about it. Wow.

Don’t like that because it turns a huge area to an area without border. If another window covers the left part, it’s hard to see that this huge area is the tools area of FreeCAD, and not an empty view in the window behind FreeCAD.

In T8076#186872, @simgunz wrote:

• Add a combobox action with a list of favorite tools.

That means two clicks to change the tool. (Currently, often needs a double-click.)

• Add a 'star' button that adds the currently selected tool and settings to the list of favorite ones

I was actually thinking about a star icon. :)

• Keep the current settings dialog for configuring annotations, but use it only to configure favorite tools (reorder them, change the name and so on). Otherwise this could be tricky to do directly from the toolbar.

Probably the current “implicit” tool should be configurable trough the dialog too, so not all controls need to be in the toolbar, but the user does not need to make a favourite for a very special annotation he/she will use only once. (This is probably what you meant in the second section.)

• Not sure how to deal with the preview of the tool, my solution is to let the user give a meaningful name of the tool. Adding a small preview as an icon next to the Action can be a solution, but I think the preview is going to be too small. I would just add the breeze icon of the corresponding tool.

@jangmarker tried using the existing, configurable icons, and I think it looks ok. Depending on the used dpi, a scalable icon engine would be good for the side panel, but toolbar icons are usually a bit bigger.

In D21364#469241, @jangmarker wrote:

Now it looks like this:

A stamp looks like this:

I think we shouldn’t rely on the ability of the user to give meaningful names.

• Currenlty the state of each annotation tool is saved. If I click underline > highlight > underline the state of underline is restored to its previous value. When a favorite tool is selected it sets the status of the color, width, etc. buttons. The state of the previously selected tool:
  • is saved if the tool is different from the current one: e.g. was highlight, my favorite is underline, state of highlight saved
  • is lost if the tool is the same as the current one: e.g. was highlight, my favorite is highlight with different color, now the saved state of the highlight tool is the same as my selected favorite

Then I’d call them “implicit tools” and “explicit tools”. The tools which can be selected from the toolbar are associated to implicit tools. (I. e. one implicit tool for each Freehand, Stamp, Popup, Highlight,...) By clicking arround in the toolbar the user selects or configures one of them. By choosing a favourite he/she loads a preset into one of the implicit tools.

Then it’s time I want to ask this:

If there is a dedicated tool for dimensions, straight line annotations recognized as dimension should be movable by dragging the label. FreeCAD illustrates this, although a bit unintuitive: ;)

In T8076#141446, @simgunz wrote:

This is a first mockup of the annotation toolbar.

In T10201#186849, @GB_2 wrote:

In T10201#186847, @davidhurka wrote:

The close button is good to find a window corner, even if the window is mostly hidden by other windows. I think it shouldn’t be circle-less when the window is inactive, that way a visual aid on the window geometry is lost.

What about turning the filled circle into only a ring/circle outline?

In T10201#176718, @ndavis wrote:

In T10201#175063, @filipf wrote:

SierraBreezeEnhanced to the rescue again - what about different window buttons if the window is active or inactive?

Obviously this exact solution would be seen as copying macOS, but maybe just having circles or rings in the active window would help.

I suppose inactive windows could be set to not show the circle around the close button by default, but there should always be visible symbols.

I have just tried ScanTailor. It is useful to convert photographed documents to good looking PDFs. (Don’t know why they talk about scans, scans don’t need this.) It already uses Qt and feels like other KDE applications.

In D21416#472772, @tobiasdeiminger wrote:

In D21416#471897, @tobiasdeiminger wrote:

In D21416#471795, @davidhurka wrote:

For dark color themes: maybe the color of the adjacent text would be good as foreground color for the icons. Don’t know, but maybe QGuiApplication::pallete().color(QPalette::WindowText)?

Makes sense, thanks. Never tried this before, give me some time to check it out...

Tried your suggestion, looks good with breeze dark. Would you consider it important to connect to QGuiApplication::paletteChanged, to follow theme changes immediately?

Not wrong but not important. How often does one change the color theme while chosing a line ending? I could only imagine that the color theme changes automatically based on enviromnent light sensors, for people who work in a vehicle passing many tunnels. But how often does one chose the line ending while entering/leaving a tunnel the same time?

In D10859#472473, @simgunz wrote:

Not only straight line, but also freehand line, geometrical shape and polygon (with the same meaning). I agree with you, but on the other hand in drawing software like Krita or Gimp it is called Size so maybe the users are used to it. I have not a strong preference on this matter.

In D10859#472322, @simgunz wrote:

For Highlighter and Geometrical shape I moved the annotation type to the top, before the color/size settings. What do you think?

Makes sense, most important setting first. :) Maybe this makes squiggle and strikeout a bit more discoverable.

Turns out that nothing is independent of page rotation, just discovered PagePrivate::rotateAt(Okular::Rotation), which transforms everything what is known to rotateAt().

Turns out that the coordinate system of RegularAreaRect, as it is used by TextPage::textArea(TextSelection), is not independent of the page display. textArea() transforms the whole RegularAreaRect with the current totalRotation() of the Page.

In D10859#471799, @ngraham wrote:

I don't think the section headings really added much. Most of them were group boxes with one item, which is pointless. When using a FormLayout style, in general you want to make the labels self-explanatory as much as possible so you don't need section headers. To separate groups of related settings, you can add some whitespace that has the effect of grouping things together in a very natural-looking way. We do this extensively in other FormLayouts and people generally think it looks good:

I’m not sure whether to agree.

The UI looks good and I understand the code. :)

Just tried this. Maybe you can bring back the section headings, which were group box labels before? Straight Line got many options recently.

Got an overview of open-a-document methods in the Detailed Description of Part. Helped me a lot, can it stay there?

• Add structure to open*(url) methods documentation, shown in Detailed Description of Part
• Make showMenu() documentation more generic.

If you say “at this low level”, would being more abstract make more sense?

I’m complaining a lot about the source code. Don’t understand that as arrogant demand to fix it, just tell me to do it. Anyway, the code works, so no need to change it?

Giving up for today, there are sooooo many functions of the format open*(url).

Did exactly this (and some more)

• Improve code documentation of updateViewActions() and showMenu()
• Document random member functions of Part, including showMenu()
• Document more random member functions of Part, including openUrl(), and improve thats code comments
• Document even more open*(url) functions, and slotPrint(). Also complain about source code.
• Remove TODOs (but not all)

In D21364#469241, @jangmarker wrote:

Now it looks like this:

Looks ok, but if someone makes PageViewAnnotator::makeToolPixmap() return a QIcon(Engine) instead of a pixmap, it will look better.

Why do you move EditAnnotToolDialog to GuiUtils? / How does the annotation tool bar (shown with F6) get its icons?

In D21376#469822, @davidhurka wrote:

Your code:

Wouldn’t static_cast<>() be better than a C-style cast?

You are not touching “Highlight with Comment”-style texts, which is probably good. (And would fit in another commit anyway.)
There was a discussion about this in D10797, and in T8533 in more general, but this patch is probably fine.
(T8533 is why I thought the annotations would have been y-ordered.)

In D21364#469159, @jangmarker wrote:

I think captionForAnnotation() does not include the comment's text currently, so this change should probably be done in another commit.

Nice, makes the list more intuitive. :) (Didn’t test this)

Probably it should be described how dropped URLs are handled in general? Sometimes the Part uses them and wildly opens files, sometimes not.

• Part::Part() 'QObject is a widget' -> 'QObject is an object'
• Document some D-Bus methods and Part signals, minor improvements in Document

So I will keep it this way.

In D21195#468008, @ngraham wrote:

+1 for this. I think it makes sense. Trying it out, I like it a lot.

• NormalizedPoint: Revert some stuff and mention mouse click events

Should the section “Coordinate System” of NormalizedPoint mention the “Trimmed Margins” feature? To prevent that someone sloppily codes a feature, which draws something on the page and fails if Trim Margins is active.

In D21281#467283, @aacid wrote:

In D21281#466844, @davidhurka wrote:

Is there some more KParts literature? I could find KParts on api.kde.org and the tutorials on community.kde.org, but couldn’t really transfer that to Okular.

Why you couldn't transfer it to okular? If you don't say what you don't understand is hard to explain *everything*

• Fix typos spotted by yurchor
• Fix typos spotted by Albert

Didn’t get far yet. Much information is visible in the source code, but what should I put into the class/member documentation, and what is clear just because it’s a Part?

TextPagePrivate::correctTextOrder() calls some complex functions, which are yet undocumented. Interesting stuff is happening in them, so they should get some documentation. I added their prototypes to core/textpage_p.h, so I can add documentation to them.

This is part of my goal to understand how TextEntity reordering works. There will probably be more patches like this soon.

I have figured out, what was going on in the QToolButton.

• Toolbar button finally shows the intended menu
• Add icon for Configure... action
• Corrected action-slot connections
• Named enable/disable action "Change Colors" again, looks better in the toolbar

I have added CheckableActionMenu, which cuts the default action connection between the KActionMenu itself and the toolbar button. Now it is possible to make the toolbar button checkable, but not the submenu.

Removed checkbox from submenu, but toolbar button invents other menu structure

The lambda looks much better, but it uses still int as action data, not Okular::SettingsCore::EnumRenderMode::type, which would make more sense. Is it possible to put Okular::SettingsCore::EnumRenderMode::type into the action’s QVariant? It didn’t work because I couldn’t register it as metatype.

• Renamed the menu entries to Color Mode and Enable Color Changing
• Use lambda function instead of function-like macro

In D21195#464938, @aacid wrote:

That menu is ultra hard to understand, it's a checked action + menu with an action with the same name inside that is also a checked action

In D21195#464828, @ngraham wrote:

Screenshots are appreciated when submitting patches that change or add UI elements. :)

https://community.kde.org/Infrastructure/Phabricator#Include_some_screenshots

Nate suggested almost exactly this patch in Bug 407326. But instead of hiding Continuous when accessed from the menubar, I moved Continuous completely to the View Mode submenu.

Okular does not follow the KDELibs coding style, so I tried to follow the existing coding style. Maybe I didn’t understand something right, if so, please correct me.