Add FPDFDest_GetLocationInPage API

public/fpdf_doc.h

 // Copyright 2014 PDFium Authors. All rights reserved.
 // Use of this source code is governed by a BSD-style license that can be
 // found in the LICENSE file.
 
 // Original code copyright 2014 Foxit Software Inc. http://www.foxitsoftware.com
 
 #ifndef PUBLIC_FPDF_DOC_H_
 #define PUBLIC_FPDF_DOC_H_
 
 #include "fpdfview.h"
@@ skipping 153 matching lines @@
 
 // Get the page index of |dest|.
 //
 //   document - handle to the document.
 //   dest     - handle to the destination.
 //
 // Returns the page index containing |dest|. Page indices start from 0.
 DLLEXPORT unsigned long STDCALL FPDFDest_GetPageIndex(FPDF_DOCUMENT document,
                                                       FPDF_DEST dest);
 
+// Get the (x, y, zoom) location of |dest| in the destination page, if the
+// destination is in [page /XYZ x y zoom] syntax.
+//
+//   dest    - handle to the destination.
+//   hasX    - out parameter; true if the x value is not null

[Lei Zhang, 2016/11/07 22:04:17]

Still a little ambiguous, as "x" can refer to either the x in [page /XYZ x y
zoom], or the x parameter. Maybe rename the parameters to avoid confusion?

I would also mention that the float out parameters are only written to if the
corresponding boolean is set to true.

[dsinclair, 2016/11/08 14:04:46]

Done.

+//   hasY    - out parameter; true if the y value is not null
+//   hasZoom - out parameter; true if the zoom value is not null
+//   x       - out parameter; the x coordinate, in the page coordinate system.
+//   y       - out parameter; the y coordinate, in the page coordinate system.
+//   zoom    - out parameter; the zoom value.
+// Returns TRUE on successfully reading the /XYZ value.
+DLLEXPORT FPDF_BOOL STDCALL FPDFDest_GetLocationInPage(FPDF_DEST dest,
+                                                       FPDF_BOOL* hasX,
+                                                       FPDF_BOOL* hasY,
+                                                       FPDF_BOOL* hasZoom,
+                                                       FS_FLOAT* x,
+                                                       FS_FLOAT* y,
+                                                       FS_FLOAT* zoom);
+
 // Find a link at point (|x|,|y|) on |page|.
 //
 //   page - handle to the document page.
 //   x    - the x coordinate, in the page coordinate system.
 //   y    - the y coordinate, in the page coordinate system.
 //
 // Returns a handle to the link, or NULL if no link found at the given point.
 //
 // You can convert coordinates from screen coordinates to page coordinates using
 // |FPDF_DeviceToPage|.
@@ skipping 92 matching lines @@
 DLLEXPORT unsigned long STDCALL FPDF_GetMetaText(FPDF_DOCUMENT doc,
                                                  FPDF_BYTESTRING tag,
                                                  void* buffer,
                                                  unsigned long buflen);
 
 #ifdef __cplusplus
 }  // extern "C"
 #endif  // __cplusplus
 
 #endif  // PUBLIC_FPDF_DOC_H_