The `carousel` Widget

by

Trevor Williams

phase1geo@gmail.com

Reference

NAME

carousel::carousel - Create and manipulate carousel widgets

SYNOPSIS

carousel::carousel pathName ?options?

STANDARD OPTIONS

-background or -bg
-borderwidth or -bd
-cursor
-height
-relief
-state
-takefocus
-width
-xscrollcommand

WIDGET-SPECIFIC OPTIONS

-animate value
-padx pixels
-pady pixels
-reflect saturation
-reflectblur saturation

pathName bind
        index ?sequence? ?script?

pathName cget
        option

pathName configure
        ?option? ?value? ?option value ...?

pathName delete
        first ?last?

pathName index
        index

pathName insert
        index type ?options?

pathName itemcget
        index option

pathName itemconfigure
        index ?option? ?value? ?option value ...?

pathName setcurrent
        index

pathName size

pathName xview 
          args

pathName xview

pathName xview moveto fraction

pathName xview scroll number what

OVERVIEW OF ITEM TYPES

COMMON ITEM OPTIONS

-ratio ratio
-dash pattern
-dashoffset offset
-fill color
-outline color
-offset offset
-outlinestipple bitmap
-outlineoffset offset
-stipple bitmap
-state state
-width outlineWidth

IMAGE ITEM

-image image

Detailed Reference

NAME

carousel::carousel - Create and manipulate carousel widgets

SYNOPSIS

carousel::carousel pathName ?options?

STANDARD_OPTIONS

-borderwidth
-cursor
-font
-relief
-state
-takefocus
-variable

See the options manual entry for details on the standard options.

WIDGET-SPECIFIC OPTIONS

Command-Line Name:	`-animate`
Database Name:	`animate`
Database Class:	`Animate`

If set to a boolean value of true, adds some small animations to the carousel when items are rotated. If set to a boolean value of false, no additional animations are made. The animations help give the carousel a more fluid look. Defaults to true.

Command-Line Name:	`-padx`
Database Name:	`padX`
Database Class:	`Pad`

Specifies the amount of horizontal padding (in pixels) between the current item and the items to the left and right of the current item. This padding value is also used to calculate the number of horizontal pixels between the outer edges of the other displayed items.

Command-Line Name:	`-pady`
Database Name:	`padY`
Database Class:	`Pad`

Specifies the amount of vertical padding (in pixels) between the current item and the top and bottom edges of the widget.

Command-Line Name:	`-reflect`
Database Name:	`reflect`
Database Class:	`Reflect`

If this option is set to a value greater than 0, turns on reflections and the value (fraction within the range of >0 to 1) specifies the amount of saturation in the reflection. The lower the value, the more subtle the reflection. A value of 1.0 will essentially create an inverted copy of the original image beneath the displayed item. A value of 0 will disable reflections. Default is 0.2.

Command-Line Name:	`-reflectblur`
Database Name:	`reflectBlur`
Database Class:	`ReflectBlur`

Specifies the amount of reflection blurring that should occur. A value of 0 is no blur while a value of 1 is complete blurring. The default is 0.5. This option is only valid if the -reflect option is set to a value greater than 0.

DESCRIPTION

The carousel::carousel command creates a new window named pathName and of the class Carousel, and makes it into a carousel widget. Additional options, described above, may be specified on the command-line or in the option database to configure aspects of the carousel. The carousel::carousel command returns its pathName argument. At the time this command is invoked, there must not exist a window named pathName, but pathName's parent must exist.

The carousel widget is a widget that displays a linear list of images in a 3-D view, allowing the user to rotate through the images. A single item in the list is considered the "current" item which is displayed in the center of the widget and in a larger view. The developer can bind any number of sequences and scripts to this image to do interesting things. The user can switch between items in the carousel by using a scrollbar (or some other developer-defined control) or by left-clicking on displayed items. The latter will cause the clicked item to immediately become the current item.

INDICES

Carousel items are identified by an index which represents its position in the list. The following forms of index can be used in the commands.

number: A decimal number giving the position of the desired item wihin the carousel. 0 refers to the first item, 1 the next item to the right in the carousel and so on. A number less than 0 is treated as zero, and a number greater than the length of the carousel is treated as if it were equal to the length of the carousel.
number+number: Adds the second number to the first number. If the resulting value is equal to or greater than the index last item of the list, value is treated as the last item of the carousel.
number-number: Subtracts the second number from the first number. If the resulting value is less than 0, value is treated as zero.
current: Specifies the index of the item that is displayed in the middle of the carousel display. This item is the only item that can respond to user-supplied events/interractions.
end: When inserting, specified the position past the last item of the carousel. In all other cases, specifies the position of the last item of the carousel.
end-number: Specifies the number'th item to the left of the last item in the list. If the resulting position is less than 0, value is treated as zero.
@x,y: Refers to the coordinate of the point given by x and y, where x and y are specified in the coordinate system of the carousel.

