View source for Subject locator previews

Subject locator is an URI that '''is''' the subject of a topic. In Wandora, each topic may have at most one subject locators. Wandora's [[Traditional topic panel]] views subject locator URI. In Wandora, a subject locator can be a

* Local resources that is addressed by a file URI.
* External resource addressed by an URL. Usually URL's protocol is http or https.
* Internal [https://en.wikipedia.org/wiki/Data_URI_scheme data URI] resource where the data is encoded inside the URI itself.

[[Traditional topic panel]] views the subject locator resource if option '''View subject locators''' is enabled. The option is set by selecting a menu option '''View > Traditional w ... > View subject locators'''. Another method to toggle the subject locator previews is to press the icon button right to the subject locator label. Wandora doesn't view subject locator resources by default. Once subject locator preview is enabled, Wandora resolves mimetype for the subject locator resource and chooses a viewer for the resource.


== Supported preview formats ==

Wandora selects a viewer for the subject locator resouce using resources mimetype. At the moment Wandora has a viewer for images, videos, web pages etc. Next table lists all viewers and supported data formats (2016-05-10).

{| class="wikitable" 
|-
|'''Mimetype(s)'''
|'''File extension(s)'''
|'''Handler'''
|'''Description and notes'''

|- style="vertical-align: top"
|
application/zip
|
zip
|
ApplicationZip
|
Zip archive preview. Views the content of zip archive and allows the extraction of zipped files.

|- style="vertical-align: top"
|
application/x.zx.*<br>
application/x-spectrum-*<br>
application/x.spectrum.*
|
z80<br> 
slt<br> 
tap<br>
sna<br>
rom
|
ApplicationZX
|
[https://en.wikipedia.org/wiki/ZX_Spectrum Sinclair ZX] emulator based on [http://wizard.ae.krakow.pl/~jb/qaop/ Qaop] created by Jan Bobrowski.

|- style="vertical-align: top"
|
application/d64<br>
application/x-d64<br>
application/x-cbm-d64<br>
application/t64<br>
application/x-t64<br>
application/x-cbm-t64<br>
application/x-c64-program<br>
application/x-c64-snaphot
|
d64<br> 
t64<br> 
prg<br>
p00
|
ApplicationC64
|
[https://en.wikipedia.org/wiki/Commodore_64 Commodore 64] emulator based on [https://sourceforge.net/projects/jmec64/ JSwingC64] created by Joerg Jahnke.

|- style="vertical-align: top"
|
audio/midi<br>
application/x-midi
|
mid<br>
midi<br>
rmf
|
AudioMidi
|
[https://en.wikipedia.org/wiki/MIDI Midi] audio player. The midi player is based on Java's midi system.


|- style="vertical-align: top"
|
audio/x-flac
|
flac
|
AudioFlac
|
[https://en.wikipedia.org/wiki/FLAC Flac] audio player. Wandora's flac audio player uses Daniel Becker's Javamod player. The Javamod player is embedded in Wandora and requires no extra installations.




|- style="vertical-align: top"
|
audio/ogg<br>
application/ogg
|
ogg<br>
ogx
|
AudioOgg
|
[https://en.wikipedia.org/wiki/Vorbis Ogg Vorbis] audio player. Wandora's ogg audio player uses Daniel Becker's Javamod player.





|- style="vertical-align: top"
|
audio/x-sidtune<br>
audio/sidtune<br>
audio/x-psid<br>
audio/psid<br>
audio/prs.sid<br>
audio/x-sid<br>
|
sid
|
AudioSid
|
[https://en.wikipedia.org/wiki/MOS_Technology_SID Sid tune] audio player. See also [https://en.wikipedia.org/wiki/The_High_Voltage_SID_Collection The High Voltage SID Collection]. Wandora's sid tune audio player uses Daniel Becker's Javamod player.




|- style="vertical-align: top"
|
audio/mod<br>
audio/xm<br>
audio/wow<br>
audio/it<br>
audio/stm<br>
audio/s3m<br>
audio/xm<br>
|
mod<br>
wow<br>
it<br>
stm<br>
s3m<br>
xm
|
AudioMod
|
[https://en.wikipedia.org/wiki/MOD_%28file_format%29 Mod] audio player. Wandora's mod audio player uses Daniel Becker's Javamod player. See also [http://modarchive.org/ The Mod Archive].




|- style="vertical-align: top"
|
audio/x-wav<br>
audio/x-aiff<br>
audio/basic
|
wav<br>
aif<br>
au
|
AudioWav
|
Basic audio sample player for wav and aiff files. Basic audio sample player uses Java's native audio libraries.



|- style="vertical-align: top"
|
audio/mpeg<br>
audio/x-mpeg-3<br>
audio/mpeg3
|
mp3
|
AudioMP3v2
|
Audio MP3 player. Wandora's mod audio player uses Daniel Becker's Javamod player.  The Javamod player is embedded in Wandora and requires no additional installations.





|- style="vertical-align: top"
|
image/*
|
gif<br>
jpg<br>
jpeg<br>
tif<br>
tiff<br>
png
|
Image
|
Image viewer. Even though the viewer captures all image mimetypes, viewer supports only image types supported by Java.





|- style="vertical-align: top"
|
application/pdf
|
pdf
|
ApplicationPDF
|
PDF viewer.





|- style="vertical-align: top"
|
text/rtf<br>
application/rtf
|
rtf
|
TextRTF
|
RTF viewer.




|- style="vertical-align: top"
|
text/html
|
html<br>
htm
|
TextHTML
|
General web viewer uses JavaFX. If Java doesn't support JavaFX, the web viewer doesn't work.






|- style="vertical-align: top"
|
application/xml<br>
text/xml
|
xml
|
ApplicationXML
|
General XML viewer. The XML is viewed as text.




|- style="vertical-align: top"
|
text/*
|
txt<br>
text<br>
asm<br>
asp<br>
bat<br>
c<br>
....
|
Text
|
General text viewer that captures all text type mimetypes and many text file formats.





|- style="vertical-align: top"
|
video/mp4<br>
video/x-flv<br>
video/x-javafx<br>
application/vnd.apple.mpegurl<br>
audio/mpegurl<br>
audio/x-m4a<br>
video/x-m4v<br>
|
mp4<br>
flv<br>
fxm<br>
m3u8<br>
m4a<br>
m4v<br>
|
VideoMp4
|
Video player can view MP4 videos, for example. The video player requires JavaFX. Oracle's Java 8 includes JavaFX by default.





|- style="vertical-align: top"
|
application/x-zmachine<br>
application/x-zmachine-1<br>
application/x-zmachine-2<br>
application/x-zmachine-3<br>
application/x-zmachine-4<br>
application/x-zmachine-5<br>
application/x-zmachine-6<br>
application/x-zmachine-7<br>
application/x-zmachine-8
application/x-blorb
|
z1<br>
z2<br>
z3<br>
z4<br>
z5<br>
z6<br>
z7<br>
z8<br>
zblorb<br>
zlb
|
ApplicationZMachine
|
Viewer runs interactive fiction files in [https://en.wikipedia.org/wiki/Z-machine Z machine] format and the user can play the games. Viewer is based on Z-Machine Preservation Project (ZMPP) created by Wei-ju Wu. Wandora fork is avalable in [https://github.com/wandora-team/zmpp-wandora GitHub as a separate project]. See [http://www.ifarchive.org/indexes/if-archiveXgamesXzcode.html The Interactive Fiction Archive] for playable games. 







|}


Values in Handler column are Java classes in package '''org.wandora.application.gui.previews.formats'''.

== Examples ==

=== Z machine preview example ===

Wandora user has created a topic '''Adventure 3''' with a subject locator '''http://www.ifarchive.org/if-archive/games/zcode/adv550.z8'''. It addresses a playable Z machine application. User opens the topic with Tradition topic panel by double clicking the topic. Next Wandora user toggles the subject locator preview on by clicking the icon right to the subject locator field. Wandora opens up the subject locator preview, a playable Adventure 3, the 550 point version of Adventure aka Colossal Cave, by Dave Platt, from 1979, converted to C99 and compiled as Z-code with a modified vbccz compiler by Arthur O'Dwyer.


[[File:sl_preview_example_zmachine.png|center]]

=== MP3 audio preview example ===

Wandora user has a local folder that contains MP3 audio files. The user drags and drops the folder into Wandora's empty topic panel. Wandora ensures the user wants to extract dropped files with Simple File Extractor. The user confirms and clicks '''Yes to all''' button. Wandora creates topics for each MP3 file in the folder. Each created topic has a subject locator, a file URI addressing MP3 resource. User double mouse clicks one of the created topics, Wandora opens up the topic with Traditional topic panel. After the user has activated subject locator preview, Wandora opens the MP3 player. Now Wandora user can listen the MP3 audio track by pressing player's '''Play''' button.


[[File:sl_preview_example_mp3_1.png|center]]


[[File:sl_preview_example_mp3_2.png|center]]


[[File:sl_preview_example_mp3_3.png|center]]


=== Image preview example ===

In this example, Wandora user creates a topic without subject locator, and opens the topic into Traditional topic panel. Next the user drops a local JPG image file into the subject locator field. The user confirms to create a data uri out of dropped file resource. Wandora creates a data URI out of dropped resource and sets topic's subject locator. Finally user switches subject locator preview on by clicking the icon right to the subject locator field. The reader should note that the image data is now inside Wandora's topic map, encoded inside the data URI.


[[File:sl_preview_example_image_1.png|center]]


[[File:sl_preview_example_image_2.png|center]]


[[File:sl_preview_example_image_3.png|center]]


=== Web preview example ===

First the user double mouse clicks the topic '''Schema type''' in Wandora's topic tree. Wandora opens the topic in a Traditional topic panel. The user right mouse clicks the subject identifier '''http://wandora.org/si/core/schema-type''' and selects the menu option '''Copy to subject locator'''. Wandora sets topic's subject locator. The user sets subject locator previews visible and Wandora previews the URL '''http://wandora.org/si/core/schema-type'''. Next Wandora user changes the subject locator to '''http://www.bbc.com''' and Wandora reloads the preview.



[[File:sl_preview_example_web_1.png|center]]


[[File:sl_preview_example_web_2.png|center]]


[[File:sl_preview_example_web_3.png|center]]

== Preview player options ==

All preview players have an user interface that is used to manage and tune the preview. Available managing and tuning options depend on viewed media format. Next chapters briefly describe available options in each preview player (2015-11-13).

=== AudioMidi ===

AudioMidi preview player is used to play midi audio files. The player has simple user interface to play and stop audio play, copy subject locator URI, fork external application for the URI, and to save the URL resource to a local file. The midi player has no progress bar nor time display.

{| cellpadding="3"
|-
| [[File:sl_preview_ui_play.png]]
| Play the midi audio resource.
|-
| [[File:sl_preview_ui_stop.png]]
| Stop playing the midi resource.
|-
| [[File:sl_preview_ui_copy_location.png]]
| Copy subject locator URI to system clipboard.
|-
| [[File:sl_preview_ui_open_ext.png]]
| Open the subject locator URI with external application registered to handle midi resources.
|-
| [[File:sl_preview_ui_save_as.png]]
| Save subject locator resource to a local file.
|}

=== AudioFlac ===

AudioFlac preview player is used to play FLAC (Free Lossless Audio Codec) audio files. The FLAC player has a progress bar and time display during playback.

{| cellpadding="3"
|-
| [[File:sl_preview_ui_play.png]]
| Plays the FLAC audio file.
|-
| [[File:sl_preview_ui_pause.png]]
| Pause the play.
|-
| [[File:sl_preview_ui_stop.png]]
| Stops the play.
|-
| [[File:sl_preview_ui_backward.png]]
| Move the play cursor backward.
|-
| [[File:sl_preview_ui_forward.png]]
| Move the play cursor forward.
|-
| [[File:sl_preview_ui_copy_location.png]]
| Copy subject locator URI to system clipboard.
|-
| [[File:sl_preview_ui_open_ext.png]]
| Open the subject locator URI with external application registered to handle FLAC files.
|-
| [[File:sl_preview_ui_save_as.png]]
| Save subject locator resource to local file system as a FLAC file.
|}

=== AudioOgg ===

AudioOgg preview player is used to play OGG audio files. The OGG player has a progress bar and time display during playback.

{| cellpadding="3"
|-
| [[File:sl_preview_ui_play.png]]
| Plays the OGG audio file.
|-
| [[File:sl_preview_ui_pause.png]]
| Pause the play.
|-
| [[File:sl_preview_ui_stop.png]]
| Stops the play.
|-
| [[File:sl_preview_ui_backward.png]]
| Move the play cursor backward.
|-
| [[File:sl_preview_ui_forward.png]]
| Move the play cursor forward.
|-
| [[File:sl_preview_ui_copy_location.png]]
| Copy subject locator URI to system clipboard.
|-
| [[File:sl_preview_ui_open_ext.png]]
| Open the subject locator URI with external application registered to handle OGG files.
|-
| [[File:sl_preview_ui_save_as.png]]
| Save subject locator resource to local file system as a OGG file.
|}

=== AudioSid ===

AudioSid preview player is used to play sid audio files. The sid player has a progress bar which views current tune in sid file.

{| cellpadding="3"
|-
| [[File:sl_preview_ui_play.png]]
| Plays the sid audio file.
|-
| [[File:sl_preview_ui_pause.png]]
| Pause the play.
|-
| [[File:sl_preview_ui_stop.png]]
| Stops the play.
|-
| [[File:sl_preview_ui_previous.png]]
| Play previous tune in sid file.
|-
| [[File:sl_preview_ui_next.png]]
| Play next tune in sid file.
|-
| [[File:sl_preview_ui_copy_location.png]]
| Copy subject locator URI to system clipboard.
|-
| [[File:sl_preview_ui_open_ext.png]]
| Open the subject locator URI with external application registered to handle sid files.
|-
| [[File:sl_preview_ui_save_as.png]]
| Save subject locator resource to local file system as a sid file.
|}

=== AudioMod ===

AudioMod preview player is used to play MOD audio files. The MOD player has a progress bar and time display during playback.

{| cellpadding="3"
|-
| [[File:sl_preview_ui_play.png]]
| Plays the MOD audio file.
|-
| [[File:sl_preview_ui_pause.png]]
| Pause the play.
|-
| [[File:sl_preview_ui_stop.png]]
| Stops the play.
|-
| [[File:sl_preview_ui_backward.png]]
| Move the play cursor backward.
|-
| [[File:sl_preview_ui_forward.png]]
| Move the play cursor forward.
|-
| [[File:sl_preview_ui_copy_location.png]]
| Copy subject locator URI to system clipboard.
|-
| [[File:sl_preview_ui_open_ext.png]]
| Open the subject locator URI with external application registered to handle MOD files.
|-
| [[File:sl_preview_ui_save_as.png]]
| Save subject locator resource to local file system as a MOD file.
|}

=== AudioWav ===

AudioWav preview player is used to play WAV audio files. The WAV player contains a waveform view and buttons to control the playback and the subject locator resource. Next image views WAV player's waveform.


[[File:sl_preview_wav_waveform.png|center]]


Buttons to control the playback and the subject locator resource are


{| cellpadding="3"
|-
| [[File:sl_preview_ui_play.png]]
| Plays the WAV audio file.
|-
| [[File:sl_preview_ui_stop.png]]
| Stops the play.
|-
| [[File:sl_preview_ui_copy_location.png]]
| Copy subject locator URI to system clipboard.
|-
| [[File:sl_preview_ui_open_ext.png]]
| Open the subject locator URI with external application registered to handle WAV files.
|-
| [[File:sl_preview_ui_save_as.png]]
| Save subject locator resource to local file system as a WAV file.
|}

=== AudioMP3v2 ===

AudioMP3v2 preview player is used to play MP3 audio files. The MP3 player has a progress bar and time display during playback.

{| cellpadding="3"
|-
| [[File:sl_preview_ui_play.png]]
| Plays the MP3 audio file.
|-
| [[File:sl_preview_ui_pause.png]]
| Pause the play.
|-
| [[File:sl_preview_ui_stop.png]]
| Stops the play.
|-
| [[File:sl_preview_ui_backward.png]]
| Move the play cursor backward.
|-
| [[File:sl_preview_ui_forward.png]]
| Move the play cursor forward.
|-
| [[File:sl_preview_ui_copy_location.png]]
| Copy subject locator URI to system clipboard.
|-
| [[File:sl_preview_ui_open_ext.png]]
| Open the subject locator URI with external application registered to handle MP3 files.
|-
| [[File:sl_preview_ui_save_as.png]]
| Save subject locator resource to local file system as a MP3 file.
|}

=== Image ===

Image views general images. User can zoom, copy and print the image, for example.

{| cellpadding="3"
|-
| [[File:sl_preview_ui_zoom_in.png]]
| Zoom in the image.
|-
| [[File:sl_preview_ui_zoom_out.png]]
| Zoom out the image.
|-
| [[File:sl_preview_ui_reset_size.png]]
| Reset image size. Image is viewed in an original size.
|-
| [[File:sl_preview_ui_copy_image.png]]
| Copy subject locator image resource to system clipboard.
|-
| [[File:sl_preview_ui_copy_location.png]]
| Copy subject locator URI to system clipboard.
|-
| [[File:sl_preview_ui_open_ext.png]]
| Open the subject locator URI with external application registered to handle image files.
|-
| [[File:sl_preview_ui_save.png]]
| Save subject locator resource to a local image file.
|-
| [[File:sl_preview_ui_print.png]]
| Print subject locator resource image.
|}

=== ApplicationPDF ===

ApplicationPDF views PDF resources. PDF options include PDF navigation and view zooming.

{| cellpadding="3"
|-
| [[File:sl_preview_ui_first_page.png]]
| View first page in PDF document.
|-
| [[File:sl_preview_ui_previous_page.png]]
| View previous page in PDF document.
|-
| [[File:sl_preview_ui_next_page.png]]
| View next page in PDF document.
|-
| [[File:sl_preview_ui_last_page.png]]
| View last page in PDF document.
|-
| [[File:sl_preview_ui_zoom_in.png]]
| Zoom in the PDF preview.
|-
| [[File:sl_preview_ui_zoom_out.png]]
| Zoom out the PDF preview.
|-
| [[File:sl_preview_ui_copy_image.png]]
| Copy current page of PDF document to system clipboard.
|-
| [[File:sl_preview_ui_copy_location.png]]
| Copy subject locator URI to system clipboard.
|-
| [[File:sl_preview_ui_save.png]]
| Save subject locator resource to a local file.
|}

=== TextRTF ===

TextRTF views RTF (Rich Text Format) formatted text files.

{| cellpadding="3"
|-
| [[File:sl_preview_ui_copy_location.png]]
| Copy subject locator URI to system clipboard.
|-
| [[File:sl_preview_ui_open_ext.png]]
| Open the subject locator URI with external application registered to handle image files.
|-
| [[File:sl_preview_ui_save.png]]
| Save subject locator resource to a local image file.
|}

=== TextHTML ===

TextHTML is a generic web viewer. It contains a web browser and a set of buttons to control the web view and the subject locator. The web viewer uses and requires JavaFX. Next list describes the preview buttons.

{| cellpadding="3"
|-
| [[File:sl_preview_ui_reload.png]]
| User can leave the web page addresses by the subject locator URL. Reload button is used to reopen the subject locator URL.
|-
| [[File:sl_preview_ui_open_ext.png]]
| Open the subject locator URL with external application registered to handle URLs.
|-
| [[File:sl_preview_ui_copy_location.png]]
| Copy subject locator URI to system clipboard.
|-
| [[File:sl_preview_ui_copy_selection.png]]
| Copy selected text to system clipboard.
|-
| [[File:sl_preview_ui_copy_image.png]]
| Copy preview to system clipboard.
|-
| [[File:sl_preview_ui_save_as.png]]
| Save subject locator resource to a local file.
|-
| [[File:sl_preview_ui_set_basename.png]]
| Selected text is set as topic's basename.
|-
| [[File:sl_preview_ui_set_display_name.png]]
| Selected text is set as topic's display name.
|-
| [[File:sl_preview_ui_set_occurrence.png]]
| Selected text is set as topic's occurrence.
|}

=== ApplicationXML ===

ApplicationXML contains a text area and buttons to control the preview and the subject locator.

{| cellpadding="3"
|-
| [[File:sl_preview_ui_copy_location.png]]
| Copy subject locator URI to system clipboard.
|-
| [[File:sl_preview_ui_open_ext.png]]
| Open the subject locator URI with external application registered to handle the resource.
|-
| [[File:sl_preview_ui_save.png]]
| Save subject locator resource to a local file.
|}

=== Text ===

Text contains a scrollable text area and buttons to control the text area and the subject locator. The user can not edit the text in the text area. Selection and copy is allowed. Next image views an example of the text area.


[[File:sl_preview_text_view.png|center]]


Available options to control the preview and subject locator follow


{| cellpadding="3"
|-
| [[File:sl_preview_ui_copy_location.png]]
| Copy subject locator URI to system clipboard.
|-
| [[File:sl_preview_ui_open_ext.png]]
| Open the subject locator URI with external application registered to handle the resource.
|-
| [[File:sl_preview_ui_save.png]]
| Save subject locator resource to a local file.
|}

=== VideoMp4 ===

Wandora uses VideoMp4 to view subject locator resources that are MP4 resources, for example. The view contains a video, progress bar and several buttons to control the video and the subject locator. The preview is based on and requires JavaFX. Next image views an example of video area.


[[File:sl_preview_mp4_view.png|center]]


Available buttons to control the video and the subject locator are


{| cellpadding="3"
|-
| [[File:sl_preview_ui_play.png]]
| Play media resource.
|-
| [[File:sl_preview_ui_pause.png]]
| Pause playing the media resource. Play continues by pressing the pause button again or by pressing the play button.
|-
| [[File:sl_preview_ui_stop.png]]
| Stop playing the media resource. Stopping play restores play cursor to the beginning to media resource.
|-
| [[File:sl_preview_ui_backward.png]]
| Move the play cursor backward. Pressing the backward button has effect only if the media resource is being played.
|-
| [[File:sl_preview_ui_forward.png]]
| Move the play cursor forward. Pressing the forward button has effect only if the media resource is being played.
|-
| [[File:sl_preview_ui_restart.png]]
| Restart playing the media resource.
|-
| [[File:sl_preview_ui_copy_location.png]]
| Copy subject locator URI to system clipboard.
|-
| [[File:sl_preview_ui_open_ext.png]]
| Open the subject locator URI with external application registered to handle media file.
|-
| [[File:sl_preview_ui_save_as.png]]
| Save subject locator resource to a local file.
|}

=== ApplicationZMachine ===

ApplicationZMachine is used to view interactive fiction games created for the [https://en.wikipedia.org/wiki/Z-machine Z machine]. The view includes a game window and few buttons to control the view and subject locator.

{| cellpadding="3"
|-
| [[File:sl_preview_ui_preferences.png]]
| Open preferences dialog of Z machine player. Preferences dialog is used to set font sizes, background and foreground colors, and antialising of text. Preferences changes take effect after game restarts. Game restarts if subject locator preview is toggled off and on.
|-
| [[File:sl_preview_ui_copy_location.png]]
| Copy subject locator URI to system clipboard.
|-
| [[File:sl_preview_ui_open_ext.png]]
| Open the subject locator URI with external application registered to handle media file.
|-
| [[File:sl_preview_ui_save.png]]
| Save subject locator resource to a local file.
|}

== Additional notes ==

* Some preview players can't view (play) a data URI resources directly. These preview players save the data URI resource into a local file and view (play) the local file. These temporary files are stored in computer's default temporary directory. Temporary files are deleted when Wandora application is closed.
* Java has security limitations that prevent the user to open data URIs with system's default application.