Controlling the Viewer

• A working build of the viewer
• A text editor you like, preferably with syntax highlighting for JavaScript and PHP (The one used in the example)

• Important:
  • Anytime x and y coordinates (or any pixel measurement) are provided or recived by the viewer, they are scaled to match the height and width specified in the config.ini file. The only exception to this rule is viewerSetDragDistance.

State

• The static(ish) size and scaling factors of the viewer.
  • viewerGetViewerDensityFactor(): viewerGetWidth() × viewerGetViewerDensityFactor() = The window width in config.ini Get a number to multiply by screen pixels to turn it into viewer pixels.*
    • Generaly this is not needed because the viewer scales everything going in and out to match the width and height specified in the config file.
  • viewerGetWidth(): Gets the width of the viewer in pixels*
  • viewerGetWidthInches(): Gets the width of the viewer in inches*
  • viewerGetHeight(): Gets the height of the viewer in pixels*
  • viewerGetTextureInfo(): Get a message about any changes the viewer performed on the images to get them to work on the client's computer.
  • viewerGetStartTime(): Get the time, measured by JavaScript's Date.now of when the viewer first loaded. viewerGetUpTime() counts upwards from this point onward.
  • viewerGetVersion(): Get the version of the viewer build. This will probably be a string like v3. This is not a replacement for the version code you give your own code (that code will change a lot more than the viewer code).

Input

• On the fly control of the viewer.
  • viewerSetDragDistance( newDistance ): The drag distance by default scales to the viewer's pixels, if you want to reset it yourself (to conform to inches or something you can reset it here.
  • viewerSetButtonTime( seconds ): State how many seconds the button must be held before the slide advances (note that unlike the config setting, you can only input seconds here, no milliseconds).
  • viewerSetScrollLimit( newLimit ): The maximum amount of scroll allowed per scroll event. Unless different custom values are needed per client it is best to set this in the config file.
  • viewerSetScrollSensitivity( newSensitivity ): The sensitivity of the scroll wheel. Unless different custom values are needed per client it is best to set this in the config file.
  • viewerPipeInput(keyCode, pressType): Direct input the viewer. This is important because browsers don't do the best job giving canvas elements focus.
    • keyCode is a number, you can use the event flag from event.keyCode (which is becomming obsolete, but still fairly well supported), or use FLAGviewerKeyScrollUp or FLAGviewerKeyScrollDown.
    • pressType is a number to tell whether the key was pressed down, or released, use FLAGviewerKeyPressRelease or FLAGviewerKeyPressDown.
  • viewerScrollLock( true or false ): disable or enable scrolling
  • viewerClickLock( true or false ): disable or enable clicking. This means events window.viewerListenerClickAdded and window.viewerListenerClickRemoved won't fire, however the last click will still be set, and window.viewerListenerInput will still fire.
  • viewerSetSlide( setIndex, optinal slideIndex): Tell the viewer to show a specific set of slides. Optionally at a specific index. Note: viewerSetSlide(4, 0) = viewerSetSlide(4). Note that this will log a blur event on the previous image, and a focus event on the new image, assuming they are not the same. If they are the same, and you use this to scroll to another slide, it will NOT be logged. If you wish for that event to be logged, add a message with viewerLogScrollMessage(index,message) ²

Present Status

• Current (but changing) status of the viewer.
  • viewerGetLastClick(): Get the last click, see the config file's overwrite last click setting.
    • This is formatted as x,y,slide,time
    • This will be 0,0,0,0 if no click occured since the last viewerResetLastClick
  • viewerGetCurrentSlide(): Get the index for the current slide.
  • viewerGetCurrentSet(): Get the index for the current set
  • viewerGetUpTime(): Get the milliseconds the viewer has been active. This is the same timing method used in the viewer's logs.

Control

• Resetting.
  • viewerResetLastClick(): Reset the last click, see the config file's overwrite last click setting.
  • viewerResetSize(): Reset the viewer's size if a new value is provided through window.viewerStatsWidth, Otherwise, the viewer will recreate itself with the same size, which is a lot of expense for no gain.²
  • viewerResetScrolls( index ): Reset the scroll log at a specific image's index
  • viewerResetClicks( index): Reset the clicks (log, and displayed clicks) at a specific image's index
  • viewerResetHighlights( index ): Reset all of the highlights and shapes (both UI and image) at a specific image's index
  • viewerResetShaderLog(): Clear the shader log but not the shaders themselves. Shaders can be removed with viewerRemoveShader(name)