DASH PATTERNS

Some items support the notion of a dash pattern for outlines.

The first possible syntax is a list of integers. Each element represents the number of pixels of a line segment. Only the odd segments are drawn using the "outline" color. The other segments are drawn transparent.

The second possible syntax is a character list containing only 5 possible characters ".,-_ ". The space can be used to enlarge the space between other line elements, and cannot occur as the first position in the string. Some examples:

        -dash .    → -dash {2 4}
        -dash -    → -dash {6 4}
        -dash -.   → -dash {6 4 2 4}
        -dash -..  → -dash {6 4 2 4 2 4}
        -dash {. } → -dash {2 8}
        -dash ,    → -dash {4 4}

The main difference of this syntax with the previous is that it is shape-conserving. This means that all values in the dash list will be multiplied by the line width before display. This assures that "." will always be displayed as a dot and "-" always as a dash regardless of the line width.

On systems which support only a limited set of dash patterns, the dash pattern will be displayed as the closest dash pattern that is available. For example, on Windows only the first 4 of the above examples are available. The last 2 examples will be displayed identically to the first one.

WIDGET COMMANDS

The carousel::carousel command creates 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 option ?arg arg ...?

option and the arg determine the exact behavior of the command. The following commands are possible for carousel widgets:

pathName bind index ?sequence? ?script?

If this command is called with on index, returns a list containing all of the sequence-script combinations currently bound to the indexed item. If the sequence option is specified without the script option, the script associated with the specified sequence for the indexed item is returned. If script is set to the empty string, the currently assigned script for the sequence for the indexed item is deleted. If script is not the empty string, the specified script is associated with the sequence for the indexed item. If a plus (+) character is placed prior to the script, the script will be appended to the current script associated with the indexed item.

The sequence-script pairs are only bound to the indexed item when the item becomes the "current" item in the widget.

pathName cget option

Returns the current value of the configuration option given by option.

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.

pathName delete first ?last?

Deletes one or more items from the carousel. If last is not specified, a single item is deleted at index first. If last is specified, the range of items between first and last are deleted, inclusive.

pathName index index

Returns the numeric index of the given index in the carousel.

pathName insert index type ?options?

Inserts a new item into the carousel list at the given index. The type and options specify the item type to insert and the options to pass to the item. See ITEM TYPES for available type and associated options values.

pathName itemcget index option

Retrieves the value associated with option for the item in the index position in the carousel. If option is not a valid option for the specified item, an empty string will be returned.

pathName itemconfigure index ?option? ?value? ?option value ...?

Query or modify the configuration options for the item at the index position of the carousel. If no option is specified, returns a list describing all of the available options for the item at the index position (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 not option is specified). If one or more option-value pairs are specified, then the command modifies the given item option(s) to have the given value(s); in this case the command returns the empty string. See ITEM TYPES for available option values.

pathName setcurrent index

Sets the current item in the carousel to the item at the index position. If the value of index is less than 0, the current item is set to the first item. If the value of index is greater than or equal to the number if items in the carousel, the current item is set to the last item. An error will be generated if the user attempts to set the current item to an item in the hidden state.

pathName size

Returns the number of items stored in the carousel.

pathName xview args

This command is used to query and change the horizontal position of the information in the widget's window. It can take any of the following forms:

pathName xview: Returns a list containing two elements. Each element is a real fraction between 0 and 1; together they describe the horizontal span that is visible in the window. For example, if the first element is .2 and the second element is .6, 20% of the carousel's items are off-screen to the left, the middle 40% is visible in the window, and 40% of the items are off-screen to the right. The fractions refer only to the items that are actually visible in the window: if the items all fit in the window, so that they are entirely visible, the returned fractions will be 0 and 1. These are the same values passed to scrollbars via the -xscrollcommand option.
pathName xview moveto fraction: Adjusts the view in the window so that fraction of the items are off-screen to the left. Fraction is a fraction between 0 and 1.
pathName xview scroll number what: This command shifts the view in the window left or right according to number and what. What must be units or pages and number must be an integer. If what is units, the view adjusts left or right by number of items on the display; if it is pages then the view adjusts by number screenfuls. If number is negative then items farther to the left become visible; if it is positive then items farther to the right become visible.

OVERVIEW OF ITEM TYPES

When creating a new carousel item, a type argument is required to specify the type of item to add to the carousel. Each type has associated options that can be specified. The following describes the valid types and options.

COMMON ITEM OPTIONS

Some items share a common set of options. These options are explained here, and then referred to for each type for brevity.

