The [popover] command.

Introduction

The popover command lets you create and manipulate popover windows. They are transient windows used to display additional content related to existing content on the screen. A popover is positioned relative to the existing content.
The system automatically positions each popover relative to a positioning view or to some rectangle area within the positioning view.
Popover windows can be automatically closed in response to user interactions: they can be transient, semi-transient or application-defined (see the -behavior option).
They can optionally be detached to become a separate window when they are dragged from their current position (see the -detachable option). The detached window displays the exact same contents as the popover itself but it remains visible until it is explicitely closed.

Synopsis

The formal syntax of the [popover] command is:

popover subcommand ?options?

The possible subcommands are described below. Depending on the subcommand, some options may be specified.

Popover subcommands

The [close] subcommand

This subcommand lets you close a popover. The complete syntax is:

    popover close token

User interactions can automatically close the popover depending on the -behavior option. However this command provides a means to do so programmatically. If the popover has been detached, this command closes the detached window instead.

The [configure] subcommand

This subcommand lets you get or set some properties of a popover. The syntax can take two forms:

    popover configure token option
    popover configure token option value ?option value...?

In the first form the command returns the current value of the specified option. In the second form, it lets you set the value of one or several options.
The available options are described in the Popover options section below.

The [create] subcommand

This subcommand creates a new popover. The complete syntax is:

    popover create ?option value? ?option value...?

It returns a token which can be used in the other popover subcommands. The possible options are described in the Popover options section below.

The [delete] subcommand

This subcommand lets you delete a popover. The complete syntax is:

    popover delete token

This also deletes the detached window if the popover was detached by the user. After deletion, the token is no longer valid.

The [detached] subcommand

This subcommand tells whether the popover is currently detached. The complete syntax is:

    popover detached token

The command returns 1 if the -detachable option is set to 1 and if the popover is actually detached and the detached window is visible. It returns 0 otherwise.

The [list] subcommand

This subcommand returns the list of the currently existing popover tokens. The syntax is:

    popover list

The [show] subcommand

This subcommand lets you display a popover. The complete syntax is:

    popover show token ?-c? ?-rect {l b w h}? ?-parent viewToken? ?-edge num?

The popover to display is specified by its token. The options have the following meaning:

the -c option only makes sense if the popover is attached to a document window. By default, the popover is attached to the current text pane, but if the -c option is specified it is attached to the window's content view.
the -edge option lets you specify the edge of the positioning view the popover should prefer to be anchored to. See the possible values below.
the -parent option lets you specify the view relative to which the popover should be positioned. If it is not specified and if a document window is opened, the current text pane or the content view of this window is used by default (see option -c).
the -rect option lets you specify a sub area within the positioning view. If it is not specified, the entire frame of the positioning view is used. This rectangle may have been set already with the [popover create] or [popover configure] commands.

The possible values for the -edge option are:

Name	Value	Description
Min X Edge	0	left edge
Min Y Edge	1	bottom edge
Max X Edge	2	right edge
Max Y Edge	3	top edge

Popover options

Here is the description of the various options which can be passed to the [popover create] or the [popover configure] commands:

-animates: the -animates option is a boolean that specifies if the popover is to be animated when it shows, closes, moves, or appears to transition to a detachable window. The default value is 1.
-behavior: the -behavior option specifies how the popover is dismissed. See the possible values below. The default value is 1 (transient behavior).
-closeProc: the -closeProc option specifies a Tcl proc to execute when the popover closes. If the popover is detached, this proc is executed when the user closes the detached window. The Tcl proc takes one argument which is the popover's token.
-detachable: the -detachable option tells whether the popover can be turned into a detached window by dragging. The default value is 0.
-oneShot: the -oneShot option tells whether the popover is meant to be used only once. If it is set to 1, the popover is immediately released when it is closed and its token becomes invalid, which means that there is no need to call the [popover delete] command. If the popover has been detached, the window itself is automatically released when the user clicks on the close button. The default value is 0.
-rect: the -rect option returns the positioning rectangle within the positioning view. This is a read-only option. In order to display a popover at a given position use the -rect option of the [popover show] command.
-shown: the -shown option tells if the popover is currently displayed. This is a read-only option.
-size: the -size option specifies the content size of the popover. Its value is a two elements list containing the width and height of the popover.
-view: the -view option is the token of a view used as the content of the popover. This token is typically obtained with the [view create] command. This view is a content view and is not to be confused with the positioning view specified with the -parent option of the [popover show] command.

The possible values for the -behavior option are:

Name	Value	Description
ApplicationDefined	0	The code is responsible for closing the popover.
Transient	1	The system closes the popover when the user clicks outside the popover.
Semitransient	2	The system closes the popover when the user clicks in the window outside the popover's positioning view.

Examples

See examples of use in the test files for the [popover] command located in the application's bundle. In particular, popover_test.tcl and popoverTestsCommon.tcl.

Last updated 2020-01-09 09:48:57