Updated 2012-05-25 12:54:59 by ABU

ABU 25-may-2012

qblx is a specialized widget designed for viewing and interacting with images in a curios and bizarre way.

Qblx is just a widget, but you can play with a simple demo-app provided within the package.

  • Download [1]

qblx 1.0 qblx Quadratic-Blocks

Quadratic-Blocks - a bizarre widget for interacting with images

SYNOPSIS edit

package require Tk 8.5

package require qblx ?1.0?

  • qblx pathName ?option value...?
  • pathName cget option
  • pathName configure ?option? ?value option value ...?
  • pathName load filename ?option value...?
  • qblx default ?-sidelength N? ?-framecolor color?
  • pathName save filename ?option value ...?
  • pathName reset
  • pathName refresh
  • pathName query ?what?
  • pathName counters
  • qblx keybindings
  • qblx keybindings virtual-event
  • qblx keybindings virtual-event event-sequence

DESCRIPTION edit

qblx is a specialized widget designed for viewing and interacting with images in a curios and bizarre way. Within a qblx widget an image is recursively subdivided in square blocks. Each group of 2x2 pixel is merged in a block, each group of 2x2 blocks is merged in a larger block, and so on recursively. At the top the original image is rendered just as a single uniform-color block. When user moves the cursor in a block, it is splitted in four sub-blocks, and so on recursively. On the contrary, just by pressing the shift-key and moving the cursor, user can join four sub-blocks in a larger block. That's all about it. Split & Join ! Qblx is just a widget, but you can play with a simple demo-app provided within the package. The qblx command creates the pathName widget and returns a new Tcl command whose name is pathName.
qblx pathName ?option value...?

STANDARD OPTIONS edit

-bg
Specifies the normal background color to use when displaying the widget.

WIDGET-SPECIFIC OPTIONS edit

-gridcolor
Specifies the color used for the thin grid surrounding each block. Default is gray20
-lowest
Specifies a non negative integer for the lowest splittable layer. Only blocks over this layer can be splitted. Set it to zero for revealing the bottom layer (i.e. the original-image layer) Default is 1
-join
Specifies the minimum number of full sub-blocks for joining. It can 2,3 or 4. Default is 3 (i.e when 3of4 sub-blocks are full, these sub-blocks and the 4th incomplete sub-block are merged in a larger block).
-zoom
Specifies a positive integer used for enlarging the whole image. Be careful that large zoom values with large images may produce some not-enough-memory errors. In general, since this widget has no scrolling capabilities (unnecessary?), it is useless to play with a zoomed image larger than the screen Default is 2.
-animationdelay
Specify a non negative integer used for setting a delay (in millisecs) between two frames in animations. Default is 50 millisecs.

WIDGET COMMANDS edit

The qblx command creates a widget and a new Tcl command whose name is pathName. This command may be used to invoke various operations on the widget. It has the following general form:
pathName subCommand ?arg ...?
The following subCommands are possible for qblx widgets:
pathName cget option
Returns the current value of the configuration option given by option. Option may have any of the values accepted by the qblx command.
pathName configure ?option? ?value option value ...?
Query or modify the configuration options of the widget. If no option is specified, returns a list describing all of the available options for pathName (see Tk_ConfigureInfo for information on the format of this list). If option is specified with no value, then the command returns a list describing the one named option (this list will be identical to the corresponding sublist of the value returned if no option is specified). If one or more option-value pairs are specified, then the command modifies the given widget option(s) to have the given value(s); in this case the command returns an empty string. Option may have any of the values accepted by the qblx command.
pathName load filename ?option value...?
Loads an image from filename. The file format must be one of those for which there is an image file format handler that can read data (package Img or similar should be preloaded). The following options may be specified:
-sidelength N
N must be a power of two (default is 256). Image from filename is cropped or framed with a uniform-color border so that only a square image of NxN pixel is loaded.
-framecolor color
When image in filename is smaller than NxN (see ?-sidelength? option), it is centered in a NxN image and surrounding pixels are filled with color (default is black). You can query/change these defaults with the following command
qblx default ?-sidelength N? ?-framecolor color?
pathName save filename ?option value ...?
Saves the current image in filename. filename must have a suffix recognized by a format-handler of the photo command, or you can explicitely specify the format handler adding -format format-name option. All options of the [imageX write ..] command may be used.
pathName reset
All the splitted blocks are restored to full-blocks.
pathName refresh
Redraws the image (just in case it is damaged)
pathName query ?what?
Returns information about the state of the widget
pathName query layers
Returns the number of layers
pathName query blocks layer
Returns a list of two integers: total number of blocks on layer, number of full blocks on layer
pathName counters
Returns the name of public array holding the number of full blocks on each layer. Array indexes are from 0 to N-1 (N is number of layers). as returned by [pathName query layers] . Note that the number of full blocks on each layer can also be obtained by [pathName query blocks layer] command, but this method provides the name of an array continuously updated, thus usable for some sort of tracing (see demos included with the package)

