[js library] utilities for scripting  SOLVED

Forum for the PDF-XChange Editor - Free and Licensed Versions

Moderators: PDF-XChange Support, Daniel - PDF-XChange, Chris - PDF-XChange, Sean - PDF-XChange, Paul - PDF-XChange, Vasyl - PDF-XChange, Ivan - Tracker Software, Stefan - PDF-XChange

Mathew
User
Posts: 760
Joined: Thu Jun 19, 2014 7:30 pm

[js library] utilities for scripting  SOLVED

Post by Mathew »

I use these utility functions quite a lot in other scripts. I've tried to document them within the code, so I won't repeat here. The color utilities I've been using for quite a while but didn't get around to posting the source here until v2. It includes a color picker that makes use of the undocumented 'image' and 'link_text' types in dialogs.

The timeout and interval methods are not needed as of the 10.5 release of PDF-XChange.
The PXEmacro class is mostly covered by the new util.expandMacros method as of the 10.6 release of PDF-XChange https://www.pdf-xchange.com/product/pdf ... 10-6-0-396

These zip files contain the source code for the three main xutil libraries I made:
xutil: My plan was to minify the script, but because this is all loaded locally, I didn't see a need and included the source -- now I think starting to include a minified version would cause confusion so I've always just stuck with including the source.
xutil v0.8.zip
xutil.ClrUtx: This is the color utilities. This one I do use a minified version and call the file xutil.colorUtils.js:
xutil.colorUtils v2.2.zip
xutil.stampDialog: This is the stamp dialog utility. This one I also use a minified version and call the file xutil.stampUtils.js:
xutil.stampUtils.source v1.6.1.zip

This is a pdf with documentation (output by jsDoc):
xutil 2025-08-06.pdf
xutil.addBookmark
  • Add a bookmark that uses built-in bookmark properties at current page/zoom/position (ie without the limitations of bookmark.setAction())
    Uses a saved array of bookmarks and .includes() to find which bookmark was added.
xutil.setInterval
xutil.setTimeout Note that capitalization matches javascript in browsers (the built-in app.setTimeOut() capitalizes 'Out'.)
  • These extend the built in app methods to allow one to pass functions. I find this much easier to work with because I can use closures. Instead of returning an object, they return an integer greater than zero on success.
xutil.clearInterval
xutil.clearTimeout
  • Functions to clear the interval or timeout set with the above functions.
xutil.getNewAnn
  • Get an annotation as soon as it's drawn
xutil.PXEmacro
  • Minimal PDF-XChange macros class for javascript
xutil.GetPageRectangle
Class based on Matrix2D but it fixes view rotation and page offsets (in PDF XChange build 386 onwards).

xutil.rotateCoords
Rotate a coordinate array around a point.

xutil.getBounds
Get the min and max coordinates of a coordinate array.

xutil.bxCtr
Get the center point of bounding box (obtained from xutil.getBounds).

xutil.ClrUtx
  • Class for color utilities I have used in quite a few scripts. From v2 onwards, it has a dialog that includes color images for a color picker (previously it was limited to just using the color names in a drop-down list). It's documented in the code, but I've also output the jsDoc as a pdf.
xutil.stampDialog
  • This is the library to make stamp dialogs easier and has functionality to change the color of stamp elements. I've posted extensively about it here: viewtopic.php?t=45879

Licensing
These are all released under the 'MIT license' so you can pretty much do with it as you want. I included a copy of the license in the zip file. The software is provided "as is", without warranty of any kind, express or implied, including but not limited to the warranties of merchantability, fitness for a particular purpose and noninfringement.
You do not have the required permissions to view the files attached to this post.
Last edited by Mathew on Wed Aug 06, 2025 9:06 pm, edited 25 times in total.
User avatar
Stefan - PDF-XChange
Site Admin
Posts: 19930
Joined: Mon Jan 12, 2009 8:07 am

Re: [javascript] utilities for scripting

Post by Stefan - PDF-XChange »

Hello Mathew,

Many thanks for sharing those utilities you've prepared with other users here in the forums!

Kind regards,
Stefan
Mathew
User
Posts: 760
Joined: Thu Jun 19, 2014 7:30 pm

Re: [javascript] utilities for scripting

Post by Mathew »