• Creation
  • viewerSimulateClick( index, x, y, slide ): Simulate a click for the image at index, at the position x, y,slide. Note that this could add or remove a click (if one was already nearby). ¹
    • These clicks are logged.
    • These clicks fire the window.viewerListenerInput event.
    • These clicks fire the window.viewerListenerClickAdded or window.viewerListenerClickRemoved event.
    • These clicks do not set the click retrieved by viewerGetLastClick().
  • viewerAddHighlight( index, x, y, slide ): Add a highlight marker for the image at index, at the position x, y,slide.
  • viewerAddShapeToImage( name, index, x, y, slide ): Add a shape named name from shapes.txt to the image at index, at the position x, y,slide. Note, these shapes are effected by shaders. ¹
  • viewerAddShapeToUI( name, index, x, y, slide ): Add a shape named name from shapes.txt to the image at index, at the position x, y,slide. Note, these shapes are not effected by shaders. ¹
• Shaders (Windowing)
  Look in the shader page for details on the following functions:
  • viewerAddCustomShader( name, vertexShader, fragmentShader, optional log )
  • viewerAddWindowingShaderGray( name, level, width, optional log )
  • viewerAddWindowingShaderValue( name, level, width, optional log )
  • viewerAddWindowingShaderGrayFull( name, level, width, optional log )
  • viewerAddWindowingShaderValueFull( name, level, width, optional log )
  • viewerAddWindowingShaderGray16( name, level, width, optional log )
  • viewerSetveShader( name, optional log )
  • viewerRemoveShader( name, optional log )

Logging

• Getting lists of information (and adding to those lists).
• Look in the controls section above for functions to reset logs.
• Get:
  • viewerGetClicksFor( index, separater1, separater2 ): Get a string containing all of the current clicks for the image at index. The components (eg: x, y, slide, time) of every click are separated by separater1, and every click is separated by separater2.
    • This list doesn't contain every click ever performed, any clicks which have been removed are not reported in the log, if you want those, save them when they trigger viewerListenerClickAdded and viewerListenerClickRemoved
    • A recorded click does not have any sort of type identifier.
    • Clicks have 4 components: x, y, slide, time of click
    • Click Messages have 2 components: message, time of message
      Be aware that messages aren't wrapped in quotes or anything to signify that they are strings. If you put a comma in your message, and use a comma for a separater, you will have a difficult time parsing your data later.
  • viewerGetScrollTimesFor( index, separater1, separater2 ): Get a string containing all of the scrolls performed for the image at index. The components (eg: slide, time, event) of every scroll are separated by separater1, and every scroll is separated by separater2.
    • Each scroll can be flagged with 1 of 4 events.
      • f: the focus event, happens when viewerSetSlide navigates to the image.
      • w: a scroll event, happens when the user scrolls the image with the mouse scroll wheel (but not when viewerSetSlide moves to another slide of the image).
      • d: a scroll event, happens when the user scrolls the image by dragging with touch or mouse (but not when viewerSetSlide moves to another slide of the image).
      • k: a scroll event, happens when the user scrolls the image with arrow keys or WASD (but not when viewerSetSlide moves to another slide of the image).
      • b: the blur event, happens when viewerSetSlide navigates away from the image.
      • m: the message event, you inject a message into the scroll log with viewerLogScrollMessage.
    • If the image was never active, the string should be empty.
    • If the image was active, but the user never scrolled, there should at least be a focus event, and depending on your implementation a blur event.
  • viewerGetShaderLog( separater1, separater2 ): Get a string containing all of the shader changes for the entire viewer (shaders are not constrained to a particular image). The components of every shader change are separated by separater1, and every shader change is separated by separater2. More in The shader documentation
• Add:
  • viewerLogClickMessage( index, message ): inject a message into the click log for the image at index.
  • viewerLogScrollMessage( index, message ): inject a message into the scroll log for the image at index.
  • viewerLogShaderMessage( message ): inject a message into the shader log.

Tutorial Videos