KEY BINDINGS edit

Qblx's default key-bindings for splitting and joining blocks may be changed with the following commands:
qblx keybindings
Returns a list of virtual-events used for splitting/joining blocks. Currently these are <<Qblx.Split>> <<Qblx.Join>>
qblx keybindings virtual-event
Returns the event-sequence associated with one of the above listed virtual-events.
qblx keybindings virtual-event event-sequence
Changes the event-sequence associated with one of the above listed virtual-events.

EVENTS edit

Qblx generates virtual-events every time a block is splitted or merged. These virtual-events carry some data that may be caught in binding script by the %d substitution keyword. These are the generated events along with data they carry:
<<BlockSplitting>> layer xIndex yIndex
<<BlockSplitted>> layer xIndex yIndex
<<BlockMerging>> layer xIndex yIndex
<<BlockMerged>> layer xIndex yIndex
These events will be generated before/after a block is splitted/merged. The three parameters are: the layer's index and the two block's indexes: x-index and y-index.
<<BlockAnimationStopped>> layer xIndex yIndex
Sometimes an animation can be be started (and then signalled by <<BlockSplitting>> or <<Block.Merging>>) and then stopped by some operation (such as reset or a super-block merging). In these cases the <<BlockAnimationStopped>> event is generated.
<<EmptyLayer>> layer
This event will be generated when the last full block of a layer has been splitted
<<LastEmptyLayer>> layer
This event will be generated when the lowest layer (see -lowest option) -and therefore all layers above- is empty.
<<FullLayer>> layer
This event will be generated when a layer is full.
<<LastFullLayer>> layer
This event will be generated when the top layer is full.

More on Blocks and Layers. edit

Once an image is loaded, it is first cropped/enlarged to a QxQ square image, where Q is a power of two (Q=2**N). and then stored on the bottom Layer-0.

  • Layer-0 is made of 2**N x 2**N blocks each one representing 1x1 pixels.
  • Then Layer-1 is computed by grouping blocks of 2x2 pixels.
  • Layer-1 is made of 2**(N-1) x 2**(N-1) blocks each one representing 2x2 pixels.
  • and so on till the top Layer-N
  • Layer-N is made of 2**(N-N) x 2**(N-N), that is just 1 block representing 2**N x 2**N pixels. Therefore on Layer-N there's only block whose indexes are (0,0), whilst on Layer-(N-1) there are 2x2 blocks indexed as (0,0) (0,1) (1,0) (1,1). Don't confuse block's indexes with block's coordinates.

BUGS, IDEAS, FEEDBACK edit

  • Being a pure tcl app, some operations are slow; in particular "reset" and "refresh" should be coded in C
  • add sounds to split/join events
  • Qblx has been ispired by Vadim Ogievetsky's work on http://www.koalastothemax.com/

KEYWORDS edit

Snit, widget

COPYRIGHT edit

 Copyright (c) 2012, by A.Buratti