I changed the parameters that get sent to the timeout and interval functions. Now 'this' (the current doc) is sent if no additional args are supplied, otherwise, only the additional args.
xutil v0.4.zip
You do not have the required permissions to view the files attached to this post.
Mathew
User
Posts: 760
Joined: Thu Jun 19, 2014 7:30 pm

Re: [js library] utilities for scripting

Post by Mathew »

Adding xutil.ClrUtx source code to the first post above.
xutil.colorUtils v2.1.zip
version history
* v2.1 2025-07-02 fix some duplicated color names; add hideLinks parameter to color picker; fix errors when making dialog if color is null; code cleanup in main loop; slight change to method of finding nearest color
* v2.0 2025-06-30 add color box picker option; add color boxes to editColrNames; add new method editCustomColors; lint cleanup; add .useHex property; document code; standard colors rearranged and based on @mCHSNUg5Pz8cPap forum post viewtopic.php?t=46178
* v1.2 2025-03-30 make equal a static property so can use xutil.ClrUtx.equal()
* v1.1 2024-11-18 add noSave parameter to editColrNames()
* v1.0.1 2024-11-18 check if supplied color string undefined in colFromStr
* v1.0 2024-09-18 revised to separate xutil, added own persistent global, added translation, make color name based on nearby colors
* v0.1 part of change colors tool

xutils is also updated to v0.7
version history
* v0.7 2025-04-04 PXEmacro revisions, getNewAnn revisions, added xutil.addBookmark()
* v0.6 2025-03-31 fix alphabetize function; add methods dealphabetize, deromanize, fromNumberType
* v0.5 2024-12-12 fix bugs and add return function for cancel in getNewAnn(), add parameter to setTimeout so can request an ID (makes dealing with cancelling timeouts in running intervals easier)
* v0.4 2024-12-03 changed parameters supplied to timeout and interval return functions, code cleanup
* v0.3 2024-05-08 added xutil.PXEmacro()
* v0.2 2024-05-03 added xutil.getNewAnn()
* v0.1.1 2024-04-28 added _XUTIL_DEBUG_ option
* v0.1.0 2024-04-12
You do not have the required permissions to view the files attached to this post.
User avatar
Stefan - PDF-XChange
Site Admin
Posts: 19930
Joined: Mon Jan 12, 2009 8:07 am

[js library] utilities for scripting

Post by Stefan - PDF-XChange »

:)
Mathew
User
Posts: 760
Joined: Thu Jun 19, 2014 7:30 pm

Re: [js library] utilities for scripting

Post by Mathew »

I updated to v0.8 and included the stampUtils.


xutil v0.8
  • Clearly cite license
  • Add GetPageRectangle class;
  • add methods for working with point coordinates rotatePoint(), rotateCoords(), getBounds(), bxCtr()
xutil v0.8.zip

colorUtils v2.2
  • clearly cite license
  • use colArr256() in colObj() if can't find color name
  • fix bug when one of the custom colors deleted
xutil.colorUtils v2.2.zip

stampUtils
xutil.stampUtils.source v1.6.1.zip
  • v1.6.1 2025-08-06 clearly cite license
  • v1.6 2025-08-01 update to v2.1 of ClrUtx color picker (instead of dropdown with color names)
  • v1.5 2025-04-10 console output if stampID is not a string; fix error getting annots/fields if there are none; fix startTool to start a tool on app.doc; fix changing color of fields inside elements
  • v1.4 2025-04-04 code changes: move DialogDataStore class property declarations to constructor, and make DialogDescription a constructor function; fix typo on startTool setup; fail gracefully if no ClrUtx; compress with minify-js.com (ecma 2016)
  • v1.3 2025-04-03 fix color dialog when function is supplied; remove unnecessary code; move some defaults to front of function; update all fields & globals before color assignment is done
  • v1.2 2025-04-03 allow popup to return a non-string value; add try/catch and better error reporting to setStampProperty
  • v1.1 2025-04-02 xutil.setStampProperty for setting any property of the stamp, start timeout after the ok() functions have run.
  • v1.0 2025-03-29 add xutil.stampDialog to make dynamic stamp dialogs easier
  • v0.1 2025-01-22 xutil.setStampColor for setting strokeColor on a stamp after it's placed
You do not have the required permissions to view the files attached to this post.
User avatar
Jordan - PDF XChange
Site Admin
Posts: 285
Joined: Mon Jul 03, 2023 3:10 pm

[js library] utilities for scripting

Post by Jordan - PDF XChange »

:)
Best regards,
Jordan