-ratio ratio: Specifies the width-to-height ratio to use when drawing the rectangle and oval item types. To calculate the correct value to use, use the following expression: [expr $item_width / $item_height.0]. This option will default to a value of 1 (will have the effect of drawing a square or a circle if the rectangle or oval item type is specified, respectively).
-dash pattern: This option specifies dash patterns for an item. pattern may have any of the forms as specified in DASH PATTERNS. If the dash options are omitted then the default is a solid outline.
-dashoffset offset: The starting offset in pixels into the pattern provided by the -dash option. -dashoffset is ignored if there is no -dash pattern. The offset may have any of the forms described in the COORDINATES section above.
-fill color: Specifies the color to be used to fill item's area. Color may have any of the forms accepted by Tk_GetColor. If color is an empty string (the default), then the item will not be filled.
-outline color: This option specifies the color that should be used to draw the outline of the item. Color may have any of the forms accepted by Tk_GetColor. This option defaults to black. If color is specified as an empty string then no outline is drawn for the item.
-offset offset: Specifies the offset of stipples. The offset value can be of the form x,y or side, where side can be n, ne, e, se, s, sw, w, nw, or center. In the first case the origin is the origin of the toplevel of the current window. For the canvas itself and canvas objects the origin is the canvas origin, but putting # in front of the coordinate pair indicates using the toplevel origin instead. For canvas objects, the -offset option is used for stippling as well.
-outlinestipple bitmap: This option specifies stipple patterns that should be used to draw the outline of the item. Indicates that the outline for the item should be drawn with a stipple pattern; bitmap specifies the stipple pattern to use, in any of the forms accepted by Tk_GetBitmap. If the -outline option has not been specified then this option has no effect. If bitmap is an empty string (the default), then the outline is drawn in a solid fashion. Note that stipples are not well supported on platforms that do not use X11 as their drawing API.
-outlineoffset offset: Specifies the offset of the stipple pattern used for outlines. The offset value can be of the form x,y or the description of a side (one of n, ne, e, se, s, sw, w, nw, or center). This option only has an effect when the outline is drawn as a stipple pattern, and is only supported under X11.
-stipple bitmap: This option specifies stipple patterns that should be used to fill the item. bitmap specifies the stipple pattern to use, in any of the forms accepted by Tk_GetBitmap. If the -fill option has not been specified then this option has no effect. If bitmap is an empty string (the default), then filling is done in a solid fashion. Note that stipples are not well supported on platforms that do not use X11 as their drawing API.
-state state: Each item can be manually placed into one of three states: normal, disabled or hidden. If the item is placed into the normal state, the item will be displayed in the carousel, its user-defined bindings will be usable, and the normal option values apply. If the item is placed in the disabled state, the item will be displayed in the carousel, and its user-defined bindings will be disabled. If the item is placed in the hidden state, the item will not be displayed in the carousel. Hidden items will not be able to be set to the current item.
-width outlineWidth: Specifies the width of the outline to be drawn around the item's region. outlineWidth may be in any of the forms described in the COORDINATES section above. If the -outline option has been specified as an empty string then this option has no effect. This option defaults to 1.0. For arcs, wide outlines will be drawn centered on the edges of the arc's region.

IMAGE ITEM

Items of type image are used to display images in the carousel. Images are created with the following widget command:

  pathName insert index image options

After the coordinates there may be any number of option-value pairs, each of which sets one of the configuration options for the item. These same option-value pairs may be used in itemconfigure widget commands to change the item's configuration. An image item becomes the current item when it is displayed in the center (magnified) of the carousel widget.

The following standard options are supported by images:

  -state

The following extra options are supported for images:

-image name: Specifies the name of the images to display for the item. This image must have been created previously with the image create command. The image will be managed by the carousel and automatically deleted (when the carousel is destroyed).

The width/height ratio of the image will be maintained within the widget, scaled appropriately as determined by the position and width/height of the carousel widget itself.

RECTANGLE ITEM

Items of type rectangle appear as square or rectangular regions in the carousel. Each rectangle may have an outline, a fill or both. Rectangles are created with the following widget command:

  pathName insert index rectangle options

After the rectangle keyword there may be an number of option-value pairs, each of which sets one of the configuration options for the item. These same option-value pairs may be used in itemconfigure widget commands to change the item's configuration. A rectangle item becomes the current item when it is displayed in the center (magnified) of the carousel widget.

The following standard options are supported by ovals:

  -ratio
  -dash
  -fill
  -offset
  -outline
  -outlineoffset
  -outlinestipple
  -stipple
  -state
  -width

OVAL ITEM

Items of type oval appear as circular or oval regions in the carousel. Each oval may have an outline, a fill or both. Ovals are created with the following widget command:

  pathName insert index oval options

After the oval keyword there may be an number of option-value pairs, each of which sets one of the configuration options for the item. These same option-value pairs may be used in itemconfigure widget commands to change the item's configuration. An oval item becomes the current item when it is displayed in the center (magnified) of the carousel widget.