CBX_Handler: Comic Book Reader

Note: This script requires Opus 11.16 or above.

This script was written in response to a request from JoePerkins in the following discussion, but then further updated to meet my own needs and wants as well as some I 'think' other people might appreciate:

Button to change preferences option (CBR/CBZ)

What does it do?:

This script was initially written to provide an Opus user with the ability to override the default image viewing application settings for regular images (usually jpg) while inside of comic archives - in the case that the Opus internal picture viewer is NOT set as the default image handler. Leo graciously, quickly and succinctly offered up a script to do just that. From there - being familiar with digital comics archives, and having a tendency to over complicate things - I took it a step further and made a script to treat common Comic Book Archive formats (configurable as an option - but usually ZIP or RAR archives, though I've seen some 7-zip as well) as 'Comic Books' as opposed to just 'archives'.

What does that mean...? CBX_Handler allows you to double-click on a comic archive, and as long as Opus is already configured to treat such extensions as archives (todo: add a link to a forum topic that actually describes how to do this), the script will automatically launch the images inside the archive in the Opus internal picture viewer.

There are still good reasons to use dedicated apps out there though (like CDisplay Ex), because as digital comics have become more mainstream they've gotten fancier in the experience they offer. Dedicated apps are updated to take advantage of the kind of whiz-bang features of newer digital comics like animation, but also offer nice features like color enhancement of older washed out or blandly colored images, and other things. This script will NOT aim at addressing those needs, but there are a LOT of 'plain' comic archives out there that ~just contain images. So this script caters to users who just want a light-weight way of getting Opus to show those images in the internal picture viewer easily and quickly for basic comic book archive files.

How to install and use it?:

The script is provided here as an Opus Script Package... which in turn is actually a zip file with a VBScript packaged inside. It can be installed by either manually copying the OSP file to the /dopusdata\Script AddIns folder, or via drag-and-drop into the Preferences / Toolbars / Scripts page.

Download: CBX_Handler.osp (4.36 KB)


After installing the script package, users can configure the scripts options via the scripts listing in Prefs (Configure button):

There are various options to control how the script behaves, described immediately below:

How does it work?:

CBX_Handler is implemented as a DoubleClick 'Event Handler'. When you double click on files and folders in Opus, the script will run and check to see if it's supposed to go any further... This means it checks to see if it is 'enabled' for use in any of the variety of ways the script can be configured. It also checks to see if the item you've double clicked on is one of the file extensions that the script is configured to handle. Here is a description of each of the script configuration options shown in the screenshot above:

  • Always_On: Set this option to True in order to enable script execution without the use of environment variables or qualifier keys.
  • Archive_Ext_List: This option lets you specify the list of comic archive file extensions you want the script to handle.
  • DEBUG: Set this option to True to enable logging to the Opus script log. Not currently used in this script...
  • DEBUG_CLEAR: Set this option to True clear messages logged to the Opus script log between script runs. Not currently used in this script...
  • Default_Action: Set this option to the default Opus command that should be run if the QualKey_Disable option is used.
  • Image_Ext_List: This option lets you specify the list of image file extensions you want the script to handle inside archives.
  • QualKey: Set this option to the qualifier key that you want to ENABLE the scripts execution.
  • QualKey_Disable: Set this option to the qualifier key that you want to DISABLE the scripts execution.
    By default, installing this script will cause images to automatically load in the Opus internal picture viewer after double-clicking on any of the file extensions configured in the Archive_Ext_List option (you can see the default extensions in the screenshot above are CBR, CBZ, CB7, and ZCB).

However, if you DON'T want that to happen, you can set these options to give you alternate ways of controlling when the script does it's job. For instance, with the Always_On option left at the default 'True' value, you could then configure the QualKey option and set it to ctrl. This would cause it to only automatically open the images in the Opus picture viewer when double-clicking on the configured archive extensions when you also hold the CTRL key down. Alternatively, you could set the Always_On option to 'False' and instead use a toolbar button or hotkey such as the following sample button to toggle an environment variable (cbx_handler) the script can look for to determine if it should do it's job or not...

Here is a sample toolbar button that toggles the lister scoped variable (the script supports tab, lister or global scoped variables) which you can copy and paste directly to your toolbar:

<?xml version="1.0"?>
<button backcol="none" display="both" label_pos="right" textcol="none">
	<function type="normal">
		<instruction>@toggle:if $glob:cbx_handler</instruction>
		<instruction />
		<instruction>@set glob:cbx_handler</instruction>
		<instruction />
		<instruction>@set glob:cbx_handler=true</instruction>

On the other hand, if you DO think you'll most always want the script to open comic archives as comics, and auto load the images into the viewer upon double-click of the archive... but think you might sometimes still want or need to open the archives and browse inside of them, you can leave the Always_On option set to 'True', but set the QualKey_Disable option to a hotkey to DISABLE the script from doing it's job. This is how I use it myself, where I've set the QualKey_Disable option to ctrl. Use of the QualKey_Disable option causes Opus to then run the action defined in the Default_Action option. I expect most people will leave this at the default action of 'Go FROMSEL'. I had to do this because without an explicit command to run instead of the script doing it's normal job of opening the images, the script would simply exit and Opus would act the way it normally would on double-click with the qualifier key (again, mine set to ctrl); and on MY system I have Opus to open archives in a new background tab when Ctrl+Double-Clicked. Since I wanted the script to treat QualKey_Disable based double-clicks in the same way as if you had double-clicked WITHOUT a qualifier key, I had to explicitly run the desired regular command. As a side effect, this means that you could sort of ~abuse this option to run some other 'alternate' action when using the QualKey_Disable option, for instance - maybe you DO have fancy new comic archives and want Shift+Double-Click to run a dedicated comic archive reader...

In addition to the options already described, you can also modify the list of file extensions for both the type of Comic Book Archives the script will handle as well as the type of images INSIDE the archives the script will show in the Opus viewer. I had to define them inside the script, so it made sense to just expose them as configurable options... however, you should realize that Opus must first be able to:

A. treat the ARCHIVE extension as an archive...
B. Display the IMAGE extension as an image...

In other words, the script doesn't ADD additional ARCHIVE or IMAGE support to Opus...

Lastly, in the case you have disabled the script using some combination of the options described so far, and you open let's say one of your CBR files as an archive and are browsing the files inside it, Leo's original code is still in effect. So back to the ORIGINAL request, if you are browsing inside a comic archive and double-click on one of the JPG's in there it will open in Opus' internal picture viewer even if you have JPG files set to open by default in some other application like IrfanView or something... This behavior is ALSO disabled by the QualKey_Disable option however, so if you use the qualifier key set for this option while double-clicking on JPG files after opening the archive for browsing in the file display, it will be opened by the default image viewer (FYI that what actually happens will be subject to however that default application behaves when whatever qualifier key you double-clicked with is used).

Feedback appreciated - and HAPPY NEW YEAR - 2016!


  • 2015-12-25: Initial release... posted to the forum thread above
  • 2016-01-01: v1.2.0 - This update changes the name from Leo's original 'ShowForComics' to CBX_Handler, and provides a bunch of options to control whether or not the script does it's job for cases where you still want to open the file as an archive rather than a comic book. I also added a 'Default Action' so that users with yet other preferences than either my own or even the original users goals want something 'else to happen than the images opening inside Opus' internal picture viewer. More on script options below...
  • 2016-01-02: v1.2.1 - Quick update to workaround a problem where double-clicking on some objects (Drives under 'Computer', the FTP and Libraries nodes under 'Desktop') would cause the VBScript engine to throw an error
  • 2016-02-18: v1.2.3 - Quick update to workaround a problem where archives in non-library paths were not being auto opened in the viewer, and adjusted debug log settings.
  • 2016-11-22: v1.2.7 - Quick update to workaround a problem where double-clicking archives would sometimes not produce any action at all.

Worth noting: as those of us who are familiar may know, some comics archives you download may contain a sub-folder before any images. It's somewhat common, and so CBX_Handler looks for this and can handle it. However, in the case where there is a folder and anything else at the root of the archive, CBX_Handler will default back to the Default_Action described above since it's tough to say what the "right" thing to do would be. I decided the most "sensible" thing would be to just open the archive like a folder and let the user do what they want once they know what's going on inside the archive.

Posted a small update to resolve an error caused by double-clicking on certain objects like Drives under 'Computer', and the FTP and Libraries nodes under 'Desktop'.

A minor update to correct a problem where dbl-clicking on comic archives in paths other than library paths would open the archive as a folder rather than auto launch the viewer.

Also adjusted default debug log settings...

This is fantastic :slight_smile:

Is it possible to have the script force the viewer into fullscreen without having to set the default view to fullscreen? I want the viewer in windowed for most applications, but I would always view comics fullscreen.

If only it could display two images side-by-side... :stuck_out_tongue:

Wonderful. Thank you. :smiley:
For some reason I never got the hang of ComicRack. This works much better for me.

EDIT: Added to the sample list of scripts on my page about scripts, which I need to update by looking at what other cool stuff has come out.

I've been super busy with work, but will post an update for this soon.

@newguy... it's possible doing two pages at the same time is possible. At a minimum though I think it would require disabling the 'Recycle viewer window' option in Prefs, and I'm not clear how you would advance BOTH viewer windows in any sort of synchronized fashion. Perhaps something in the Opus 12 updates with respect to the picture viewer customization features (YAAAAAAAAAAY) would help there... I will review.

A little update to fix an issue where sometimes nothing would happen when dbl-clicking on comic archives.

Haven't looked into whether or not anything new in v12 might help achieve looking at two pages at the same time, but will investigate soon.


Reviving an older thread...

I realize it was requested before for the viewer to open in full screen. Is there a way to toggle this option off? Or how can I modify the script so that it works like that for me without having to change the posted one?


There's a fullscreen option in the script's config dialog (via Preferences / Toolbars / Scripts):

I honestly don't know how I missed that when I went through it :man_facepalming:

As always,

Thanks very much!

I found really what I was looking for to handle CBX.. you read my mind .. .4 years before :rofl:

Just one request:
Would it be possible to have double page on the viewer??

I know I can have specifiv viewer, but Dopus viewer is so fast that I wanted to avoid to use an external one. Thanks for any suggestion.

Not using the built-in viewer, unless the script joined each pair of pages into a single image and then told the viewer to display those instead of the original file. That would be possible but might slow things down a bit, and could also be done by pre-processing the CBX files into that state (while keeping the originals, of course!).

There is a viewer plugin API which can do almost anything, but would require custom code writing which is a lot more complex than the current script.

1 Like

I continue to test things with this tool and found something cumbersome.
As you know sometimes in a cbr/cbz file there is a directory.
Then the viewer has to go inside this directory to show images.
This is working fine with the plugin, except in one situation..
As you know there are library software creating an xml or txt file INSIDE the cbr/cbz file to help to index it.
One common file is ComicInfo.xml
these files are created a the first level of the cbz/cbr file. Then you find a ComicInfo.xml with just a directory were are all the images.
PROBLEM: If there is a file, cdx don't show images, it just open as a directory.
Any sugestion for "everytime it is cbr/cbz file, forget the directory structure.. just show the images".
Thanks for any suggestion

One possible solution would be to automate dopus to look for all cbr/cbz files, extract the inside directory into the root of the cbr/cbz file. But I don't know how to do it. Sure someone has a trick to do it with DOPUS. :wink:

1 Like