set pageOffset by mouse click on grid column

[octaeder]

This PR resolves #2190 (enhancement request) in that it supports to choose/set offset to the right for page 1 by using shift+click on the grid's rectangles. This mode of operation is signaled by changing the cursor to ArrowCursor on pressing shift. You must enable Scroll (s. hand icon in toolbar) in txs to use this feature.

The grid rectangle you click on need not contain a page of the document and you need not to scroll up to page 1. After the click the value of variable pageOffset is set such that page 1 of the document is moved left/right to that column you clicked. Grid rectangles before page 1 stay empty.

Anything said before applies to grids of any size. By this we circumvent easily the restriction that has been imposed to grids with two columns, where page 1 has always been moved to the 2^nd column (this is now the default, when setting up grid 2x1). The value of pageOffset is stored in the ini file. If you setup a grid that is too narrow for the current pageOffset, then pageOffset is reset to rightmost column. As pageOffset is an index, it counts columns starting from 0 for first column. In any case inequality 0 <= pageOffset < gridx holds, where gridx is the number of columns of the grid. Since embedded viewer is forced to use gridx = 1, you (currently) can't use this feature there.

Btw: A small enhancement to normalizedPageIndex will map all page indices p of the first grid to realPageIndex = 0. The current version maps p = 0 to 0. If everything is correct then this should be enough. But it may happen that someone tries to normalize a page index greater one (there can be many on a bigger grid) that should have normalizedIndex = 0. But in this case the normalization would miss the special case that -pageOffset should be mapped to 0.

Examples

Open a document in windowed (and internal) pdf-viewer. Uncheck single page step (otherwise pageOffset = 0), choose a grid of size 2x2 and enable Scroll mode. By default title page is to the left:

There are equal images on page 2 and 3. They belong together (same with pages 4 and 5, and so on). To present them side by side, we change operation mode by pressing shift key such that the cursor changes to arrow (move mouse a small amount):

Page offset changes after pressing (on page to the right ) and releasing the left mouse button. Release shift key:

We can check Continuous mode in the View menu and scroll down a little bit, so we can see next pair of images side by side:

We wish to better use the area in the canvas. So we decide to use a grid of 4x2 (use Custom... in Grid menu):

Maybe we are still not satisfied since the first line holds more than the title page. Also to keep pages 2 and 3 together we have to move the title page to the end of line. With shift+click we get:

Now we uncheck Continuos and choose a grid of 6x2. Since the first page is still in the 4^th column, we have 3+6 pages in the first grid and 10 pages on the next grid (from a total of 19 pages, s. image), leaving free 2 grid rectangles. This can be seen, when we jump to the end:

To fill up the last line we move first page from 4^th to 6^th column. For this we can click on the last page in the first row shown in the previous image or on the rectangle below it without a page (imagine missing pages at the end, same at the beginning):

And the result is as expected:

If we stop txs now, we find in the ini file:

Preview\GridX=6
Preview\GridY=2
Preview\PageOffset=5

[sunderme]

looks okay.
default behaviour should still be that pageOffset for grid 2x1 is 1.

[octaeder]

on first start ever of txs default for grid size is 1x1, so default for pageOffset (po) has to be 0. We could go to first start with defaults 2x1 and 1. After that last po is used whenever possible.

If I change grid from 2x1 to 2x2 or 4x1what should happen then? And what happens, when I go back to 2x1? After that round trip I would like to see po to be the same at start and end (when I do not change po manually) since I still see the same document. This can't be done if I switched po to 0 after selecting grid 2x1.

[octaeder]

I observed some refresh problems. For ex. with 19 pages in 4x2 grid switch to continuos, then change po from 0 to 3. If you scroll to the end you might not see all pages or if you change po in the last line pages are not refreshed. Workaround is to change zoom to refresh.

[sunderme]

my guess is, that it still changes default behaviour
default behaviour has to be the same, i.e. pageOffset=1 for 2x1 grid after changing to it.
it is a reasonablefunction and too many people complained about it when grid was introduced at first.

Furthermore pageOffset gets changed when using grid 1x1 which makes storing it in config a bit odd.

by the way, i don‘t mind changes on other grid settings.

[sunderme]

is it complete now ? The "draft mode" is still set, so it can't be merged.

[octaeder]

do more testing. PR complete today or tomorrow

[sunderme]

thanks

[sunderme]

In case you want other users to use this, there should be a note in the manual.

[octaeder]

And maybe in the release notes (changelog)? Who's allowed to add things there?

As a note I would expect not much text in the manual, say 3 sentences, and no images. So where to place? I could add a new section Viewing pdf documents to chapter Compiling, which already talks about viewing logs. Or we could add it to chapter Other features, section Miscellaneous features. This chapter offers another possibility, because it introduces pdf-viewer in it's 10^th section "Forward/Inverse search" with TeXstudio. But this place currently offers not the right context for my text. So I would not like to place it there. Are there any suggestions from you @sunderme ?

[sunderme]

a section to compiling is fine. Maybe it can be extended over time.

[octaeder]

@sunderme @egidioln Suggestion as a starter (has to be in html of course)

%-------------------------------------------------------------------------------
\section{Internal pdf viewer}\label{sec:pdf_viewer}
%-------------------------------------------------------------------------------
%

\txs{} has an internal (builtin) pdf viewer that you can use to view your final
pdf documents. The viewer can be embedded or window-based (windowed). The former
one uses an area to the right of the editor, the latter uses it's own window and
gives the user more options. The viewer can be opened by clicking on button
\textit{View} or with key F7.

You can choose main mode \textit{Magnify} or \textit{Scroll} from the toolbar. These offer following actions:

\begin{itemize}
\item Magnify
\begin{itemize}
\item left mouse button click opens magnifier showing enlarged part of the text
\item Shift + left mouse button click increase zoom level
\item Alt + left mouse button click decrease zoom level
\end{itemize}
\item Scroll
\begin{itemize}
\item left mouse button click graps the document so you can scroll it around or follows a link
\item double left mouse button click opens magnifier
\item Shift + left mouse button click sets grid column for the first page (s. \nameref{sec:special_features})
\end{itemize}
\end{itemize}

%-------------------------------------------------------------------------------
\subsection{Special features}\label{sec:special_features}
%-------------------------------------------------------------------------------
%

The viewer arranges pages in a grid of columns and rows where the pages are
placed. Normally the first page is placed to the left of the first row and
following pages fill the row and so on. This behavior might not be suitable in
all cases. For instance if you work on a book, since books have odd pages to the
right. For taking care of this need the first page is automatically moved to the
right, when you choose the grid 2x1 from the menu. The place to the left stays
empty. You can change the place for the first page manuallay in any grid. For
this use Shift + left mouse button click on any place of the grid while in
Scroll mode. The first page will move to the place that is in the first row and
in the same column as the place you selected.

[sunderme]

looks okay (some spelling mistakes though)

[octaeder]

update of manual with PR #2396, part of getPosFromClick contributed by @egidioln